Oracle APEX - Starting and stopping stand-alone ORDS in GNU/Linux

I have recently been working on an Oracle APEX upgrade project. As part of this upgrade, we undertook a migration that involved transitioning from the PL/SQL Gateway to Oracle REST Data Services (ORDS).

Given the time gap since I last worked with on-premises systems (a non-cloud environment, if you will), I've been actively researching the optimal methods for initiating and halting ORDS.

1️⃣ The proper way

If you deploy ORDS using a package manager, as well described in thatjeffsmith's blog here, the stop and start functionality should will already be available for you to enjoy.

In this scenario, assuming you are using systemd as the service manager, you can start ORDS simply with:

systemctl start ords

And in the same way, you can stop it with:

systemctl stop ords

In the case you want to ORDS to automatically start on server startup, you should be able to enable the service with:

systemctl enable ords

and the opposite action with:

systemctl start ords

2️⃣ The quick and dirty way

If, for some reason, you have installed Oracle ORDS through a zip file (as was my case), and you happen to have experience with a simple bash script to run ORDS (as was my case again), this method might be the quick and dirty solution you're looking for.

Start editing a file with a descriptive name; for instance:

vim start_ords.sh

Copy and paste the following bash code, then adjust it according to your needs:

#!/bin/bash
nohup ords --config <path_to_your_config> serve &
echo $! > ~/.ordspid

This code will:

Start ORDS using nohup (a bash tool to log the console output to a file called nohup.out).
The & symbol runs ords in the background.
The echo command will save the PID to a hidden file

Once you save and quit, you might want to grant execute permission to run the script:

chmod 700 start_ord.sh

Now, you should be able to run Oracle REST Data Service from your new script. Following the previous steps, you can create a start_ords.sh file with the following code:

#!/bin/bash
pkill -P  $(cat ~/.ordspid)

In this case, this command kills processes whose parent process ID matches the specified PID read from the hidden file created by the previous script.

That's it! If you're not a perfectionist (unlike me), feel free to stop reading now. Thank you, and I hope you found it helpful! 😎

3️⃣ The proper way - Manually

After refining my stop and start script, I naturally found myself wondering if there might be a better approach. So, I turned to Google for some insights and stumbled upon a helpful tip in the Oracle Forum: exploring the ORDS folder.

While listing the files, a folder named linux-support caught my attention and I quickly found a README.md stating that "The files on this folder are needed to setup your Oracle ORDS to start with the Linux service manager (Systemd or System V )". In other words, exactly what I was looking for.

Checking dependencies

The scripts depend on lsof to list open files. It's a fairly basic tool and is usually pre-installed in most Linux systems. If it's not present, you can simply install it using the package manager that comes with your distribution (dnf, apt, etc.).

Preparation

From the linux-support folder, as root, run the following command to copy the manual files to the correct location and set the appropriate permissions.

   sudo cp man/ords.1 /usr/share/man/man1/ords.1.gz
   sudo chmod 644 /usr/share/man/man1/ords.1.gz
   sudo chown root:root /usr/share/man/man1/ords.1.gz
   sudo cp man/ords.conf.5 /usr/share/man/man5/ords.conf.5.gz
   sudo chmod 644 /usr/share/man/man5/ords.conf.5.gz
   sudo chown root:root /usr/share/man/man5/ords.conf.5.gz
   sudo cp man/ords.service.8 /usr/share/man/man8/ords.service.8.gz
   sudo chmod 644 /usr/share/man/man8/ords.service.8.gz
   sudo chown root:root /usr/share/man/man8/ords.service.8.gz

Run the following command as root to copy the configuration file, service file, and init script:

	sudo cp ords.sh /etc/init.d/ords
	sudo chown root:root /etc/init.d/ords
	sudo chmod 755 /etc/init.d/ords
	sudo cp ords.conf /etc/ords.conf
	sudo chown oracle:oinstall /etc/ords.conf
	sudo chmod 750 /etc/ords.conf
	sudo cp ords.service /etc/systemd/system/ords.service
	sudo chown root:root /etc/systemd/system/ords.service
	sudo chmod 644 /etc/systemd/system/ords.service

And once again, as root, create a symlink for the ORDS binary.

sudo ln -s <ORDS_BASE>/bin/ords /usr/local/bin/ords

NOTE - ORDS_BASE is the path of the folder where you have uncompressed your Oracle ORDS Zip file.

Configuration

Once you finish copying files, it's time to set up some variables for the scripts to run smoothly. The configuration is now in one of the files we have copied in the previous step, located at /etc/ords.conf.

Usually, only two variables are needed in this step:

ORDS_BASE Same as in the previous step, it is the path of the folder where you have uncompressed your Oracle ORDS Zip file (e.g., /opt/oracle/ords).
ORDS_CONFIG: It is the path where you have decided to place your ORDS configuration while installing ORDS (e.g., /opt/oracle/ords/config).

Usage

At this point, you should be able to start, stop ,restart, enable or disable ORDS in the same way, you would do while installing ORDS using a package manager.

systemctl start ords

Find out more about our APEX Consultancy Services.