Blog

Oracle recently published a new container image for running Oracle REST Data Service (ORDS). The new image externalises the ords binary, therefore greatly simplifying the process of making changes to the configuration. How does this change the way you work with the ords image? Let’s find out!

NB: the previous ORDS image has been renamed to ords-developer, and can be found on container-registry.oracle.com as well.

Getting the new image

If you like to save time you can start downloading the ORDS image from Oracle’s container registry while you read on.

docker pull container-registry.oracle.com/database/ords:24.2.2

Once the command has completed, you are almost good to go; the only missing component is a database. This post uses Oracle Database 23ai Free, ORDS will be installed into the first Pluggable Database (PDB) named freepdb1. The database container is named oraclefree. It uses a network named blogpost-net; the network is required to allow ORDS to communicate with the database. The article assumes the database container and the database are up and running.

Installing ORDS

Let’s install ORDS in freepdb1 using the non-interactive, silent installation. This requiers you to store certain credentials (the SYS password and the PDB’s future proxy user password) in a temporary password file. This article assumes they are present in a file named password.txt. If you are unfamiliar with the details of a silent installation, please refer to the ORDS documentation for more details.

The ORDS config is kept in a docker volume in the following example, you can of course use an existing configuration directory as well, but that’s out of scope of this article.

docker volume create blogpost-ords-config-vol

Let’s start the installation, remember that the ords binary marks the container entrypoint and therefore can be omitted from the command. Note that you do not need a pseudo-tty, the -t option has been omitted on purpose:

cat password.txt | docker run --rm -i 
--name ords-install 
--volume blogpost-ords-config-vol:/etc/ords/config 
--network blogpost-net 
container-registry.oracle.com/database/ords:24.2.2 install 
    --admin-user SYS 
    --proxy-user 
    --db-hostname oraclefree 
    --db-port 1521 
    --db-servicename freepdb1 
    --feature-sdw true 
    --password-stdin
rm -f password.txt

Since the ORDS configuration is stored in a docker volume it is not necessary to preserve the container after the installation completed. The ORDS installation should have been completed successfully, if not, use the command output to troubleshoot. You can now start ORDS; note how the TLS certificates are provided as well for an extra layer of security.

docker run --rm --detach 
--name ords 
--volume blogpost-ords-config-vol:/etc/ords/config 
--volume $(pwd)/certs:/media/certs 
--network blogpost-net 
--publish 8080:8080 
--publish 8443:8443 
container-registry.oracle.com/database/ords:24.2.2 serve 
--key /media/certs/ords-cert.key --certificate /media/certs/ords-cert.crt 
--secure --port 8443

A few seconds later ORDS should be listening on port 8443 to HTTPS requests.

Enable the Mongo DB API

Enabling the Mongo DB API requires an additional step it is disabled by default. Thanks to the new image it’s as simple as stopping the ORDS container, enabling the Mongo DB API, and starting the container again.

Stop the detached container first:

docker stop ords

This might take a few seconds. Enable the MongoDB API after the container stopped like so:

docker run --rm -it 
--name ords-config-change 
--volume blogpost-ords-config-vol:/etc/ords/config 
container-registry.oracle.com/database/ords:24.2.2 config set mongo.enabled true

You should see an acknowledgement in the output. Now start the container, additionally exporting the Mongo DB API Port (defaults to 27017):

docker run --rm -it 
--name ords 
--volume blogpost-ords-config-vol:/etc/ords/config 
--volume $(pwd)/certs:/media/certs 
--network blogpost-net 
--publish 8080:8080 
--publish 8443:8443 
--publish 27017:27017 
container-registry.oracle.com/database/ords:24.2.2 serve 
--key /media/certs/ords-cert.key --certificate /media/certs/ords-cert.crt 
--secure --port 8443

All that remains to be done is getting the Mongo DB API URI from the container logs:

docker logs ords | grep -A1 'MongoDB connection string'
2024-07-20T10:04:11.413Z INFO        The Oracle API for MongoDB connection string is:
         mongodb://[{user}:{password}@]localhost:27017/{user}?authMechanism=PLAIN&authSource=$external&ssl=true&retryWrites=false&loadBalanced=true

Summary

This post should have demonstrated how easy it is to use the ORDS container. Changes to the container configuration no longer require you to use docker exec, exposing the ords binary makes this task a lot easier.