Skip to content

Latest commit

 

History

History
333 lines (293 loc) · 15.9 KB

README.md

File metadata and controls

333 lines (293 loc) · 15.9 KB
Raw

Install & Run Oracle APEX in a Docker Environment

Docker Docker-Compose Oracle Oracle-APEX

Why This Repository

So far, with the manuals both on Oracle's website as well as the ones found on blogs etc. I never really succeeded in putting up the APEX stack on docker.

However, starting to try with some more (docker) experience after procrastinating APEX in the recent 3 years, and with new energy, I found some key hints about getting it done.

Content

This docker project contains the following:

TL;DR

Here's the recipe to get this done:

  1. Create folders
  2. Initialize Express DB
  3. Setup APEX in the Express DB
  4. Download APEX files
  5. Create & Run Docker Compose
  6. Optional: Access APEX from WAN with HTTPS / Reverse Proxy

Detailed Instructions

Prerequisites

Image Sources

I wanted to use the following images:

The ords-developer image does not contain and install APEX, but there's a solution.

Naming Conventions

A few remarks about the names of objects: I generally try to name docker containers, networks etc. by using prefixes so I can identify them easier in, e.g., lists (docker ls ...) or when searching for their repositories (directories).

In this context, rad is short for Rapid Application Development, and, since there are several platforms, oracle-apex is the second prefix. expressand ords are then the specifying parts of the name.

In the case of docker service names, I use only express and ords because those service names are referred to only within the compose file.

Prepare Directories For Persistent Data

Start in the docker project's direcctory.

Express

mkdir -p ./express/oradata && \
mkdir -p ./express/scripts/startup && \
mkdir -p ./express/scripts/setup

ORDS

mkdir -p ./ORDS/variables && \
mkdir -p ./ORDS/config

Create & Run Express Container to Setup Persistent DB

Create .env file containing a ORACLE_PWD variable and a password (do not use special characters, only numbers, small and caps for compatibility reasons):

ORACLE_PWD=<password without quotes of any kind>, e.g., 1230321abcABC.

Then run the following command to

  • create and run the container rad-oracle-apex-express
  • set up a persistent database (stored in ./express/oradata)
docker run \
	-d \
  --name rad-oracle-apex-express \
	--network rad-oracle-apex \
	--hostname express \
  --env-file ./.env
	-p 1521:1521 -e ORACLE_PWD=${ORACLE_PWD} \
	-v $(pwd)/express/oradata/:/opt/oracle/oradata \
	container-registry.oracle.com/database/express:latest

Note

Note that running the container for the first time (initialization of persistent data) takes a long time - on my Synology DS918+, it took ~2.5hrs.

Run Temporary ORDS-Developer Container to Setup/Install APEX in the Express DB

Create the file conn_string.txt in the directory ./ORDS/variables with the following content:

CONN_STRING=sys/<ORACLE_PWD>@<express hostname>:1521/XEPDB1

Replace <ORACLE_PWD> with the password from the .env file and the <hostname> with the express container's hostname (express), e.g.:

CONN_STRING=sys/<ORACLE_PWD>@express:1521/XEPDB1

E.g.,

CONN_STRING=sys/1230321abcABC@express:1521/XEPDB1

Then run the following command to

  • create and run the container rad-oracle-apex-ords-temp
  • install APEX in the Express
docker run \
	-d \
	--name rad-oracle-apex-ords \
	--network rad-oracle-apex \
    -v $(pwd)/ORDS/config:/etc/ords/config \
	-v $(pwd)/ORDS/variables:/opt/oracle/variables \
	-p 8181:8181 \
    container-registry.oracle.com/database/ords-developer:latest

If you want to check, run the command as is, and open http://<docker-host>/ords:8181 to see whether the APEX environment has been installed successfully.

Login:

  • Workspace: internal
  • User: ADMIN
  • Password: Welcome_1

After successful check, the container can be stopped and removed (docker stop <container-name> && docker rm <container name>).

If you don't want to check right now, add the line --rm`\ after -d \ in order to remove the temporary container after APEX is installed.

Finalize Setup

Download & Extract APEX Files

mkdir ./apex && \
cd ./apex && \
curl -o apex.zip https://download.oracle.com/otn_software/apex/apex-latest.zip && \
unzip -q apex.zip

Set The APEX Directory In The ORDS Container

Important

Run the ORDS container once in order to update the config with the installed APEX files:

docker run --network --rm -it \
 -v $(pwd)/ORDS/config:/etc/ords/config: \
 -v $(pwd)/apex/:/opt/oracle/apex/ \ 
 container-registry.oracle.com/database/ords:latest \
 config set standalone.static.path /opt/oracle/apex/images

Reason: The ords image does not contain the APEX files.

Run Docker Compose for APEX

