ORDS normally runs standalone with ords serve, using its own embedded Jetty web server. Some organizations, though, standardize on an application server and want every Java web application deployed in it. For them, ORDS is also distributed as a standard Java web application archive, ords.war, which can be deployed in Apache Tomcat (or Oracle WebLogic Server) instead.
This guide deploys ORDS and the APEX static files in Tomcat, explains which settings move from ORDS to Tomcat, and helps you decide whether Tomcat is worth it.
These steps come from Oracle APEX 26.1 Book: The Complete Guide.
Before You Start
You need APEX installed in the database, an unzipped ORDS release (ords.war sits in the ORDS folder, for example /opt/oracle/ords), the APEX download with its images folder, Java 17 or 21, and a Tomcat release supported by your ORDS version; check the ORDS installation guide for the current list. The examples use /etc/ords/config for the ORDS configuration, /opt/oracle/apex/images for the APEX files, and $CATALINA_BASE for the Tomcat instance folder.
Step 1: Install and Configure ORDS
Run ords install exactly as for a standalone server, ideally after APEX is installed so the gateway is enabled at once. This creates the configuration folder, the ORDS schema, and the default pool; Tomcat does not change any of that.
Example:
read -rsp 'SYS password: ' SYS_PWD; echo echo "$SYS_PWD" | ords --config /etc/ords/config install \ --admin-user SYS \ --db-hostname localhost --db-port 1521 \ --db-servicename FREEPDB1 \ --feature-db-api true \ --feature-rest-enabled-sql true \ --feature-sdw true \ --gateway-mode proxied --gateway-user APEX_PUBLIC_USER \ --password-stdin unset SYS_PWD
Look for "plsql.gateway.mode was set to: proxied" in the output. If it says disabled, APEX is not in the database yet; install APEX and run the command again. For the full sequence on a server, see how to install Oracle APEX 26.1 on Oracle Linux.
Step 2: Tell ORDS Where Its Configuration Is
Inside Tomcat there is no --config option, so pass the folder as the Java system property config.url in Tomcat's start-up options. Create or edit $CATALINA_BASE/bin/setenv.sh, which Tomcat's startup scripts read automatically.
Contents of setenv.sh:
JAVA_OPTS="$JAVA_OPTS -Dconfig.url=/etc/ords/config"
On Windows, use setenv.bat with set "JAVA_OPTS=%JAVA_OPTS% -Dconfig.url=C:\apex-lab\ords-config". The account that runs Tomcat must be able to read the configuration folder, including the wallet, and nobody else should; anyone who can read it can recover the stored passwords.
Step 3: Deploy ords.war
Copy ords.war to Tomcat's webapps folder. Tomcat deploys it at /ords, the same context path that standalone mode uses.
Example:
cp /opt/oracle/ords/ords.war $CATALINA_BASE/webapps/
Step 4: Serve the APEX Images at /i/
In standalone mode, ORDS serves the APEX static files from standalone.static.path. In Tomcat that setting does not apply, so let Tomcat serve them as a web application of their own by copying the images folder to webapps/i.
Example:
cp -r /opt/oracle/apex/images $CATALINA_BASE/webapps/i
The folder name i gives the URL path /i/, matching the image prefix given to apexins.sql. These files must belong to the same APEX version as the one in the database.
Step 5: Start Tomcat and Open APEX
Example:
$CATALINA_BASE/bin/startup.sh curl -s http://localhost:8080/i/apex_version.js
Output:
var gApexVersion = "26.1.0";
Then open http://server:8080/ords/apex to reach the workspace sign-in page, and /ords/apex_admin for Administration Services. Tomcat's own log, catalina.out in $CATALINA_BASE/logs, shows ORDS starting and any configuration errors.
What Changes in Tomcat
The standalone.* settings belong to ORDS's embedded web server, so in Tomcat they do not apply. Everything else in the ORDS configuration still does.
| Concern | Standalone ORDS | ORDS in Tomcat |
|---|---|---|
| Ports and HTTPS | standalone.http.port, standalone.https.* settings | Connectors in Tomcat's server.xml |
| Access logs | standalone.access.log | Tomcat's access log valve in server.xml |
| APEX static files | standalone.static.path | The webapps/i folder |
| Configuration folder | --config option | -Dconfig.url system property |
| Pools, gateway mode, jdbc.* sizes | ORDS configuration folder | The same ORDS configuration folder |
You still manage pool and gateway settings with ords --config /etc/ords/config config set, and restart Tomcat (or reload the ords application) for changes to take effect.
Upgrading in Tomcat
For a new ORDS release, run ords install from the new release folder with the same configuration folder to upgrade the ORDS schema, then replace ords.war in webapps with the new one. When you upgrade APEX, replace webapps/i with the images folder from the new APEX download.
Should You Use Tomcat?
Unless your organization requires an application server, standalone mode is simpler and just as capable: one process, settings in one place, and HTTPS either in ORDS or at a reverse proxy, as described in how to enable HTTPS in ORDS. Choose Tomcat when your operations team already runs, monitors, and patches Tomcat for other applications and wants ORDS to fit the same pattern.
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| ORDS fails to deploy and catalina.out mentions the configuration | config.url is missing or wrong, or Tomcat's account cannot read the folder. Check setenv.sh and the folder's permissions. |
| 404 at /ords/apex | ords.war is not deployed, or the gateway is disabled. Check webapps/ords and run ords config get plsql.gateway.mode. |
| APEX pages without styles | webapps/i is missing or from another APEX version. Check /i/apex_version.js. |
| HTTP 503 Service Unavailable | ORDS cannot reach the database. Run ords --config /etc/ords/config config verify. |
Related Guides
Conclusion
To deploy ORDS in Apache Tomcat, run ords install as usual to create the configuration folder, add -Dconfig.url pointing at it to JAVA_OPTS in setenv.sh, copy ords.war to webapps, copy the APEX images folder to webapps/i, and start Tomcat. Ports, HTTPS, and access logs then move to Tomcat's server.xml, while pools and the gateway stay in the ORDS configuration.
