ORDS Developer Docker Image.

Description

This container will start a server instance with ORDS (Oracle Rest Data Services) and APEX (Oracle Application Express). 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 the container is intended to be removed when the container stops the ORDS and APEX database components will remain in the database available for other ORDS instances.

Note: This image is purposefully built to quickly start a developer environment with ORDS and APEX, as such it is unsupported and should not be used in a production environment for that please refer to the ORDS image https://container-registry.oracle.com/ords/ocr/ba/database/ords.

• A mid-tier Java application, ORDS provides a Database Management REST API, SQL Developer Web, a PL/SQL Gateway, SODA for REST, and the ability to publish RESTful Web Services for interacting with the data and stored procedures in your Oracle Database. See https://www.oracle.com/rest for more information.

• Oracle Application Express (APEX) is a low-code development platform that enables you to build scalable, secure enterprise apps, with world-class features, that can be deployed anywhere. See https://apex.oracle.com/ for more information.

Version matrix

Each image uses Oracle Linux with a specific version of ORDS and APEX. When an image is published it is tagged with the ORDS version it contains. In general, the version of APEX included in the image is the released version publicly available at the time the image was created. It is advised to always use the image with the latest tag so that the most recent ORDS and APEX is used.

• 24.4.0 - ORDS 24.4.0 and APEX 24.1.0

Pulling the image

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

Installing ORDS on your DB.

Using the image for the first time, create a directory for the conn_string.txt file which will hold the connection string that the container will use. That directory will be mapped as a specific volume when starting the container. The below command will create conn_string.txt with user/password@hostname:port/service_name specified in the CONN_STING. Replace user, password, hostname, port, and service_name with the actual database connection details. Also, you can create a docker volume or directory for ORDS configurations.

mkdir ords_secrets ords_config
chmod 777 ords_config
echo 'CONN_STRING=user/password@hostname:port/service_name' > ords_secrets/conn_string.txt

Run the container...

docker run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords-developer:latest   

Replace the container name, directory name and host port number as appropriate.

Note: If you have doubts about connection strings or credentials please check the Important Notes section.

Using an ORDS configuration volume.

You can set a configuration mount with your ORDS configurations pointing to /etc/ords/config and the container will try to start the service with configurations on the mount point.

Run the container with ords configurations mount ...

docker run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords-developer:latest

Note: If you start by the second time your container and you have provided a volume for configuration the first time, is not necessary to provide again the connections string file, The container will start ORDS with the configuration saved on configuration volume. But if you provide both, a configuration volume and connections string file, The container before starting ORDS will validate if APEX is installed or need to be upgraded and then will reconfigure this APEX if is necessary and then start ORDS.

Start ORDS with a preset configuration.

To run the container without installing/upgrading your DB, do not provide the conn_string.txt and provide a config folder with a valid configuration.

docker run --rm --name ords -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords-developer:latest

Set an SSL configuration.

To start a secure service on the ORDS container, create a folder called "ssl", put your Certificate and Key files in this folder, the files needs to be named "cert.crt" and "key.key".

mkdir -p ords_config/ssl
cp cert_file.crt ords_config/ssl/cert.crt
cp key_file.key  ords_config/ssl/key.key

Start the service with the configuration volume ...

docker run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords-developer:latest   

If the container detects the certificate and key files it will start the ORDS service on secure mode.

Custom scripts.

If you need to run a custom script on the container you can add a volume with shell scripts pointing to /ords-entrypoint.d.

docker run --rm --name ords -v /custom_scripts_path/:/ords-entrypoint.d/ -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ord-developer:latest   

The ontainer will install/upgrade APEX and ORDS and before start the ORDS service will run alphabetically all the shell scripts on /ords-entrypoint.d.

Login to APEX

Open browser on localhost with the mapped port by docker (http://localhost:8181/ords) and use below credentials:

- Workspace: internal
- User:      ADMIN
- Password:  Welcome_1

It is strongly recommend that this password is changed.

Start container with IGNORE_APEX variable

Setting up the IGNORE_APEX=TRUE variable, the container will not install, upgrade or configure Oracle APEX on your Database.

docker run --rm -e IGNORE_APEX=TRUE --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -p 8181:8181 container-registry.oracle.com/database/ords-developer:latest   

Important Notes

• The conn_string.txt file is mandatory and must be mounted on /opt/oracle/variables/ directory in the container
• The CONN_STRING variable in that file must in this format: CONN_STRING=user/password@hostname:port/service_name
• The conn_string.txt file will be deleted when the container starts. The database connection details are not held in environment variables in the container.
• The database credentials specified must have SYSDBA access because this is the database account that will be used to install/upgrade APEX and ORDS database components.
• If the database already has an earlier version of APEX installed the container will upgrade it to the version packaged in the container. That is if the major versions of the release are the same. For compatibility in the upgrade process, should the major versions of the APEX release not be the same then the container will stop.