Introduction
In this blog, we are going to show you how to install Oracle XE in a Docker container, then install ORDS and APEX. It is recommended that you have a basic knowledge of Docker and how it works.
Install Docker
First of all, you need to install docker on your machine, you can easily download and install it from the docker homepage.
Then you will need to sign up for a free account on the oracle container registry, from this registry we will pull all the docker images we will need later.
After you have Docker installed and signed up, you can follow throw with us :).
Starting Docker
After you installed Docker, you need to start docker desktop, to be able to use the docker commands.
Docker Network
We will configure a docker network, to allow communication between the DB and ORDS container. For creating a network, we simply run the following command in the Terminal or Command line:
docker network create demo-network
Now, to list the networks you have, run the following command:
docker network ls
Docker Volume
When we run our DB in a docker container all data changes are saved in the container, meaning we will lose all the data when the container gets deleted. To store the data independent from the container we can attach a volume. In this case, the data is saved on the host machine and will not be affected if we remove the container. We can later spin up a new container and mount the same volume to it.
To create a volume we run the following command:
docker volume create db-demo-volume
To list all the volumes, run the following:
docker volume ls
Download and Build Oracle XE
After installing docker, we need to download the Oracle XE docker-image. Afterward, we can spin up a container from that image, and our DB instance is ready to use.
In most cases, you will find the Docker image you need on Docker-Hub. In some cases, the image provider hosts the images on its registry, like in our example, the images are hosted on an Oracle registry.
To pull the Oracle XE image, sign in to the Oracle registry using the account you created. You can do that by running the following command:
docker login container-registry.oracle.com
After a successful login, you will see the following message
Then we run the following command to pull the latest Oracle XE image (As of today 21c 21.3.0):
docker pull container-registry.oracle.com/database/express:latest
To make things easy we will tag this image and give it a short name (oracle-xe-21.3):
docker image tag container-registry.oracle.com/database/express:latest oracle-xe-21.3
docker rmi container-registry.oracle.com/database/express:latest
You can list the images to see what images you have:
docker images
Now we can spin up a container from that image by running the following command:
docker run -d --name db-container\
> -p 1521:1521\
> -e ORACLE_PWD=1230123\
> -v db-demo-volume:/opt/oracle/oradata\
> --network=demo-network\
> --hostname database
> oracle-xe-21.3
The first flag -d will run the container in a detached mode.
The parameter --name specifies the container name.
-p maps the port 1521 on the host machine to the port 1521 in the container, so we can connect to the database.
With -e we can pass environment variables. In this case, ORACLE_PWD set the password for the SYS, SYSTEM, and PDB_ADMIN users.
-v mounts the volume we created for the oradata files in the container.
--network connects the container to the network we created.
--hostname give a name to the DB server.
The last parameter is the image we want to use to spin up the container.
After the command finishes, you should see this message:
Now if you go to SQL Developer, you can connect to the Database just like shown below:
The password in our example is 1230123.
Download and build ORDS and APEX
Now we will pull the ORDS image from the Oracle registry, to do that run the following command:
docker pull container-registry.oracle.com/database/ords:latest
We will tag the image to make the name shorter:
docker image tag container-registry.oracle.com/database/ords:latest ords-21.4
docker rmi container-registry.oracle.com/database/ords:latest
For ORDS to connect to the database, it has to know the hostname where the DB is running, the password to use when connecting, and the service name. So, we will create a file on our host machine and save the connection string variable in it. When we spin up an ORDS container, we will mount this file to the container, and ORDS will use the connection string variable to connect to the DB. In this demo, we will create a folder on the desktop and name it ORDS, create a file in the ORDS folder and name it conn_string, in the file, we will store the connection string variable.
echo 'CONN_STRING=sys/1230123@database:1521/XEPDB1'>conn_string.txt
Please note that the connection string variable has to be in the following format:
conn_string=username/password@hostname:port/service
The hostname of our DB is database, which we gave it as we initialized the container and the password is 1230123.
For Windows Users, you need to remove the quote signs from the conn_string variable. Create a file and write the connection string variable like this:
CONN_STRING=sys/1230123@database:1521/XEPDB1
Now, we spin up an ORDS container by running the following command (You have to modify the 4th line so you point to where you saved the connection string file):
docker run -d --name ords
--network=demo-network
-p 8181:8181
-v /Users/mohamadbouchi/Desktop/ords:/opt/oracle/variables
ords-21.4
If you are using Windows then the command line then the command would be:
docker run -d --name ords
--network=demo-network
-p 8181:8181
-v C:\Users\mohamadbouchi\Desktop\ords:/opt/oracle/variables
ords-21.4
The first flag -d will run the container in a detached mode.
The parameter --name specifies the container name.
-p maps the port 8181 on the host machine to the port 8181 in the container, so we can connect to APEX.
-v moves the connection string file to /opt/oracle/variables in the container.
--network connects the container to the network we created.
The last parameter is the image we want to use to spin up the container.
Please notice, that we are attaching our network to the ORDS container, so both the DB container and ORDS container are running in the same network. And also we are mounting the folder where our connection string is stored to the container.
This will take a few minutes because it will install APEX in the DB, you can monitor the installation by running the following command in a new Console/Terminal window:
docker exec -it ords tail -f /tmp/install_container.log
When the APEX installation finishes, you can open APEX in your browser using the following link:
localhost:8181/ords/
Use the following credentials to connect to the Internal Workspace:
Workspace: Internal
Username: Admin
Password: Welcome_1
Removing the Containers
After you finish, you may want to stop or remove the containers to free up system resources.
To stop the container you can simply run the following command
docker stop
At a later point you can start the container again with:
docker start
You can remove the container completely by running
docker rm
Since we are using volumes, our data will remain and we can mount it on different containers, or you can delete the volume, you can do that by running
docker volume rm
Finally to remove the network
docker network rm
We hope you found this post useful :).