# 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
```