# Oracle REST Data Services (25.2.3) Docker Image Documentation. Oracle REST Data Services (ORDS) is a mid-tier Java application that provides a Database Management REST API, the browser-based client SQL Developer Web, a PL/SQL Gateway, SODA for REST, and the ability to publish RESTful Web Services for interacting with the database objects and stored procedures in your Oracle Database. Visit the [ORDS product page](https://www.oracle.com/ords) for more details. ## Important Announcement As of ORDS version 25.1.0, the `ords-developer` image has been deprecated. Please read this document to familiarize yourself with this latest official `ords` image. ## Using This Image ### Starting an Oracle REST Data Services Instance To start an ORDS instance, execute the following command: ```sh podman run --name -v :/etc/ords/config container-registry.oracle.com/database/ords:latest ``` Where `` is the name of your container and `` is the volume that contains the ORDS configuration details. > **NOTE:** > * The above command is the most basic execution for an ORDS container; assuming a valid ORDS configuration exists in the `` volume. > * Throughout this document, words enclosed within angle brackets `< >` indicate variables in code lines. > * To learn about advanced use cases, refer to the [Custom Configurations](#custom-configurations) section. > * This document uses Podman as the prescribed container runtime, but any OCI-compatible[^1] container runtime can also be used. [^1]: [About](https://opencontainers.org/) the Open Container Initiative (OCI). ### Custom Configurations The ORDS container supports various configuration parameters to facilitate custom configurations. #### Examples ##### Run ORDS instance This example shows how you might structure a `podman run` command to run an ORDS instance, using the available ORDS installation custom configuration options. ```sh podman run -d --name \ -p :8443 -p :27017 \ -e FORCE_SECURE=TRUE \ -e DEBUG=TRUE \ -e DB_WAIT_RETRIES= \ -e DBHOST= \ -e DBPORT= \ -e DBSERVICE= \ -e CONN_STRING= \ -e ORACLE_PWD= \ -v [:]/etc/ords/config \ -v [:]/opt/oracle/apex \ -v [:]/ords-entrypoint.d:ro \ container-registry.oracle.com/database/ords:latest ```

< Click Obtaining the DBHOST, DBPORT, DBSERVICENAME, and CONN_STRING values from your running database container.

Database Hostname Port (when using the latest 23ai/free image): `podman container inspect --format "{{.Config.Hostname}}"` Database Port (when using the latest 23ai/free image):> `podman inspect --format '{{ (index (index .NetworkSettings.Ports "1521/tcp") 0).HostPort }}'` Database Servicename (when using the latest 23ai/free image): `podman logs ` *then*, search for your Pluggable Database's Name. The PDB default for 23ai is `FREEPDB1`. Connection String (also know as db.customURL) examples: Simple example: - `dbhostname:dbport/dbservicename` LDAP example: - `ldap://ldap-server:636/cn=TNSnames,cn=OracleContext,dc=my_domain,dc=com/PDBNAME`

