Docker : Oracle REST Data Services (ORDS) on Docker

This article describes a simple build for running Oracle REST Data Services (ORDS) on Docker.

Assumptions
Build the Image
Run a Container
Persistent Storage
start.sh Script
healthcheck.sh Script
Managing the Container

Assumptions

This article assumes the following.

You already have a suitable installation of the Docker Engine. Oracle products are supported on Docker if the host OS is Oracle Linux 7, but you don't need to use an OL7 host for this to work. You can see how to install Docker on OL7 here.
You have a basic understanding of Docker and Dockerfiles. You can read an introduction to Docker here, and some basics about writing Dockerfiles here.
You understand this is an example of a Dockerfile to build an image to run Oracle REST Data Services (ORDS). It's not meant to be a definitive or supported build. If you want something more generic, you might was to check out the builds and images from Oracle here.
You have an Oracle database with the appropriate APEX version installed with the appropriate network connectivity. This can be on a physical machine, a virtual machine, or running in a separate Docker container, as described here.

Build the Image

The Dockerfile and scripts this article is based upon can be found here. The build expects the following file system.

$ tree
.
├── Dockerfile
├── README.md
├── scripts
│   ├── healthcheck.sh
│   ├── install_os_packages.sh
│   ├── ords_software_installation.sh
│   ├── server.xml
│   └── start.sh
└── software
    ├── apache-tomcat-9.0.39.tar.gz
    ├── apex_20.2_en.zip
    ├── OpenJDK11U-jdk_x64_linux_hotspot_11.0.9_11.tar.gz
    ├── ords-20.2.0.178.1804.zip
    ├── put_software_here.txt
    └── sqlcl-20.2.0.174.1557.zip

$

You will have to download the software yourself and place it in the "software" directory.

The Dockerfile contains some basic instructions, which will be described further here.

With all the files in place you can build the image using the following command.

$ #Docker
$ docker build -t ol7_ords:latest .

$ #Podman
$ podman build --format docker -t ol7_ords:latest .

The build performs the following actions.

The build starts by defining some environment variables. The first section contains fixed environment variables. If you want to alter any paths or software versions they need to be reflected here. The next section defines those environment variables that can be set at runtime to alter the database connection details and passwords.
The software and scripts are copied to the correct locations in the image, "/u01/software" and "/u01/scripts" respectively.
The first RUN operation unzips all the software into the relevant locations, removes the original media to save space in the image, creates the "tomcat" user and sets the correct permissions.
After switching to the "tomcat" user we expose the ports to allow external connections to the application server, and reference the "healthcheck.sh" and "start.sh" scripts for use when a container is run based on this image.

You will notice the build phase doesn't configure ORDS. That is done on the first run of a container.

Run a Container

ORDS is configured each time the container is started. If it is the first time ORDS has been configured on the database, ORDS is installed. If this is a newer version of ORDS than on the database, the ORDS installation on the database is upgraded. If the ORDS versions match, the configuration gracefully completes with no work done. As a result we don't need to worry about testing to see if the configuration has already been completed and we don't have to worry about persistent storage.

The ORDS container must connect to an existing database containing the correct version of APEX. In the following example we use the default values for all the credentials, but amend the database hostname.

$ docker run -dit --name ol7_ords_con \
             -p 8080:8080 -p 8443:8443 \
             -e "DB_HOSTNAME=my-server.localdomain" \
             ol7_ords:latest

If the database were running on another container, as described here, we could connect directly to that container using a Docker network.

$ docker run -dit --name ol7_ords_con \
             -p 8080:8080 -p 8443:8443 \
             --network=my_network \
             -e "DB_HOSTNAME=ol7_183_con" \
             ol7_ords:latest

In reality we would expect to alter the database and ORDS credentials during the run using environment variables, as shown below.

$ docker run -dit --name ol7_ords_con \
             -p 8080:8080 -p 8443:8443 \
             --network=my_network \
             -e "DB_HOSTNAME=ol7_183_con" \
             -e "DB_PORT=1521" \
             -e "DB_SERVICE=pdb2" \
             -e "APEX_PUBLIC_USER_PASSWORD=ApexPassword2" \
             -e "APEX_TABLESPACE=SYSAUX" \
             -e "TEMP_TABLESPACE=TEMP" \
             -e "APEX_LISTENER_PASSWORD=ApexPassword2" \
             -e "APEX_REST_PASSWORD=ApexPassword2" \
             -e "PUBLIC_PASSWORD=ApexPassword2" \
             -e "SYS_PASSWORD=SysPassword2" \
             ol7_ords:latest

In the previous examples the storage is not persistent, so if the container were removed the configuration in the CATALINA_BASE would be lost also. We can solve this problem by creating a directory on the host file system and mounting it to the CATALINA_BASE in the container. Now the files reside outside the container. See the Persistent Storage section about the setup of the host volume.

$ docker run -dit --name ol7_ords_con \
             -p 8080:8080 -p 8443:8443 \
             --network=my_network \
             -v /u01/volumes/ol7_19_ords_tomcat:/u01/config/instance1 \
             -e "DB_HOSTNAME=ol7_183_con" \
             ol7_ords:latest

Persistent Storage

If you are using an external host volume for persistent storage, the build expects it to be owned by a group with the group ID of 1042. This is described here.

Docker : Host File System Permissions for Container Persistent Host Volumes

start.sh Script

The start.sh script is responsible for configuring ORDS on the first run of the container. It performs the following actions.

Defines the "gracefulshutdown" function to turn off the application server and associates it with the SIGINT, SIGTERM and SIGKILL traps.
Creates the "ords_params.properties" file with all the parameters necessary to perform a silent configuration.
Uses SQLcl to test if the database is available. The script will not continue until the database connection can be made.
Configures ORDS in the normal way.
Creates a keystore to configure HTTPS.
Amends the KEYSTORE_DIR and KEYSTORE_PASSWORD placeholders in the copy of the Tomcat "server.xml" file and copies it into place.
Starts Tomcat.
Tails the "catalina.out" file as a background process and waits on the resulting process ID. If this tail ends the container will be turned off.

healthcheck.sh Script

At the time of writing, the healthcheck.sh script always returns "0" to say successful. This will be revised later.

Managing the Container

Once the container is running you can connect to a bash shell using the following command.

$ docker exec -it ol7_ords_con bash

The container can be stopped and started using the following commands. The "--time" parameter give the application server a chance to shutdown gracefully.

$ docker stop --time=15 ol7_ords_con
$ docker start ol7_ords_con

The following command removes the container and the associated volumes. Persistent storage is not required for the application server, so there is no harm doing this and running the container again.

$ docker rm -vf ol7_ords_con

For more information see:

Hope this helps. Regards Tim...

Back to the Top.