Setting up Oracle REST Data Services (ORDS) test environment is quick and simple with Docker Compose and Oracle AI Database Free. In this article, we’ll set up a clean, consistent ORDS/APEX + Database environment in minutes using containers: No manual installs and no guesswork.
Note: This is intended as a lab setup and not a production grade installation.
I’ve previously blogged about ORDS with Oracle Autonomous AI Database Free here, however it never felt complete – the Autonomous AI Database Free image conveniently bundles ORDS, but is only available for AMD64 architectures or through emulation. This example uses two standalone containers, and runs on ARM64 or AMD64 natively!
What is ORDS?
ORDS is a free-to-use Oracle-built Java app that run separately from the database. ORDS enhances database functionality with HTTP-based services, like:
- Database administrative and schema REST APIs
- Think GET, POST, etc. requests for anything database
- AutoREST APIs for tables and views
- SQL Developer Web interface
- Wire-compatible MongoDB API
- APEX and much more!
Docker Compose Containers
You can download or copy the Docker Compose setup from GitHub here: https://github.com/anders-swanson/oracle-database-code-samples/tree/main/ords-docker-compose
The Docker Compose setup uses the following containers:
- ords: ORDS container for exposing REST APIs. The ORDS HTTP dashboard is available on
http://localhost:8888 - ordsdb: Oracle AI Database container. The database container externally accessible at
testuser/testpwd@localhost:1555/freepdb1
The setup includes pre-configured volumes for ORDS configuration and database initialization scripts.
Prerequisites
- Docker-compatible container runtime and Docker Compose installed on your system.
Directory Structure
docker-compose.yml: Main composition file defining services.oracle/: Database initialization scripts (e.g.,ords_init.sql).scripts/: initialization scripts. Used to download and install APEX from https://download.oracle.com/otn_software/apex/apex-latest.zip onto the ORDS container.ords_config/: Placeholder ORDS configuration directory. You do not need to modify this directory, ORDS will populate its configuration data here on startup.
Usage
- Clone the repo and navigate to this directory:
cd ords-docker-compose - Start the services:
APEX_ENABLED=true docker-compose up -d
% APEX_ENABLED=true docker compose up -d
[+] Running 3/3
✔ Network ords-docker-compose_default Created 0.2s
✔ Container ordsdb Started 0.3s
✔ Container ords StartedNote: if you’re not using APEX, set APEX_ENABLED=false
After a few moments, the containers will start up and become ready.
Accessing Services
- ORDS HTTP Endpoint:
http://localhost:8888/. Usetestuser/testpwdas the login information for services like SQL Developer. - MongoDB API: Port 27017 (e.g., connect using MongoDB clients to
localhost:27017). - Oracle AI Database: Connect via SQLcl or other tools to
localhost:1555/freepdb1with usernametestuserand passwordtestpwd. - APEX: Connect to APEX at
http://localhost:8888/ords/r/apex. Use WorkspaceINTERNAL,ADMIN/Welcome12345!4as the APEX admin login.
When you’re done, stop the services: docker-compose down
Understand and customize the container setup (optional)
docker-compose.yml file
Our Docker Compose file has two services, one for ORDS and another for Oracle AI Database Free. The ORDS service is configured to automatically connect to the database container:
services:
apex-download: # Download and install APEX from https://download.oracle.com/otn_software/apex/apex-latest.zip
image: container-registry.oracle.com/database/ords:latest
user: "0"
entrypoint: [ "bash", "/scripts/download-apex.sh" ]
environment:
- APEX_ENABLED=${APEX_ENABLED:-false}
- APEX_DOWNLOAD_URL=${APEX_DOWNLOAD_URL:-https://download.oracle.com/otn_software/apex/apex-latest.zip}
- APEX_DOWNLOAD_SHA256=${APEX_DOWNLOAD_SHA256:-}
volumes:
- ./apex:/apex-local:ro
- ./scripts/download-apex.sh:/scripts/download-apex.sh:ro
- apex_files:/apex-files
ords: # more info: https://container-registry.oracle.com/ords/ocr/ba/database/ords
image: container-registry.oracle.com/database/ords:latest
container_name: ords
depends_on:
apex-download:
condition: service_completed_successfully
ports:
- 8888:8080 # HTTP
- 27017:27017 # MongoDB API
environment:
- CONN_STRING=jdbc:oracle:thin:@ordsdb:1521/freepdb1
- ORACLE_PWD=Welcome12345
- APEX_PWD=${APEX_PWD:-Welcome12345}
- APEX_ENABLED=${APEX_ENABLED:-false}
volumes:
- ./ords_config:/etc/ords/config
- apex_files:/opt/oracle/apex:ro
healthcheck:
# Hack to enable TESTUSER schema for ORDS on startup
test: [ "CMD", "bash", "-c", "echo 'EXECUTE ORDS.ENABLE_SCHEMA;' | sql -s testuser/testpwd@ordsdb:1521/freepdb1" ]
interval: 20s
timeout: 10s
retries: 5
ordsdb:
image: gvenzl/oracle-free:23.26.1-slim-faststart
container_name: ordsdb
ports:
- 1555:1521
environment:
- ORACLE_PASSWORD=Welcome12345
volumes:
- ./oracle:/container-entrypoint-initdb.d
healthcheck:
test: ["CMD-SHELL", "lsnrctl status | grep READY"]
interval: 15s
timeout: 10s
retries: 5
start_period: 30s
volumes:
apex_files:
Note that the ords_config and apex_files directories are mounted to the ORDS container. This gives the container a read/write location to store temporal data.
ORDS user init.sql script
The init.sql script creates an app user for ORDS. This script and any other script in the oracle directory are mounted onto the Oracle AI Database container and run during database startup:
-- Set as appropriate for your database.
alter session set container = freepdb1;
@?/rdbms/admin/utlrp.sql
create user testuser identified by testpwd quota unlimited on users;
grant connect, resource to testuser;You can modify this script or add your own scripts to customize the database on startup.
Leave a Reply