```sh Parameters: -d Starts the container in container in detached mode --name: The name of the container (default: auto generated) -p: The port mapping of the host port to the container port. 8080 by default for HTTP 8443 if SECURE flag is TRUE 27017 for Mongo Listener -e DBHOST: The IP/Hostname of your database this needs to be reachable by the container. DBPORT and DBSERVICENAME are required. -e DBPORT: The port number where your database is listening connections. DBHOST and DBSERVICENAME are required. -e DBSERVICENAME: The database service name where you want to install and configure your ORDS. DBPORT and DBHOST are required. -e CONN_STRING: The database custom URL "jdbc:oracle:thin:@". This replaces DBHOST, DBPORT and DBSERVICENAME. -e ORACLE_PWD: The Oracle Database SYS password -e FORCE_SECURE If the FORCE_SECURE flag is TRUE and valid certificates files are not provided. at the configuration directory /etc/ords/config/ssl. The ORDS instance will not start. -e DEBUG If the DEBUG flag is set to TRUE the ORDS instance will set the config debug.printDebugToScreen true, if the flag is set to FALSE the ORDS instance will set the config debug.printDebugToScreen false. -v /etc/ords/config The data volume to use for the ORDS configuration. Must be writable from within the container by the Unix "oracle" (uid: 54321) user. -v /opt/oracle/apex Optional: A volume Oracle Application EXpress files (APEX). If this is mounted with the images folder to ORDS instance will set the standalone.static.path /opt/oracle/apex/images. Must be readable from within the container by the Unix "oracle" (uid: 54321) user. -v /ords-entrypoint.d Optional: A volume with custom scripts to be run before ORDS instance start. The scripts (*.sh) will run alphabetically. Must be readable from within the container by the Unix "oracle" (uid: 54321) user. ``` ##### Run ORDS instance using a preset configuration > **NOTE:** Setting database variables is not necessary when using this option. ```sh podman run -d --name \ -p :8443 -p :27017 \ -e FORCE_SECURE=TRUE -e DEBUG=TRUE \ -v [:]/etc/ords/config \ -v [:]/opt/oracle/apex \ -v [:]/ords-entrypoint.d:ro \ container-registry.oracle.com/database/ords:latest ``` ```sh Parameters: -d Starts the container in detached mode. --name: The name of the container (default: auto generated) -p: The port mapping of the host port to the container port. 8080 by default for HTTP 8443 (HTTPS) when the SECURE flag is TRUE 27017 for Mongo Listener -e FORCE_SECURE NOTE: The ORDS instance will not start when the FORCE_SECURE flag is set to TRUE, but valid certificate files are not provided in the /etc/ords/config/ssl configuration directory. -e DEBUG If the DEBUG flag is set to TRUE the ORDS instance will set the ORDS config debug.printDebugToScreen true. -v /etc/ords/config The data volume to use for the ORDS configuration. Must be writeable from within the container by the Unix "oracle" (uid: 54321) user. -v /opt/oracle/apex Optional: A volume for Oracle Application EXpress files (APEX). Mounting as the images folder for the ORDS instance will set the standalone.static.path to /opt/oracle/apex/images. Must be readable from within the container by the Unix "oracle" (uid: 54321) user. -v /ords-entrypoint.d Optional: A volume with custom scripts to be run before the ORDS instance starts. The scripts (*.sh) will be run alphabetically. Must be readable from within the container by the Unix "oracle" (uid: 54321) user. ``` ##### Using the ORDS CLI **Example 1:** This example shows how to use ORDS CLI commands to configure a Customer Managed ORDS (using the ADB-S service). > **NOTE:** Docker is used in this example. 1. Step 1: Create a volume, download a wallet, and create a secrets file. ```sh mkdir -p //ords_atp_config chmod 777 ords_atp_config cat secrets.txt chmod 755 password.txt ``` > **NOTE:** To download the wallet for the Autonomous Database instance, review the instructions for [Downloading Client Credentials](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/connect-download-wallet.html#GUID-B06202D2-0597-41AA-9481-3B174F75D4B1). For additional information about passwords in the secrets file, review the [Installing and Configuring Customer Managed ORDS](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/25.2/ordig/installing-and-configuring-customer-managed-ords-autonomous-database.html#GUID-AC7F9A42-A7C2-4453-B8D1-BFD2784C3CA0) documentation. 2. Step 2: Install your customer managed ORDS. ```sh cat password.txt | docker run --rm -i \ -v /ords_atp_config:/etc/ords/config \ -v /atp_wallet.zip:/atp_wallet.zip \ container-registry.oracle.com/database/ords:latest install adb --admin-user --db-user --gateway-user --wallet /atp_wallet.zip --wallet-service-name --feature-sdw true --password-stdin ``` 3. Step 3: Create an SSL self signed certificate, CN (common name) should be the domain to be requested, and it could be localhost or a FQDNS. ```sh mkdir -p /ords_atp_config/ssl openssl req -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -out /ords_atp_config/ssl/cert.crt -keyout $/ords_atp_config/ssl/key.key -subj "/C=US/ST=State/L=City/O=my_corp Corp/OU=my_unit/CN=localhost" chmod -R 777 /ords_atp_config/ssl ``` 4. Step 4: Start ORDS customer managed. ```sh docker run --rm -i \ -p 8443:8443 \ -v /ords_atp_config:/etc/ords/config \ -v /atp_wallet.zip:/atp_wallet.zip \ -v /apex_files/24.2/apex:/opt/oracle/apex \ container-registry.oracle.com/database/ords:latest ``` **Example 2:** This example shows how to use ORDS CLI commands to rotate the db password. 1. Step 1: Get the current password. ```sh docker run \ -v :/etc/ords/config \ container-registry.oracle.com/database/ords:latest config get --secret db.password ``` 2. Step 2: Update the password. ```sh docker run -it \ -v :/etc/ords/config \ container-registry.oracle.com/database/ords:latest config secret db.password ``` > **NOTE:** For more details on ORDS CLI commands see [Help Center](https://docs.oracle.com/search/?q=CLI&lang=en&category=database&product=en%2Fdatabase%2Foracle%2Foracle-rest-data-services%2F25.2). ##### Sample Compose file ```yaml name: demo services: db23: hostname: database image: container-registry.oracle.com/database/free:latest environment: - ORACLE_PDB=FREEPDB1 - ORACLE_PWD=oracle - DBHOST=database volumes: - db_files:/opt/oracle/oradata/ ports: - :1521 ords-node1: restart: on-failure hostname: ords-node image: container-registry.oracle.com/database/ords:latest environment: - DBSERVICENAME=FREEPDB1 - DBHOST=database - DBPORT=1521 - ORACLE_PWD=oracle #Modify JDK_JAVA_OPTIONS to adjust the JVM memory #- JDK_JAVA_OPTIONS=-Xms1024M -Xmx1024M volumes: - ords_config:/etc/ords/config - :/opt/oracle/apex ports: - :8080 healthcheck: test: curl --noproxy "localhost" -f -k http://localhost:8080/ords/ || exit 1 interval: 30s timeout: 10s retries: 150 depends_on: db23: condition: service_healthy volumes: ords_config: db_files: ``` > **NOTE:** Running the ORDS container on a Podman or Docker machine with JVM low memory allocation may result in the container crashing with a Java out of memory exception. You can adjust the `JDK_JAVA_OPTIONS` to avoid this issue (as seen above in the example compose.yaml file). ### Starting the ORDS container on secure port 8443 Tp start the ORDS container in secure mode (i.e., HTTPS, port 8443), place the SSL certificate and key files in the ORDS config volume. ```sh /ssl/cert.crt /ssl/key.key ``` Alternatively, mount the files to the `/etc/ords/config/ssl` directory. ```sh -v [:]/etc/ords/config/ssl/cert.crt:ro \ -v [:]/etc/ords/config/ssl/key.key:ro \ ``` > **NOTE:** The SSL certificate and key files must be readable from within the container by the Unix "oracle" (uid: 54321) user. The container will detect the files and start the ORDS service on port 8443 instead of 8080. > > **NOTE** If the `FORCE_SECURE` flag has been set to `TRUE` and certificates files are unavaialbe, the container will exit with an error. However, if both the `FORCE_SECURE` flag is unset and certificate files are unavailable/missing, the container will start using the non-secure (HTTP) port 8080. ### Running Scripts prior to starting the ORDS instance You can configure Docker/Podman images to run scripts (.sh extensions are supported) as ORDS starts up. To include scripts so they run at startup, mount the directory on your host, where these scripts are located, to the `/ords-entrypoint.d` volume. ### Accessing ORDS logs You can access the ORDS console logs with the following command (where is the name of the container): ```sh podman logs ```