8i | 9i | 10g | 11g | 12c | 13c | 18c | 19c | 21c | 23c | Misc | PL/SQL | SQL | RAC | WebLogic | Linux

Home » Articles » Misc » Here

Oracle REST Data Services (ORDS) : Standalone Mode (ORDS Versions 3.0 to 21.4)

These instructions work for ORDS versions 3.0 to 21.4. If you want to use version ORDS 22.1 onward, use the instructions here.

Oracle now supports Oracle REST Data Services (ORDS) running in standalone mode using the built-in Jetty web server, so you no longer need to worry about installing Tomcat or WebLogic unless you have a compelling reason to do so. Removing this extra layer means one less layer to learn and one less layer to patch.

Related articles.

Installation

The ORDS installation process is similar regardless of the application server being used, so you should follow the installation described here, but make sure you specify the following parameters in the "ords_params.properties" file. Obviously adjust to the desired settings and ignore the Tomcat deployment.

For HTTP access use the following parameters. Adjust the image path as required.

# Standalone HTTP
standalone.mode=true
standalone.http.port=8080
standalone.static.path=/home/oracle/apex/images

For HTTPS using Auto SSL use the following parameters. Adjust the image path and host as required.

# Standalone HTTPS - Auto SSL
standalone.mode=true
standalone.use.https=true
standalone.https.port=8443
standalone.static.path=/home/oracle/apex/images

For HTTPS using your own certificate, use the following parameters. Adjust the paths and host as required.

# Standalone HTTPS - Certificate
standalone.mode=true
standalone.use.https=true
standalone.https.port=8443
standalone.ssl.host=localhost.localdomain
standalone.static.path=/home/oracle/apex/images
standalone.use.ssl.cert=true
standalone.ssl.cert.path=/home/oracle/keystore/localhost.der
standalone.ssl.key.path=/home/oracle/keystore/localhost-key.der

The static image location used a different parameter name prior to ORDS 19, but you shouldn't be using that now anyway.

# ORDS19 Onward
standalone.static.path=/home/oracle/apex/images
# Pre-ORDS19
standalone.static.images=/home/oracle/apex/images

The installation parameters are a convenience. The underlying Jetty configuration remains the same, so once you have installed ORDS, you can reconfigure Jetty as described below. You don't need to reinstall ORDS to alter the settings.

If you did the installation using the standalone settings (as above), you will find the standalone settings in the following file.

/u01/ords/conf/ords/standalone/standalone.properties

If not, you will need to start ORDS in standalone mode one, and the config file will be created. You can then adjust it at as you require.

Once started, ORDS will be available using one of the following URLs.

# HTTP
http://ol7-121.localdomain:8080

# HTTPS
http://ol7-121.localdomain:8443

Starting/Stopping ORDS in Standalone Mode

During testing, you can manually start the ORDS using the following command. If you have fully configured ORDS it won't prompt you for any user input.

cd /u01/ords
$JAVA_HOME/bin/java -jar ords.war standalone

It will capture the console and push all log information to it. You can stop ORDS using CTRL+C.

For a production deployment you should start ORDS as a background process and push the output to a log file. For example, you could create a file called "~/scripts/start_ords.sh" with the following contents. Remember to adjust paths as required.

#!/bin/bash
export PATH=/usr/sbin:/usr/local/bin:/usr/bin:/usr/local/sbin:$PATH
export JAVA_HOME=/usr
LOGFILE=/home/oracle/scripts/logs/ords-`date +"%Y""%m""%d"`.log
cd /u01/ords
export JAVA_OPTIONS="-Dorg.eclipse.jetty.server.Request.maxFormContentSize=3000000 -Duser.timezone=UTC"
nohup $JAVA_HOME/bin/java ${JAVA_OPTIONS} -jar ords.war standalone >> $LOGFILE 2>&1 &
echo "View log file with : tail -f $LOGFILE"

You can kill ORDS by killing the background process. Create a scripts called "~/scripts/stop_ords.sh" with the following contents.

#!/bin/bash
export PATH=/usr/sbin:/usr/local/bin:/usr/bin:/usr/local/sbin:$PATH
kill `ps -ef | grep ords.war | awk '{print $2}'`

Create the log directory and make the scripts executable.

