8i | 9i | 10g | 11g | 12c | 13c | 18c | 19c | 21c | 23ai | Misc | PL/SQL | SQL | RAC | WebLogic | Linux
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.
- Installation
- Starting/Stopping ORDS in Standalone Mode
- Auto SSL (HTTPS)
- SSL Configuration (HTTPS)
- APEX Static Images
- Static Resources (Document Root)
- Custom Error Pages
- Access Log
Related articles.
- Oracle REST Data Services (ORDS) : All Articles
- Oracle REST Data Services (ORDS) : Installation on Tomcat
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
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:
- Running in Standalone Mode
- Jetty Documentation
- Oracle REST Data Services (ORDS) : All Articles
- Oracle REST Data Services (ORDS) : Installation on Tomcat
Hope this helps. Regards Tim...