Oracle REST Data Services (ORDS)

Oracle REST Data Services (ORDS) 3.0, 17.x and 18.x Installation on Tomcat 7, 8 and 9
Oracle REST Data Services (ORDS), formerly known as the APEX Listener, allows APEX applications to be deployed without the use of Oracle HTTP Server (OHS) and mod_plsql or the Embedded PL/SQL Gateway. ORDS version 3.0 onward also includes JSON API support to work in conjunction with the JSON support in the 12c database. ORDS can be deployed on WebLogic, Glassfish or Tomcat. This article describes the installation of ORDS on Tomcat 7, 8 and 9.

This methods works ORDS 3.0 onward, including ORDS 17.4 and 18.1.

Assumptions
Multitenant : CDB or PDB Installation
Downloads
ORDS Installation
Tomcat Deployment
Starting/Stopping ORDS Under Tomcat
Manual ORDS Uninstall
Related articles.

Oracle REST Data Services (ORDS) Articles
Oracle REST Data Services (ORDS) : Standalone Mode
Oracle Application Express (APEX) 5.x Installation
Apache Tomcat 7 Installation on Linux (RHEL and clones)
Apache Tomcat 8 Installation on Linux (RHEL and clones)
Apache Tomcat 9 Installation on Linux (RHEL and clones)
Assumptions
You have a server with Tomcat 7, 8 or 9 installed on it. In this case I used a server with Oracle Linux 7 and used the same process to install ORDS on Tomcat 7, Tomcat 8 and Tomcat 9.
You have a database with APEX 4.2 or APEX 5.x installed. From ORDS 3.0 onward, APEX is not actually necessary, but there is some useful stuff in there, so I would always recommend it.
The Embedded PL/SQL Gateway should be configured on the APEX installation, but the HTTP port left set to the value “0”.
Multitenant : CDB or PDB Installation
When using the multitenant architecture there are several options for how to install ORDS.

For Lone-PDB installations (a CDB with one PDB) ORDS can be installed directly into the PDB. The db.servicename parameter will be set to the PDB service name in the properties file. This is the method I typically use as there is no additional ORDS dependency on the CDB.

If you are using multiple PDBs per CDB, you may prefer to install ORDS into the CDB to allow all PDBs to share the same connection pool. This will drastically reduce the number of database connections used compared to having a separate connection pool per PDB. In this case the db.servicename parameter will be set to the CDB service name in the properties file. From version 18.1 onward there are two ways of installing ORDS into the CDB. The recommended way is to set cdb.common.schema=false in the properties file, which will allow each PDB to run a different version of ORDS. Alternatively you can use cdb.common.schema=true in the properties file, which will mean all PDBs will have to use the same version of ORDS. Whichever option you choose, you will probably want to also use the db.serviceNameSuffix=.your_db_domain parameter to enable the pluggable mapping functionality.

You read more about the CDB installation options here.

Remember, even though the documentation doesn’t speak explicitly about installing directly into the PDB, it is a viable option for Lone-PDB instances.

Downloads
Download the following software. Always use the latest version available.

Oracle REST Data Services 3.0, 17.x or 18.x
ORDS Installation
Check the SYS user and common public users are unlocked and you know their passwords. Remember to lock the SYS user when the installation is complete.

CONN / AS SYSDBA
ALTER USER SYS IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;
–ALTER USER SYS IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK CONTAINER=ALL;

–ALTER SESSION SET CONTAINER = pdb1;
ALTER USER APEX_LISTENER IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;
ALTER USER APEX_PUBLIC_USER IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;
ALTER USER APEX_REST_PUBLIC_USER IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;

— The next one will fail if you’ve never installed ORDS before. Ignore errors.
ALTER USER ORDS_PUBLIC_USER IDENTIFIED BY OraPassword1 ACCOUNT UNLOCK;
Unzip the ORDS distribution. In this case we are doing this as the “tomcat” user on the server.

# su – tomcat
$ mkdir /u01/ords
$ cd /u01/ords
$ unzip /tmp/ords.17.4.0.348.21.07.zip
Make a directory to hold the configuration.

$ mkdir -p /u01/ords/conf
If you have any failures during the installation, remember to delete the contents of this directory before trying again.

