Oracle 23c Free Docker, APEX & ORDS – all in one simple guide

Contents

Using Oracle APEX with the 23c version of free Docker is quite easy if you know how to set things up correctly. This 25-step guide will take you through everything you need to do.

These are the things you’ll need:

Oracle 23c Free Database
ORDS latest (23.1 at time of writing)
Open JAVA 17 JDK
latest Oracle APEX version (22.2 at the time of writing)

However, you don’t really need to download anything now – I’ll tell you how to do that quickly via the command line.

Also, if you already have Docker running, you can skip the first section about installation and get to the steps that follow ( the Getting Docker to work section).

Install and run Docker

If you don’t have Docker installed, just get through the steps outlined below. Details will differ depending on your platform/OS of choice.

For Mac, you first need to install Brew/Colima/Docker – you can follow the instructions in this guide by my colleague Rafał Grzegorczyk
For Windows, the process is really straightforward, so simply make sure Docker is running and start Docker Desktop
For Unix, install it by using the following commands in your terminal:

docker version
sudo yum install docker -y

Once you’ve downloaded Docker, you’ll need to unpack the data. Drop into the command line (i.e. terminal or windows+r, cmd) and type the following command. It’ll take about 15 mins to complete and unpack to 10.5GB on your HDD.

docker pull container-registry.oracle.com/database/free:latest

This is what it’ll look like once it completes:

Now, all that’s left is to run Docker. You can do this by using the following command. Please note, that I’ve changed ports to 8xxx to avoid conflicts with my other docker images.

docker run -d -it --name 23cfree -p 8521:1521 -p 8500:5500 -p 8023:8080 -p 9043:8443 -e ORACLE_PWD=E container-registry.oracle.com/database/free:latest

Get Docker to work with Oracle APEX

Now, here are the 25 steps you’ll need to follow to get everything working. The process is quite straightforward.

1. Enter bash

Just type the following command:

docker exec -it 23cfree /bin/bash

2. Get APEX

Use this command (it’ll take around 1 minute):

curl -o apex-latest.zip https://download.oracle.com/otn_software/apex/apex-latest.zip

3. Unpack and enter APEX

You can use these commands:

unzip apex-latest.zip
rm apex-latest.zip
cd apex

4. Let your database settle for at least a few minutes

It’s best to let things settle a bit before you continue, so give it a few minutes. You can grab a coffee while you wait!

5. Open SQL*Plus with sqlplus / as sysdba

The exact command looks like this:

bash-4.4$ sqlplus / as sysdba
SQL*Plus: Release 23.0.0.0.0 - Developer-Release on Wed Apr 5 13:27:32 2023 Version 23.2.0.0.0
Copyright (c) 1982, 2023, Oracle. All rights reserved.
Connected to: Oracle Database 23c Free, Release 23.0.0.0.0 - Developer-Release Version 23.2.0.0.0

6. Run the APEX installer

Use the following command:

ALTER SESSION SET CONTAINER = FREEPDB1;
@apexins.sql SYSAUX SYSAUX TEMP /i/

The installation will take around 10 minutes. If you get the PLS-00201: identifier ‘SYS.DBMS_DB_VERSION’ must be declared an error, just keep re-trying this step until it works. It’ll settle down after a while.

7. Unlock the public user account

Here’s the command:

ALTER USER APEX_PUBLIC_USER ACCOUNT UNLOCK;
ALTER USER APEX_PUBLIC_USER IDENTIFIED BY E;

8. Change the password

Run the following command and follow the outlined steps:

@apxchpwd.sql

It’s worth noting you must use a complex password for this purpose, so come up with something adequate.

9. Exit SQL*Plus

Simply type the following word:

exit

10. Create the following folders

To make things quick and simple, you can copy-paste the commands outlined below:

mkdir /home/oracle/software
mkdir /home/oracle/software/apex
mkdir /home/oracle/software/ords
mkdir /home/oracle/scripts

11. Copy the APEX images & change the folder

Simply type in the following:

cp -r /home/oracle/apex/images /home/oracle/software/apex
cd /home/oracle/

12. Install sudo

Use the following commands:

su
dnf update
dnf install sudo -y

13. Install nano

Type in the following:

dnf install nano -y

14. Edit the sudo list

Now, you’ll need to quickly edit the sudo list. First, type in this command:

nano /etc/sudoers

In the Defaults section, add the following:

Defaults !lecture

