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.
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.3
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; the default database listener port is published, too.
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.3 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. In case the following command fails, and the last line of output you see is the certificate name, ensure that ORDS can access the certificate and key. It is assumed t hat you stored the certificate and key in your current working directory. Adjust the volume bind accordingly if they are stored elsewhere.
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.3 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.
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.3 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 --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 \
--publish 27017:27017 \
container-registry.oracle.com/database/ords:24.2.3 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
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.
Martin is a product manager at Oracle helping customers in Europe and around the world address their IT related problems. He is most interested in cloud technology, DevOps and how these can be used best with Oracle technology.