mkdir -p ~/scripts/logs
chmod u+x ~/scripts/*.sh

You can then easily stop and start ORDS using the scripts.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Auto SSL (HTTPS)

ORDS will automatically create a self-signed certificate for use with SSL if you don't specify a valid certificate and key.

Edit the "/u01/ords/conf/ords/standalone/standalone.properties" file, setting the following parameters. Adjust the port as desired.

jetty.secure.port=8443
ssl.cert=
ssl.cert.key=
ssl.host=

Restart ORDS.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

SSL Configuration (HTTPS)

You should probably be fronting ORDS with a reverse proxy or a load balancer, so you may decide to leave internal network communication using HTTP. If you do want direct access, or internal network traffic encryption, you will need to configure Jetty to use HTTPS. If you have a proper CA certificate and key, make sure they are in DER format and just do the "standalone.properties" file settings. In this case we will manually create a new self-signed certificate and use that for the HTTPS configuration. Remember to adjust the "dname" and passwords as required.

mkdir ~/keystore
cd ~/keystore

# Create a self-signed certificate in a JKS keystore.
$JAVA_HOME/bin/keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore.jks \
   -dname "CN=`hostname`, OU=Example Department, O=Example Company, L=Birmingham, ST=West Midlands, C=GB" \
   -storepass password1 -validity 3600 -keysize 2048 -keypass password1

# Create a PKCS12 keystore from the JKS keystore.
$JAVA_HOME/bin/keytool -importkeystore -srckeystore keystore.jks -srcalias selfsigned -srcstorepass password1 \
   -destkeystore keystore.p12 -deststoretype PKCS12 -deststorepass password1 -destkeypass password1 

# Extract the key and certificate in PEM format.
openssl pkcs12 -in keystore.p12 -nodes -nocerts -out `hostname`-key.pem
openssl pkcs12 -in keystore.p12 -nokeys -out `hostname`.pem

# Convert them to DER format.
openssl pkcs8 -topk8 -inform PEM -outform DER -in `hostname`-key.pem -out `hostname`-key.der -nocrypt
openssl x509 -inform PEM -outform DER -in `hostname`.pem -out `hostname`.der

If everything has gone OK you now have key and certificate in DER format.

$ ls *.der
ol7-121.localdomain.der  ol7-121.localdomain-key.der
$

Edit the "/u01/ords/conf/ords/standalone/standalone.properties" appending the following settings.

# SSL Confile
jetty.secure.port=8443
ssl.cert=/home/oracle/keystore/ol7-121.localdomain.der
ssl.cert.key=/home/oracle/keystore/ol7-121.localdomain-key.der
ssl.host=ol7-121.localdomain

Restart ORDS.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Check it has started correctly by looking at the log file.

tail -f ~/scripts/logs/ords-`date +"%Y""%m""%d"`.log

Once started, ORDS will be available using the following URL.

https://ol7-121.localdomain:8443

APEX Static Images

When using ORDS to front APEX applications, ORDS should be configured to serve the APEX static files.

Edit the following path in the "/u01/ords/conf/ords/standalone/standalone.properties" file to the desired OS path.

standalone.static.context.path=/i
standalone.static.do.not.prompt=true
standalone.static.path=/home/oracle/apex/images

Restart ORDS.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Static Resources (Document Root)

ORDS can be used to serve static content like a regular web server.

Edit the following path in the "/u01/ords/conf/ords/standalone/standalone.properties" file to the desired OS path. The line below shows the default path.

standalone.doc.root=/home/oracle/ords-3.0.9-conf/ords/standalone/doc_root

Make sure the desired path exists.

mkdir -p /u01/ords/conf/ords/standalone/doc_root

Restart ORDS.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Custom Error Pages

ORDS will automatically handle the typical HTTP errors. If you are fronting ORDS with a load balancer, you may wish to use that to handle custom error messages, rather than altering the ORDS configuration. If you need it, ORDS can handle custom error pages.

Add the following entry to the "/u01/ords/conf/ords/defaults.xml" file and restart ords. Adjust the path as required.

<entry key="error.externalPath">/home/oracle/error-pages/</entry>

Create the required custom error files. I've just created some simple ones to test with.

echo "404 Error: Whoops" > /home/oracle/error-pages/404.html
echo "500 Error: Whoops" > /home/oracle/error-pages/500.html

Restart ORDS.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Access Log

Thanks to Kris Rice for his explanation of how to configure this (see here).

Access logs are really important if you want to know who is accessing your web server. The Jetty web server, which is used by ORDS in standalone mode, can be configured using XML files. The Jetty documentation for this feature can be found here.

Create the ".../standalone/etc" directory to hold the config file and a directory to hold the log files.

mkdir -p /u01/ords/conf/ords/standalone/etc
mkdir -p /u01/ords/conf/ords/standalone/logs

Create a new file called "/u01/ords/conf/ords/standalone/etc/jetty-http.xml" with the following contents. Adjust the configuration as required.

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
    <Ref id="Handlers">
      <Call name="addHandler">
        <Arg>
          <New id="RequestLog" class="org.eclipse.jetty.server.handler.RequestLogHandler">
            <Set name="requestLog">
              <New id="RequestLogImpl" class="org.eclipse.jetty.server.NCSARequestLog">
                <Set name="filename"><Property name="jetty.logs" default="/u01/ords/conf/ords/standalone/logs/"/>ords-access-yyyy_mm_dd.log</Set>
                <Set name="filenameDateFormat">yyyy_MM_dd</Set>
                <Set name="retainDays">90</Set>
                <Set name="append">true</Set>
                <Set name="extended">false</Set>
                <Set name="logCookies">false</Set>
                <Set name="LogTimeZone">GMT</Set>
            </New>
          </Set>
        </New>
        </Arg>
      </Call>
    </Ref>
</Configure>

Restart ORDS.

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

Once you access ORDS you will see an access log created in the "/u01/ords/conf/ords/standalone/logs" directory.

For more information see:

Hope this helps. Regards Tim...

Back to the Top.