# Oracle REST Data Services (25.2.0) 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 data and stored procedures in your Oracle Database. See https://www.oracle.com/rest for more information. ## IMPORTANT ANNOUNCEMENT Beginning with ORDS version 25.1.0, the `ords-developer` image is deprecated. This `ords` image has changed substantially. Please read this document to learn the latest changes. ## Using This Image ### Starting an Oracle REST Data Services Instance To start an Oracle REST Data Services instance, execute the following command where <container_name> is the name of the container and <ords-config> is a volume containing the ORDS configuration details: ```sh podman run --name <container_name> -v <ords-config>:/etc/ords/config container-registry.oracle.com/database/ords:latest ``` > **Note:** > > * Throughout this document, words enclosed within angle brackets < > indicate variables in code lines. > * To learn about advanced use cases, see: "Custom Configurations" > * This document uses podman as the prescribed container runtime, but using contemporary commands is also anticipated to work. ### Custom Configurations The Oracle REST Data Services 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 <container name> \ -p <host_port>:8443 -p <host_port>:27017 \ -e FORCE_SECURE=TRUE \ -e DEBUG=TRUE \ -e DBHOST=<your_database_hostname> \ -e DBPORT=<your_database_port> \ -e DBSERVICENAME=<your_databse_service_name> \ -e CONN_STRING=<your_database_connections_string> \ -e ORACLE_PWD=<your_database_password> \ -v [<host mount point>:]/etc/ords/config \ -v [<host mount point>:]/opt/oracle/apex \ -v [<host mount point>:]/ords-entrypoint.d:ro \ container-registry.oracle.com/database/ords:latest 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:@<CONN_STRING>". 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 <container name> \ -p <host_port>:8443 -p <host_port>:27017 \ -e FORCE_SECURE=TRUE -e DEBUG=TRUE \ -v [<host mount point>:]/etc/ords/config \ -v [<host mount point>:]/opt/oracle/apex \ -v [<host mount point>:]/ords-entrypoint.d:ro \ container-registry.oracle.com/database/ords:latest 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 This example shows how to use ORDS CLI supported commands when issuing the `podman run` command. Details on the various ORDS CLI commands can be found here (https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/24.4/ordig/about-REST-configuration-files.html#GUID-006F916B-8594-4A78-B500-BB85F35C12A0): ```sh podman run -it --rm --name <container name> \ -v [<host mount point>:]/etc/ords/config \ container-registry.oracle.com/database/ords:latest <ORDS CLI command> Parameters: -it Optional: Add an interactive tty to use ORDS interactive commands on the ORDS CLI. --rm Optional: Removes the container once the execution is complete. Prevents your database connection details from being exposed. --name: The name of the container (default: auto generated) -v /etc/ords/config The data volume to read/store the ORDS configuration. Must be writeable from within the container by the Unix "oracle" (uid: 54321) user. ORDS CLI command The ORDS command line interface commands to run. Example: "config list" will list the ORDS configuration settings stored in the /etc/ords/config volume. ``` ##### Using a 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 ports: - <port>:1521 ords-node1: hostname: ords-node image: container-registry.oracle.com/database/ords:latest environment: - DBSERVICE=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 - <apex_file_path>:/opt/oracle/apex ports: - <port>: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 ``` > **NOTE:** Running The ORDS container on podman machine or docker machine with low allocated memory can makes ORDS crashing with java out of memory errors, you can adjust the `JDK_JAVA_OPTIONS` to avoid this issue. ### Starting the ORDS container on secure port 8443 Place the SSL certificate and key files in the ORDS config volume to start the Oracle REST Data Service container in secure mode (i.e., HTTPS, port 8443). ```sh <ords_cofing_volume>/ssl/cert.crt <ords_cofing_volume>/ssl/key.key ``` Alternatively, mount the files to the /etc/ords/config/ssl directory. ```sh -v [<SSL certificate file>:]/etc/ords/config/ssl/cert.crt:ro \ -v [<SSL Key file >:]/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 not present, the container will start using the non-secure (HTTP) port 8080. ### Running Scripts prior to starting the ORDS instance Before an ORDS startup, you can configure Docker/Podman images to run scripts (.sh extensions supported). To include scripts in this directory so they run at startup, mount the directory on your host to the /ords-entrypoint.d volume. ### Accessing ORDS logs You can access the ORDS access and console logs with the following command (where <ords-node> is the name of the container): ```sh podman logs <ords-node> ```