Edit the “/u01/ords/params/ords_params.properties” file provided with the ORDS software, setting the appropriate parameters for your installation. In this case my file contents were as follows.

db.hostname=ol7-122.localdomain
db.port=1521
db.servicename=pdb1
#db.sid=
# Next 2 lines for CDB installations only.
#cdb.common.schema=false
#db.serviceNameSuffix=.your_db_domain
db.username=APEX_PUBLIC_USER
db.password=OraPassword1
migrate.apex.rest=false
plsql.gateway.add=true
rest.services.apex.add=true
rest.services.ords.add=true
schema.tablespace.default=APEX
schema.tablespace.temp=TEMP
standalone.mode=false
# Next 3 lines for standalone mode only.
#standalone.use.https=true
#standalone.http.port=8080
#standalone.static.images=/home/oracle/apex/images
user.apex.listener.password=OraPassword1
user.apex.restpublic.password=OraPassword1
user.public.password=OraPassword1
user.tablespace.default=APEX
user.tablespace.temp=TEMP
sys.user=SYS
sys.password=OraPassword1
If you need to restart the installation for any reason, remember of clear down the config directory and check the contents of the “/u01/ords/params/ords_params.properties” file before you restart the installation. Having password entries in this file from a failed installation can cause problems.

Use the “ords.war” file to specify the configuration directory using the following command. The file name “ords.war” will result in a URL containing “/ords/”. If you want a different URL, rename the WAR file accordingly. In this article I will use the original name.

$ $JAVA_HOME/bin/java -jar ords.war configdir /u01/ords/conf
Dec 17, 2017 8:50:19 AM
INFO: Set config.dir to /u01/ords/conf in: /u01/ords/ords.war
$
Configure ORDS using the following command. This is the equivalent of specifying the “install simple” command line parameters. If you’ve entered the parameters correctly in the parameter file there should be no prompts. If some parameters are missing or incorrect you will be prompted for a response.

$ $JAVA_HOME/bin/java -jar ords.war

Retrieving information.
Dec 17, 2017 8:50:59 AM
INFO: Updated configurations: defaults, apex, apex_pu, apex_al, apex_rt
Installing Oracle REST Data Services version 17.4.0.348.21.07
… Log file written to /u01/ords/logs/ords_install_core_2017-12-17_085059_00767.log
… Verified database prerequisites
… Created Oracle REST Data Services schema
… Created Oracle REST Data Services proxy user
… Granted privileges to Oracle REST Data Services
… Created Oracle REST Data Services database objects
… Log file written to /u01/ords/logs/ords_install_datamodel_2017-12-17_085224_00812.log
… Log file written to /u01/ords/logs/ords_install_apex_2017-12-17_085234_00725.log
Completed installation for Oracle REST Data Services version 17.4.0.348.21.07. Elapsed time: 00:01:40.123

$
Lock the SYS user.

ALTER USER SYS ACCOUNT LOCK;
Tomcat Deployment
Copy the APEX images to the Tomcat “webapps” directory.

$ mkdir $CATALINA_HOME/webapps/i/
$ cp -R /tmp/apex/images/* $CATALINA_HOME/webapps/i/
Copy the “ords.war” file to the Tomcat “webapps” directory.

$ cd /u01/ords
$ cp ords.war $CATALINA_HOME/webapps/
ORDS should now be accessible using the following type of URL.

http://<server-name>:<port>/ords/

http://ol7.localdomain:8080/ords/
Starting/Stopping ORDS Under Tomcat
ORDS is started or stopped by starting or stopping the Tomcat instance it is deployed to. Assuming you have the CATALINA_HOME environment variable set correctly, the following commands should be used.

$ $CATALINA_HOME/bin/startup.sh
$ $CATALINA_HOME/bin/shutdown.sh
Manual ORDS Uninstall
Extract the scripts from the “tomcat” user using the following commands.

su – tomcat
cd /u01/ords
$JAVA_HOME/bin/java -jar ords.war ords-scripts –scriptdir /tmp
Perform the uninstall from the “oracle” user using the following commands.

su – oracle
cd /tmp/scripts/uninstall/core/

sqlplus sys@pdb1 as sysdba

@ords_manual_uninstall /tmp/scripts/logs

One Comment on “Oracle REST Data Services (ORDS)”

Leave a Reply

Your email address will not be published. Required fields are marked *