launch your ORACLE APEX Instance in a Docker Container
One of the most important aspects of the Software Development Process is having an application that can run inside a Docker container to streamline the app release process. This allows for the creation and destruction of instances easily without the need to redo all the configurations (Oracle Database, ORDS, APEX, etc.).
In this blog, I will guide you step by step on launching your APEX instance inside a Docker container.
Requirements
- You should have Docker or Podman installed.
- We will use Oracle Container Registry to use the base images:
— Oracle XE : Oracle Database Express Edition
— ORDS : Oracle REST Data Services (ORDS) with Application Express
Oracle XE
In this section, we will attempt to start an Oracle XE container step by step using the following instructions.
We will attempt to pull the container with the latest version. You can choose a specific version by replacing the tag “latest” with your preferred version.
docker pull container-registry.oracle.com/database/express:latest
Let’s verify that the Oracle XE image has been successfully pulled
docker images
It is advisable to create a network in a Docker environment so that our containers can communicate with each other using a hostname
docker network create apex-network
At this point, we have completed all the necessary steps, and we can now execute the command to run Oracle Database XE in a Docker container on our laptop
docker run -d --name apex_db --hostname apexhost --network=apex-network -p 1522:1521 container-registry.oracle.com/database/express:latest
details:
- -d: Run the container in detached mode, which means it will run in the background, allowing you to continue using the terminal without being directly connected to the container’s console.
- --name apex_db: Assign a specific name to the Oracle XE container using the --name option. This allows you to refer to the container more conveniently in various Docker commands and operations.
- --network=apex-network: Launch the container on the ‘apex-network’ network instead of the default network using the — network option. This helps segregate and control network communication, providing a more organized and isolated environment for the container.
- -p 1522:1521: Map the host port (1522) to the container port (1521 Oracle Listener), establishing a connection between the specified ports on the host and container.
When the container is started, a random password is used for the SYS, SYSTEM and PDBADMIN users.
Let’s verify that our container is started with success
docker ps
As you can see in the picture, the container status is (starting), indicating that the container is still in the process of starting. Once it is ready for use, the status will be updated to (healthy). In the event of a failure, it will be updated to (failed)
The next step is to check that the database is running without any issues by executing a simple SQL query.
So lets connect to the database using this docker exec command
docker exec -it apex_db sqlplus / as sysdba
show pdbs
With the show pdbs command you will check the status of your pdbs
To change the To change the password , use the docker exec command, to run the setPassword.sh script that is found in the container.
Note that the container must be running before you run the script.
docker exec apex_db ./setPassword.sh hamza123
So now the new password is hamza123
You can access the database alert log by using the following command
docker logs apex_db
To connect from outside of the container using SQLPlus, run the following commands:
To connect to the database at the CDB$ROOT level as sysdba:
sqlplus sys/hamza123@//apexhost:1522/XE as sysdba
To connect as non sysdba at the CDB$ROOT level:
sqlplus system/hamza123@//apexhost:1522/XE
To connect to the default Pluggable Database (PDB) within the XE Database:
sqlplus pdbadmin/hamza123@//apexhost:1522/XEPDB1
APEX & ORDS
Until now, we haven’t installed APEX. We’ve only installed the database in a Docker container.
The next step is to start an APEX instance and link it with the Oracle XE database (apex_db).
This container will start a server instance with ORDS (Oracle Rest Data Services) and APEX (Oracle Application Express).
Execute the pull command to download the ords image
docker pull container-registry.oracle.com/database/ords:latest
At startup the container will install or upgrade ORDS and APEX in the specified database. The target default database pool for ORDS is specified in a file (conn_string.txt) that the container reads at startup.
The database connection string is necessary to install/upgrade the database components.
The file is deleted during the startup process, although you can prevent this by not granting permission.
To configure the APEX installation we have to create a directory on our laptop
mkdir ~/apex
then put the string information inside a file on this directory
echo CONN_STRING=sys/hamza123@apexhost:1521/XEPDB1 > ~/apex/conn_string.txt
please note I used the parameter apexhost of Oracle Database XE.
Note: In some cases, you may encounter issues when using the hostname (apexhost). If you encounter this problem, you can resolve it by replacing the hostname (apexhost) with the IP address.
you can retrieve the ip address using this command
docker inspect apex_db
and search for the IPAddress
CONN_STRING variable needs to be in below shape (without single quote that can happen if you are using bash shell ):
CONN_STRING=user/password@host:port/service_name
At this point, you can run the docker
docker run --rm --name apex -v /absolute_path/apex:/opt/oracle/variables --network=apex-network -p 8181:8181 container-registry.oracle.com/database/ords:latest
Change the password for APEX_PUBLIC_USER user inside the database; To do that login in a Oracle XE docker by sqlplus
sqlplus sys/hamza123@//apexhost:1521/XEPDB1 as sysdba
and set the password
alter user APEX_PUBLIC_USER identified by eraoui123;
Now you can connect to your APEX instance
to connect, use this link
Use this information to log in to an internal workspace
Workspace: internal
Username: admin
Password: Welcome_1The END
I hope this information proves helpful, and I have thoroughly explained each step.
If there is any ambiguity, please feel free to point it out in the comments. Alternatively, you can reach me on my LinkedIn account for further clarification.