services:
  express: # XE database
    image: container-registry.oracle.com/database/express:latest # 21.3.0-xe
    container_name: rad-oracle-apex-express
    # hostname: oracledev
    restart: unless-stopped
    environment:
      - ORACLE_PWD=${ORACLE_PWD} # make sure the declaration is in the .env file as ORACLE_PWD=<your password, non complex, min. 8 chars small, cap, & numbers>
    networks:
      - apex
    #ports:
    #  - 1521:1521
    #  - 5500:5500
    # depends_on:
    #   - oracle-ords
    volumes:
      - ./express/oradata:/opt/oracle/oradata
      - ./express/scripts/setup:/opt/oracle/scripts/setup
      - ./express/scripts/startup:/opt/oracle/scripts/startup
    #healthcheck:
    #  #test command below is with grep because in my case, the output of checkDBstatus.sh is always "The Oracle base remains unchanged with value /opt/oracle" which seems to indicate the DB is fine.
    #  test: /opt/oracle/checkDBStatus.sh | grep -q 'remains unchanged'
    #  interval: 30s
    #  timeout: 10s
    #  retries: 10
    #  #  start_period: 120s not working on Synology NAS

  ords:
    #image: container-registry.oracle.com/database/ords-developer:latest
    image: container-registry.oracle.com/database/ords:latest
    container_name: rad-oracle-apex-ords
    restart: unless-stopped
    #depends_on:
    #  express:
    #    condition: service_healthy
    volumes:
      - ./ORDS/variables:/opt/oracle/variables
      - ./ORDS/config:/etc/ords/config
      - ./apex/:/opt/oracle/apex
    networks:
      - apex
    ports:
      - 8080:8080

networks:
  apex:
    name: rad-oracle-apex

Log Into APEX Workspace

  1. Go to your instance's APEX homepage, e.g., http://<docker-host>.
  2. Select Oracle APEX (the middle pane)
  3. Login:
    • Workspace: internal
    • User: ADMIN
    • Password: Welcome_1

Warning

If you changed the password during log-in check from running the temporary ORDS-Developer container, use the updated password!

Log Into APEX Administration

  1. Go to your instance's APEX homepage, e.g., http://<docker-host>.
  2. Select Oracle APEX (the middle pane)
  3. Go to the bottom of the page and select Administration in the Tasks column
  4. Login:
    • User: admin
    • Password: The one you changed the default password Welcome_1 to

SQL Developer Web (SDW): Set Up & Log In

Well, that's a whole different story: The workspace/database schema needs to be enabled for SDW as follows:

  1. Log into the express container's CLI:
    • To get to the SQL prompt directly: docker exec -it oracle-apex-express sqlplus sys/<ORACLE_PWD>@//localhost:1521/XEPDB1 as sysdba
    • Via shell: docker exec -it oracle-apex-express sh and then enter sqlplus sys/<ORACLE_PWD>@//localhost:1521/XEPDB1 as sysdba at the prompt
  2. Now, the following must be entered: 
    BEGIN
 ords_admin.enable_schema(
  p_enabled => TRUE,
  p_schema => 'schema-name',
  p_url_mapping_type => 'BASE_PATH',
  p_url_mapping_pattern => 'schema-alias',
  p_auto_rest_auth => NULL
 );
 commit;
END;
/

Important

E.g.,

BEGIN
 ords_admin.enable_schema(
  p_enabled => TRUE,
  p_schema => 'WORKSPACE1',
  p_url_mapping_type => 'BASE_PATH',
  p_url_mapping_pattern => 'workspace1',
  p_auto_rest_auth => NULL
 );
 commit;
END;
/
  1. Optional: Verify if schema (= value used for p_schema) has been enabled with select username from all_users order by username
  2. Change user password via SQL prompt: alter user <user> identified by <password>; (replace <user) - every workspace, in the database, is basically a user, hence this step
  3. Go to http(s)://<domain name>/ords/sql-developer and log in with the credentials used above

Warning

There seems to be a bug in ORDS which prevents objects from loading in SDW's Data Modeler and SQL Navigator. The DB user (equals workspace name) therefore needs to be granted resource permissions as follows:

grant <privilege> to <user>

This solution might work, with me, it didn't. However, the ORDS update from Nov. 8, 2024, solved the issue.

Access APEX from WAN with HTTPS / Reverse Proxy

Put the following 2 lines into ./ORDS/config/global/settings.xml, replacing <your apex domain, no trailing slash> with your domain's name:

<entry key="security.externalSessionTrustedOrigins">http://<your apex domain, no trailing slash>, https://<your apex domain, no trailing slash>:443</entry>
<entry key="security.forceHTTPS">true</entry>

The complete settings.xml might now look similar to:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>Saved on Mon Oct 21 16:07:13 UTC 2024</comment>
<entry key="database.api.enabled">true</entry>
<entry key="db.invalidPoolTimeout">5s</entry>
<entry key="debug.printDebugToScreen">true</entry>
<entry key="standalone.static.path">/opt/oracle/apex/images</entry>
<entry key="security.externalSessionTrustedOrigins">http://<your apex domain, no trailing slash>, https://<your apex domain, no trailing slash>:443</entry>
<entry key="security.forceHTTPS">true</entry>
</properties>

Docker Installation Sources

Sources used for new attempt

Sources used years ago

... and a few more.

APEX Programming

Integration With 3rd Party Tools

Footnotes

  1. See also https://docs.oracle.com/en/database/oracle/oracle-database/21/sqpug/slash.html ↩