Multiple ORDS Instances on the Same Machine

Oracle REST Data Services (ORDS) can be run in standalone mode, making it easy to serve RESTful APIs without needing a separate application server. However, when running multiple ORDS instances on the same machine, each serving HTTPS traffic on a different port, users may encounter an issue: ORDS still attempts to bind to the default HTTP port 8080.

The Issue: ORDS Listens on Port 8080 by Default

In standalone mode, ORDS can listen for HTTP, HTTPS and MongoDB Wire Protocol traffic at the same time. The port numbers that ORDS listens on are configurable:

• standalone.http.port – HTTP listen port, default 8080
• standalone.https.port – HTTPS listen port, default 8443
• mongo.port – API for MongoDB Wire Protocol listen port, default 27017

When running more than one ORDS instance on the same machine you will want to share the same configuration, but not the same port numbers. The ORDS serve command line gives you some options around that. Quite literally…

ords serve --help

ORDS: Release 24.4 Production on Mon Feb 10 21:48:05 2025

Copyright (c) 2010, 2025, Oracle.
...
Usage:
  ords serve [OPTIONS]

Launch Oracle REST Data Services in standalone mode

Options:
...
     --port <int>          HTTP listen port, default 8080

     --secure              HTTPS listen port, default 8443.   
                           Must specify options 
                           --secure --port <PORT> 
                           to use HTTPS.

This allows you to run multiple ORDS instances in standalone mode from the command specifying a different port for HTTP:

ords serve --port 8081

ORDS: Release 24.4 Production on Mon Feb 10 21:53:30 2025

Copyright (c) 2010, 2025, Oracle.
...
2025-02-10T21:53:31.005Z INFO        HTTP and HTTP/2 cleartext listening on host: 0.0.0.0 port: 8081
...
2025-02-10T21:53:34.361Z INFO        Oracle REST Data Services initialized
Oracle REST Data Services version : 24.4.0.r3451601
Oracle REST Data Services server info: jetty/12.0.13
Oracle REST Data Services java info: Java HotSpot(TM) 64-Bit Server VM  (build: 17.0.12+8-LTS-286 mixed mode, sharing)

Then in another shell window…

ords serve --port 8091

ORDS: Release 24.4 Production on Mon Feb 10 21:53:30 2025

Copyright (c) 2010, 2025, Oracle.
...
2025-02-10T21:53:31.005Z INFO        HTTP and HTTP/2 cleartext listening on host: 0.0.0.0 port: 8091
...
2025-02-10T21:53:34.361Z INFO        Oracle REST Data Services initialized
Oracle REST Data Services version : 24.4.0.r3451601
Oracle REST Data Services server info: jetty/12.0.13
Oracle REST Data Services java info: Java HotSpot(TM) 64-Bit Server VM  (build: 17.0.12+8-LTS-286 mixed mode, sharing)

That’s great for HTTP. As many ORDS instances as you like so long as you specify a unique port number for each.

For HTTPS, just add the --secure option like this:

ords serve --port 8444 --secure

Well, that would work for one instance but not for your second. By default, when ORDS runs in standalone mode, it listens for HTTP traffic on port 8080 and HTTPS traffic on the port specified by the --port argument when using ords serve --secure. This means that even if you specify a different secure port for each ORDS instance, the HTTP listener on 8080 may cause conflicts if multiple instances are running.

Could not start Standalone Mode because the listen port: 8080 is already in use by another process. Check if another instance of ords is already running

The upshot is that you can not start that second ORDS instance no mater what secure port you specify. There’s a solution…

The Solution: Disable the HTTP Listener

To avoid conflicts, you must explicitly disable the HTTP listener by setting the standalone.http.port configuration parameter to 0. This prevents ORDS from attempting to bind to port 8080 when serving HTTPS traffic.

Steps to Run Multiple ORDS Instances with Different Secure Ports

1. Disable HTTP Listener Use the ORDS command line to set the HTTP listen port to zero: ords config set standalone.http.port 0
2. Start Each ORDS Instance on a Different HTTPS Port When launching each ORDS instance, specify a unique HTTPS port:
   ords serve --secure --port 8443
   
   For a second instance:
   ords serve --secure --port 8444
   This ensures each instance runs on a different secure port without conflicts.

Summary

This simple configuration allows multiple ORDS services, listening for secure HTTPS traffic, to coexist on the same machine without interference.

Should you want multiple instances to listen for HTTP and HTTPS traffic then using the ORDS docker image from https://container-registry.oracle.com/ords/ocr/ba/database/ords is your best option.