I previously wrote about troubleshooting the ORDS (Oracle REST Data Services) container’s entrypoint, e.g. the script that’s run whenever an ORDS container starts. This older article is now obsolete … Beginning with ORDS 25.2.3 a new flag has been added to the container image allowing you to debug the container startup.
The new ORDS image is available from Oracle’s official container registry. You may save yourself some time by pulling it in advance:
docker pull container-registry.oracle.com/database/ords:25.2.3
If you use podman instead, substitute the it for docker, this article equally applies to both.
For obvious reasons ORDS requires a database. When starting the container make sure you have the target database ready and know all the details required to connect to it. I used an Oracle Database 23ai Free instance, also running in docker.
Enough talk already, show me how to install ORDS!
Provided the database you want to connect to is up and running, and this is the first time you’re installing or updating ORDS, here’s the command you need:
docker run \
--name some-ords \
-p 8080:8080 -p 27017:27017 -p 8443:8443 \
-v blogpost-ords-config-vol:/etc/ords/config \
--network blogpost-net \
-e DBHOST="some-oracle" \
-e DBPORT=1521 \
-e DBSERVICENAME=freepdb1 \
-e ORACLE_PWD=${ORACLE_SYS_PASSWORD} \
-e DEBUG=TRUE \
container-registry.oracle.com/database/ords:25.2.3
This is it, simple as that. The image documentation lists all the other options, including the ones to force TLS-only mode which is omitted in the above snippe to keep it simple.
Thanks to the DEBUG flag you can see the entire entrypoint script’s execution. Should something go wrong, you’ll see exactly what and why.
Here’s what I saw on my screen, although I should hasten to add there is nothing to see … move along 😀
docker run ...
container-registry.oracle.com/databaseords:25.2.3
+ _run_script
+ '[' '' = '' ']'
+ '[' '!' -z some-oracle ']'
+ '[' '!' -z 1521 ']'
+ '[' '!' -z freepdb1 ']'
+ '[' '!' -z changeOnInstall ']'
+ mkdir -p /tmp/install_logs
+ _test_sys_database
+ local MAX_RETRIES=60
+ local RETRY_DELAY=10
+ local ATTEMPT=1
+ local RESULT=1
++ _dbconnect_var
++ cut -d_ -f 3
++ '[' -n changeOnInstall ']'
++ '[' -n some-oracle ']'
++ '[' -n 1521 ']'
++ '[' -n freepdb1 ']'
++ echo conn_type_simple
+ CONN_TYPE=simple
Testing database connection...
+ case "${CONN_TYPE}" in
+ DB_URL='sys/changeOnInstall@some-oracle:1521/freepdb1 as sysdba'
+ '[' -n 'sys/changeOnInstall@some-oracle:1521/freepdb1 as sysdba' ']'
+ echo 'Testing database connection...'
+ '[' 1 -le 60 ']'
+ sed 's/changeOnInstall/*****/'
+ printf '%s%s\n' 'INFO : ' 'Attempt 1: Connecting to sys/changeOnInstall@some-oracle:1521/freepdb1 as sysdba...'
INFO : Attempt 1: Connecting to sys/*****@some-oracle:1521/freepdb1 as sysdba...
++ echo '
SET HEADING OFF FEEDBACK OFF VERIFY OFF ECHO OFF
SELECT open_mode FROM v$pdbs WHERE name = UPPER('\''freepdb1'\'');
EXIT;'
++ grep -c 'READ WRITE'
++ sql -s sys/changeOnInstall@some-oracle:1521/freepdb1 as sysdba
INFO : Database connection successful.
...
resource.templates.enabled=false
db.password=******
conf.use.wallet=true
2025-09-10T10:28:55.044Z WARNING *** jdbc.MaxLimit in configuration |default|lo| is using a value of 10, this setting may not be sized adequately for a production environment ***
2025-09-10T10:28:55.334Z INFO Created Pool: |default|lo|-2025-09-10T10-28-54.611477984Z at: 2025-09-10T10:28:54.611477984Z
2025-09-10T10:28:55.338Z INFO
Mapped local pools from /etc/ords/config/databases:
/ords/ => default => VALID
2025-09-10T10:28:55.398Z INFO Oracle REST Data Services initialized
Oracle REST Data Services version : 25.2.3.r2241517
Oracle REST Data Services server info: jetty/12.0.18
Oracle REST Data Services java info: Java HotSpot(TM) 64-Bit Server VM GraalVM EE 21.3.14 (build 17.0.15+9-LTS-jvmci-21.3-b110 mixed mode, sharing)
2025-09-10T10:28:55.461Z INFO CursorMonitor 1
Have fun!
Martins Blog 