ORDS Tomcat Install (21.2)

Assumptions

  • Oracle Database 11.1 or later

  • ORDS 19.2 or later, up to 21.2 (i.e. NOT 22.1 and later)


NOTE: These instructions were tested in an environment with Tomcat installed on a dedicated application server and an Oracle database installed on a dedicated database server.
NOTE: These instructions use a silent installation method. See the Oracle documentation if you wish to use the "advanced" interactive installation method.
NOTE: The examples in these instructions assume you are installing ORDS for use with APEX. Links are provided in case you wish to enable optional features.

Pre-Requisites

Not required for "Standalone" installation.
Tomcat 8.5 needs Java 7 or later. Tomcat 9 needs Java 8 or later
These instructions assume APEX is already installed in your target database.
For the Embedded PL/SQL gateway it is recommended that the HTTP Port is set to 0. However, as long as the port is not the same as the port used by Apache Tomcat then it can, technically, run alongside Tomcat.

On the target database instances...

For users returned by the following query, make sure the account is unlocked and you know the passwords

SELECT username,

account_status

FROM dba_users

WHERE username IN ('SYS','APEX_LISTENER','APEX_PUBLIC_USER','APEX_REST_PUBLIC_USER','ORDS_PUBLIC_USER')

/

Install

Unzip


mkdir /tomcat/ords

unzip /tomcat/ords*.zip -d /tomcat/ords

mkdir -p /tomcat/ords/conf



NOTE: These steps assume you have downloaded the ORDS installation zip file to /tomcatNOTE: The steps below should be performed as 'root'.NOTE: If you have attempted to install ORDS before then you should clear down /tomcat/conf (rm -rf /tomcat/conf) to avoid issues...

Multi-Tenant

If you are installing to a single-tenant architecure or to a CDB, ignore this step. If you are installing to a PDB you can create a user (e.g. ORDS_OWNER) to use for ORDS installation. After creating this user you need to run a script to grant the correct privileges. The script can be found here (copy it to your db server if necessary):

/tomcat/ords/installer/ords_installer_privileges.sql

Parameter File

Edit the parameter file...

/tomcat/ords/params/ords_params.properties

In the sections below, non-default parameters have values in bold italic

Database Connection

This example only covers the "basic" connection type. You can optionally use "tns" or "custumurl" instead. See the ORDS "Installation, Configuration, and Development Guide" for further information.

db.connectionType=basic

db.hostname=databaseserver

db.port=1521

db.servicename=ORCL1

db.sid=ORCL1

You must specify either db.sid or db.servicename (but not both)

basic uses service:hostname:port JDBC connect format

hostname

port

service

SID

For connection to a PDB you must specify db.servicename

REST Data Services

rest.services.ords.add=true

user.public.password=PUBpassword

schema.tablespace.default=SYSAUX

schema.tablespace.temp=TEMP

user.tablespace.default=SYSAUX

user.tablespace.temp=TEMP

bequeath.connect=false

Install the ORDS schema

Specifies password for ORDS_PUBLIC_USER

ORDS_METADATA default tablespace (must exist)

ORDS_METADATA temp tablespace (must exist)

ORDS_PUBLIC_USER default tablespace (must exist)

ORDS_PUBLIC_USER temp tablespace (must exist)

Only set to true if db is on same server as app server

REST-Enabled SQL

restEnabledSql.active=false

Enable REST-Enabled SQL

Database API

database.api.enabled=false

Enable Database API

SQL Developer Web

  • Available in ORDS 19.4+
  • Needs REST-Enabled SQL and Database API

feature.sdw=false

Enable SQL Developer Web

Multi-Tenant

  • Options for installing into CDB and all of its PDBs.
  • Leave at defaults for single-tenant architecture.

cdb.common.schema=false

db.serviceNameSuffix=.your_db_domain


Application Express

plsql.gateway.add=true

db.username=APEX_PUBLIC_USER

db.password=APUpassword

rest.services.apex.add=true

user.apex.listener.password=ALpassword

user.apex.restpublic.password=ARPUpassword

security.externalSessionTrustedOrigins

Configure ORDS for APEX.

PL/SQL gateway username. For APEX must be APEX_PUBLIC_USER

Password for APEX_PUBLIC_USER

Configure ORDS for APEX RESTful Services.

Specifies password for APEX_LISTENER

Specifies password for APEX_REST_PUBLIC_USER.

origins trusted for CORS reqs for PL/SQL Gateway or APEX

Miscellaneous

migrate.apex.rest=false

Specifies whether to migrate APEX RESTful Services definitions to Oracle REST Data Services schema.

standalone_mode=false

You can still easily launch in standalone mode later if you need to.

Copy Images

Copy the APEX images (${APXDIR}/images) to the Tomcat "webapps" directory.

If the Tomcat server and database server are separate hosts (recommended) then you will need to scp the files across.

su - root

mkdir /tomcat/latest/webapps/i/

cp -R ${APXDIR}/images/* /tomcat/latest/webapps/i/

chown -R tomcat:tomcat /tomcat/latest/webapps/i/


NOTE:
This step needs to be repeated each time you install a new version of APEX or a new version of Tomcat.

Set Configuration Directory

cd /tomcat/ords

java -jar ords.war configdir /tomcat/ords/conf

Maybe I'm missing something here, but it seems that not all the config gets copied over when you deploy the .war file to Tomcat. Some config will appear in /tomcat/latest/conf/ords (defaults.xml, standalone.properties) but the files you would expect under /tomcat/latest/conf/ords/conf (e.g. apex_al.xml, apex_pu.xml, apex_rt.xml, apex.xml) are missing and, I assume, must still be picked up from /tomcat/ords/conf/ords/conf. I guess one workaround may be to set the configdir to the Tomcat configdir at this point, but that risks losing config when upgrading Tomcat (and thus redeploying the .war).

Install

java -jar ords.war install

If you want the opportunity to check/change settings during installation, you can use: java -jar ords.war install advanced

Validate

cd /tomcat/ords

java -jar ords.war validate

This will prompt for information required to build a connect string, along with the SYS password. Rectify any reported errors before continuing.
If you see an "Incompatible versions." error then do this to upgrade the schema...java -jar ords.war schema

Test Standalone (Optional)

java -jar ords.war standalone

Use Ctrl-C to terminate the ORDS process when you are done.
You may be prompted for the path to the images location i.e.../tomcat/latest/webapps/i/
Wait for output to show an INFO message that ORDS is started,NOTE: assumes java is in your PATH (tested with openjdk 11.0.7 2020-04-14 LTS on Ubuntu 18.04 and OracleJDK 1.8.0_241 on AIX 7.1)

In a browser, test that ORDS is working, e.g.

http://tomcatserver:8181

Where tomcatserver is your Tomcat/ORDS server and databaseserver is your database server and 8181 is the port.

Deploy ords.war to Tomcat

cd /tomcat/ords

cp ords.war /tomcat/latest/webapps/

The following URL should work..

http://tomcatserver:8080/ords

ORDS should also show up as an application in Tomcat Web Application Manager...

http://tomcatserver:8080/manager/html

Next Steps