Martins Blog

ORDS 26.3.0 container image introduces a new mandatory environment variable

As a user of the Oracle REST Data Service container image I was interested to see version 26.3.0 appear in the Oracle Container Registry (🔗container-registry.oracle.com). While testing my existing Docker Compose setup, I found a change that affects new installations: the 26.3.0 image requires the ORACLE_USER_PWD environment variable when it installs ORDS for the first time.

The variable name predates this release: the 25.4.0 image logs already mention it. The change in 26.3.0 is that you must now provide it for a new installation. By default, its value is used for the ORDS administrative and runtime accounts. You can also provide it through a readable secret file at /run/secrets/ORACLE_USER_PWD.

As per the docs:

			
Parameters:
[...]
-e ORACLE_USER_PWD:
                    Required for a new ORDS installation. By default, it is
                    used for the ORDS administrative and runtime accounts.
                    It can also be supplied through the readable Docker
                    secret file /run/secrets/ORACLE_USER_PWD.
[...]

		

Add the variable to your ORDS (compose) service; here’s the Docker Compose file I use. Remember this is a lab setup, not a production configuration. It uses ORDS 26.3.0; check the registry for newer image tags for both ORDS and the database when you read this.

			
# THIS IS NOT A PRODUCTION SETUP - LAB USE ONLY!
services:
    oracle:
        image: docker.io/gvenzl/oracle-free:23.26.3
        ports:
            - 1521:1521
        environment:
            ORACLE_PASSWORD: ${ORACLE_PASSWORD:?Please provide a password for the Oracle DBA accounts}
            APP_USER: demouser
            APP_USER_PASSWORD: ${APP_USER_PASSWORD:?Please provide a password for the application user}
        volumes:
            - oradata-vol:/opt/oracle/oradata
            - ./initialisation:/container-entrypoint-initdb.d
        networks:
            - backend
        healthcheck:
            test: ["CMD", "/opt/oracle/healthcheck.sh"]
            interval: "10s"
            timeout: "5s"
            retries: 10
            start_period: "5s"
            start_interval: "5s"
    ords:
        depends_on:
            oracle:
                condition: service_healthy
        image: container-registry.oracle.com/database/ords:26.3.0
        environment:
            DBHOST: "oracle"
            DBPORT: 1521
            DBSERVICENAME: "freepdb1"
            ORACLE_PWD: ${ORACLE_PASSWORD:?Please provide a password for the Oracle DBA accounts}
            ORACLE_USER_PWD: ${ORACLE_USER_PWD:?Please provide a password for the ORDS administrative and runtime accounts}
            DEBUG: "FALSE"
        networks:
            - backend
        ports:
            - 8080:8080    # ORDS http
            - 8443:8443    # ORDS https
            - 27017:27017  # Mongo DB API
        volumes:
            - ords-config-vol:/etc/ords/config     # this docker volume contains the ORDS config
            - ./apex:/opt/oracle/apex              # use this volume mount for an automatic APEX installation
        healthcheck:
            test: curl --noproxy "localhost" -f -k http://localhost:8080/ords/ || exit 1
            interval: 30s
            timeout: 10s
            retries: 5
volumes:
    oradata-vol:
    ords-config-vol:
networks:
    backend:

		

The start_interval setting requires Docker Compose 2.20.2 or later. Depending on your SELinux settings etc, Podman users may have to adjust the volume mounts to allow the oracle user to access the files in the respective directories.

Please refer to the documentation for more information about each images environment variables:

Happy automating!

ORDS