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:
- Oracle APEX tutorial: Uncover Oracle’s best-kept low-code secret
- Interactive Grid duplicate values – Learn How to prevent a common problem using a Zero-JavaScript approach
- Oracle APEX new features – the low-code platform keeps evolving
- How the Oracle APEX community helps shape the platform’s future
- Oracle APEX Global Notification messages: An easy way to make them look better