Monday, August 31, 2020

Free Oracle Cloud: Custom Domain Name (URL) with your own ORDS on the Webserver

This post is part of a series of blog posts on the Best and Cheapest Oracle APEX hosting: Free Oracle Cloud.

One of the most popular posts in this series is how to Setup a web server on the Virtual Machine.

In that blog post we setup Nginx as our web server, and as a proxy in front of Oracle APEX running on the Autonomous Database Cloud, so we can serve our own domain name e.g.

Since the release of ORDS 19.4.6 (and higher), Oracle supports that we run our own ORDS version in front of the Oracle Autonomous Database Cloud. This is really cool, for a couple of reasons:
  • We can tune ORDS. Oracle limits our Free ATP to 20 concurrent connections, having our own ORDS we can allow more simultaneous connections to our database by changing the config files.
  • We are able to create a reverse proxy on the same network as where ORDS is running, which will result in a more secure solution.
  • We can have multiple ORDS running against the same database.
  • We have more security options as we can choose where we run ORDS.
But before we go into the details on how to run ORDS on your own Compute VM and let it talk to the Autonomous Database Cloud, I also want to highlight a few consequences of doing this.
There are two main points of attention running your own ORDS in front of your APEX instance:
  • You are responsible to keep your own ORDS version the same as the on the Autonomous Database Cloud. Whenever Oracle upgrades ORDS, you have to upgrade your own ORDS too.
  • You have to update your images folder whenever a patch or upgrade is done for APEX.
Here's a small script I use to check the version of both Oracle APEX and ORDS:

select 'APEX' as product, version_no, api_compatibility, case when patch_applied = 'APPLIED' then (select listagg('Patch ' || to_char(patch_number) || ' (' || patch_version || ') installed on ' || installed_on, ', ') within group (order by installed_on) as patches from apex_patches) end as applied_patches from apex_release
union all
select 'ORDS' as product, ords.installed_version as version_no, null as api_compatibility, null as applied_patches from dual;

This results in:

You could automate the check, and in case something changed that it will email you for example.

Now, let's get started with the installation of ORDS on the same machine as our Nginx webserver.

# Log in as the opc user to the Compute VM and install Nginx and ORDS:
ssh -l opc -i .ssh/oraclecloud

# connect as root
sudo su

# as a best practice, update all packages on Linux
yum update

# install Nginx webserver
yum install -y nginx

# load repo which holds ORDS
yum-config-manager --enable ol7_oci_included

# in case you get an error, add the repo first manually

vi oci-included-ol7.repo

name=Oracle Software for OCI users on Oracle Linux $releasever ($basearch)

yum-config-manager --enable ol7_oci_included

# install ORDS
yum install -y ords

Let's also make sure we have the latest versions of SQLcl and the Oracle software and wallet.
Download SQLcl here and check this blog post about the software and wallet and let's make sure we can still connect from our compute instance to our Autonomous Database.

# uninstall old Oracle Instant client
yum remove oracle-instantclient18.5-tools.x86_64

# install latest Oracle Instant client
yum install oracle-instantclient19.8-basic.x86_64 

# connect as oracle 
su - oracle

# set environment variables
export PATH=/usr/lib/oracle/19.8/client64/bin:$PATH
export LD_LIBRARY_PATH=/usr/lib/oracle/19.8/client64/lib
export TNS_ADMIN=/usr/lib/oracle/19.8/client64/lib/network/admin

# connect with SQLcl to see if we can connect from the VM to the DB
./sql admin@dbdimi_high

If for some reason something is not working any longer, follow the steps again in the blog post how to run sqlcl from the compute instance to ATP.

We first have to create an ORDS user we will connect at, and it won't be the normal ORDS_PUBLIC_USER as that is used by ATP itself. We will create an ORDS_PUBLIC_USER2 as specified in the Installing and Configuring Customer Managed ORDS on Autonomous Database documentation.



         p_user => 'ORDS_PUBLIC_USER2',
         p_proxy_enabled_schemas => TRUE);

Now let's configure ORDS to connect to this user in the database:

# make a base64 string of the zip
mkdir /opt/oracle/ords/wallet
cd /opt/oracle/ords/wallet
cp /tmp/ .
base64 -w 0 >

# create the apex_pu.xml and defaults.xml configuration files for ORDS
cat << EOF > /opt/oracle/ords/config/ords/conf/apex_pu.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "">
  <entry key="db.username">ORDS_PUBLIC_USER2</entry>
  <entry key="db.password">!changeme</entry>
  <entry key="">dbdimi_low</entry>
  <entry key=""><![CDATA[$WALLET_BASE64]]></entry>

cat << EOF > /opt/oracle/ords/config/ords/defaults.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "">
  <entry key="plsql.gateway.enabled">true</entry>
  <entry key="jdbc.InitialLimit">10</entry>
  <entry key="jdbc.MaxLimit">20</entry>

Let's start ORDS manually first, so we can see if there are any errors:

cd /opt/oracle/ords
java -jar ords.war standalone

Note: In case you get java.lang.OutOfMemoryError: Java heap space, you can fix that by doing: 
export JAVA_OPTIONS=-Xmx512M 
In July I got this error, when I tried again last week I didn't anymore.

Copy Oracle APEX images folder.

Download Oracle APEX and upload the zip file with your favorite SFTP program to your compute instance. E.g. I use Transmit on OSX or you can use wget or something else.

# Unzip the file in the /opt/oracle folder
unzip /tmp/ -d /opt/oracle/

You need to make sure your APEX Images folder is in sync with the version of APEX running on ATP.
Typically Oracle will apply some patches, so download from Oracle Support, the patch for Oracle APEX and download it to your Compute Instance:

# Unzip the file in the /tmp

# Overwrite the files from the original Oracle APEX folder
cp -rf /tmp/30990551/images /opt/oracle/apex

# Edit the to add the reference to the images folder
vi /opt/oracle/ords/config/ords/standalone/

# Add

Restart ORDS again, and once we are sure all is working, let's start ORDS as a service and enable it to autostart on reboot:

# make sure you are root user

# run ORDS service and enable with startup
systemctl start ords
systemctl enable ords

Next, we want to configure Nginx as a reverse proxy in front of ORDS.
ORDS by default is running on port 8080. You may want to read my previous blog post on how to get started with Nginx. I didn't configure the domain yet, but I just wanted to access the IP.

The different bit is :

vi /etc/nginx/conf.d/

Add the following:

server {
    listen         80;
    listen         [::]:80;
    root           /usr/share/nginx/html/;
    index          index.html;
    try_files $uri /index.html;

 location /i/ {
  alias /opt/oracle/apex/images/;

 location /ords/ {
  proxy_pass http://localhost:8080/ords/;
  proxy_redirect off;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-Proto  $scheme;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;


Next, you want to reload Nginx:

nginx -s reload

The first time I tried to access I got a bad gateway error.

Looking at the logs I saw what was going on: 

tail -30 /var/log/nginx/error.log

To fix the issue I did:

cat /var/log/audit/audit.log | grep nginx | grep denied | audit2allow -M mynginx
semodule -i mynginx.pp

And there we go... it worked! Now we can access Oracle APEX with our own ORDS :)

Note: instead of using Nginx, you can also configure a Load Balancer in the Oracle Cloud. 
Adrian did a nice blog post on how to do that.

There you go... now you can choose to have your preferred domain name (custom URL) with your own ORDS in the Oracle Cloud.