Now, at the very end of the file you also need to add this:

oracle ALL=(ALL) NOPASSWD: ALL

After that just click Ctrl+X and save the file.

15. Install Java

You can use this command:

dnf install java-17-openjdk -y

16. Setup ORDS folders & check JAVA

Here are the commands to use to set everything up quickly:

mkdir /etc/ords
mkdir /etc/ords/config
mkdir /home/oracle/logs
chmod -R 777 /etc/ords
java -version

If everything is as it should be, you will get the following result in return:

openjdk version "17.0.6" 2023-01-17 LTS
OpenJDK Runtime Environment (Red_Hat-17.0.6.0.10-3.el8_7) (build 17.0.6+10-LTS)
OpenJDK 64-Bit Server VM (Red_Hat-17.0.6.0.10-3.el8_7) (build 17.0.6+10-LTS, mixed mode, sharing)

17. Whilst still as su, install ORDS

Use the following commands:

yum-config-manager --add-repo=http://yum.oracle.com/repo/OracleLinux/OL8/oracle/software/x86_64
dnf install ords -y

18. Configure ORDS

Type in the following:

export _JAVA_OPTIONS="-Xms512M -Xmx512M"
ords --config /etc/ords/config install

The configuration you should use looks like this:

Installation Type > Choose option [2] Enter
Connection Type > Choose option [1] Enter
host name > Enter
listen port > Enter
service name > FREEPDB1
administrator username > SYS
password > E
default tablespace > Enter
temp tablespace > Enter
features > Enter
Start ORDS > [1] Enter <-- Standalone Mode
protocol > [1] < http
port > [1] <-- 8080
Static Resources > /home/oracle/software/apex/images

The ORDS configuration will only take a couple of minutes. Once it completes, it should display the following message:

Oracle REST Data Services version : 23.1.0.r0861423
Oracle REST Data Services server info: jetty/10.0.12
Oracle REST Data Services java info: OpenJDK 64-Bit Server VM 17.0.6+10-LTS

19. Do a quick test and close ORDS

Run http://localhost:8023/ords/apex in a different browser tab – if everything was configured correctly you should see the APEX log-in visible on the screenshot below.

You can close the tab after that. You’ll also need to quit ORDS for now by using Ctrl+C.

FYI: Prior to ORDS 23.2 (read here), you just use the URL localhost:8023/ords.

20. Create a start_ords.sh file

Use the following command:

nano /home/oracle/scripts/start_ords.sh

And then paste in this:

export ORDS_HOME=/usr/local/bin/ords
export _JAVA_OPTIONS="-Xms512M -Xmx512M"
LOGFILE=/home/oracle/logs/ords-`date +"%Y""%m""%d"`.log
nohup ${ORDS_HOME} --config /etc/ords/config serve >> $LOGFILE 2>&1 & echo "View log file with : tail -f $LOGFILE"

21. Create a stop_ords.sh file

Start with this command:

nano /home/oracle/scripts/stop_ords.sh

And then type in the following:

kill `ps -ef | grep [o]rds.war | awk '{print $2}'`

If you ever need to use these scripts manually, you can run them via the following commands. However, don’t do this now!

sh /home/oracle/scripts/start_ords.sh
sh /home/oracle/scripts/stop_ords.sh

22. Create an ORDS startup script

Use the following command:

nano /opt/oracle/scripts/startup/01_auto_ords.sh

Then paste this in:

sudo sh /home/oracle/scripts/start_ords.sh

23. If you are using Docker on Unix, enable linger

This step isn’t required for Windows/Mac installations but you need it on Unix to prevent user processes from being killed once the session is completed. To do this, run:

loginctl enable-linger $UID

24. Stop your Docker container, and then start it again

You can simply use the graphical interface or run this command:

docker restart 23cfree

You do this to activate the ORDS auto-starter script you’ve created in one of the previous steps.

25. Wait a moment, and try logging in

Wait at least 60 seconds and try logging in at http://localhost:8023/ords/apex. Use the following data:

Workspace > INTERNAL
Username > ADMIN
Password > Your Complex Password

Summary

And that’s it! As you can see, the process was quite easy and not very time-consuming. It probably took you, what… around 30 minutes total? If everything was configured properly, you should be able to get into APEX without any issues. If you’ve got any questions, you can always reach me at mmulvaney@pretius.com. Also, if you’re interested in Oracle APEX, check out some of my other articles on this blog: