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.
Disclaimer: This article was originally published in May 2023. However, in March 2024 it was updated with new content – an automated script that allows you to set everything up in one step. The updated information is at the very top, but if you prefer the manual method, you’ll find it in the latter part of the article.
(Update) Single-step setup
This article includes several steps which are prone to manual error. Copying and pasting the required code can also be pretty time-consuming. Because of this, I’ve created an update that’ll let you do the exact same thing in just one single step. Just copy and paste the code below, come back after lunch, and you’ll have a ready-to-rock APEX environment.
Prerequisites
You’ll need Podman, Docker or Docker-ce for Windows, Unix or Mac (Mac users read this first).
If you are running this on an OCI compute instance, you’ll need to open ports 8521, 8500, 8023, 9043 & 9922. Otherwise ignore this step.
Also, before you start: The 23c Docker image can be slow to start up on some OS’s and get the PDBs operational. This means a delay in successfully installing APEX. So remember about one of the steps from the guide below (the one about getting coffee) – it’ll come in handy!
I have never encountered any such issue on an Oracle Cloud Compute box. In this single step, the script doesn’t make itself (or yourself) a coffee. This would be a future improvement to the script.
The Single Step
So, here it is. Simply paste the code below into your Terminal/Command Prompt. The command should work in Windows, Unix & Mac (once again, Mac users should read this first). For clarity, I’m running this on Unix on an Oracle Cloud Compute with a free 50gb Block Volume.
docker create -it --name 23cfree -p 8521:1521 -p 8500:5500 -p 8023:8080 -p 9043:8443 -p 9922:22 -e ORACLE_PWD=E container-registry.oracle.com/database/free:latest curl -o unattended_apex_install_23c.sh https://raw.githubusercontent.com/Pretius/pretius-23cfree-unattended-apex-installer/main/src/unattended_apex_install_23c.sh curl -o 00_start_apex_ords_installer.sh https://raw.githubusercontent.com/Pretius/pretius-23cfree-unattended-apex-installer/main/src/00_start_apex_ords_installer.sh docker cp unattended_apex_install_23c.sh 23cfree:/home/oracle docker cp 00_start_apex_ords_installer.sh 23cfree:/opt/oracle/scripts/startup docker start 23cfree
If on Unix, also run this to keep your container running after closing your connection:
loginctl enable-linger $UID
Now, wait around 20mins (and an additional 15mins if you haven’t previously fetched the docker image – it’ll download it automatically if you haven’t previously downloaded it). You can monitor the installation process using the following command (but perhaps wait 1 min before running it):
docker exec -it 23cfree /bin/bash tail -f /home/oracle/unattended_apex_install_23c.log
My run took 16m 40s (I had previously fetched the docker image), until it finally showed a ### APEX INSTALLED ### message.
When it’s done, you can use Ctrl+C to exit out of the log monitoring and go to http://localhost:8023/ords/apex to check it out.
If you ever restart the docker, APEX will back up and running in about 60 seconds. i.e It will not rerun the unattended install.
Credentials
APEX Internal Workspace
- User: ADMIN
- Password: OrclAPEX1999!
Everything else, e.g. ORDS_PUBLIC_USER, APEX_PUBLIC_USER, SYS, etc.
- Password: E
And that’s about it – enjoy! Also, the configuration script is open source, feel free to fork it. You can find the repository here. If – for some reason – you’d like to go through the process manually, you’ll find the original steps below.
(Original article) Manual setup
Install and run Docker
Firstly, these are the things you’ll need:
- Oracle 23c Free Database
- ORDS latest (24.1 at time of writing)
- Open JAVA 17 JDK
- latest Oracle APEX version (23.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).
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 this command:
su
And then follow with these:
cat /dev/null > /etc/dnf/vars/ociregion dnf update -y 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
It will give you the following seclection. Choose option 3.
Enter a number to select the TNS net service name to use or specify the database connection [1] EXTPROC_CONNECTION_DATA SID=PLSExtProc [2] FREE SERVICE_NAME=FREE [3] FREEPDB1 SERVICE_NAME=FREEPDB1 [S] Specify the database connection Choose [1]: 3
It will then ask for the database user name with administrator privileges. Choose user SYS and password E.
Provide database user name with administrator privileges. Enter the administrator username: SYS Enter the database password for SYS AS SYSDBA: E
It will then display the following menu:
Retrieving information. ORDS is not installed in the database. ORDS installation is required. Enter a number to update the value or select option A to Accept and Continue [1] Connection Type: TNS [2] TNS Connection: TNS_NAME=FREEPDB1 TNS_FOLDER=/opt/oracle/product/23c/dbhomeFree/network/admin Administrator User: SYS AS SYSDBA [3] Database password for ORDS runtime user (ORDS_PUBLIC_USER): <generate> [4] ORDS runtime user and schema tablespaces: Default: SYSAUX Temporary TEMP [5] Additional Feature: Database Actions [6] Configure and start ORDS in Standalone Mode: Yes [7] Protocol: HTTP [8] HTTP Port: 8080 [9] APEX static resources location: [A] Accept and Continue - Create configuration and Install ORDS in the database [Q] Quit - Do not proceed. No changes Choose [A]:
Choose option 9 – APEX static resources location. When prompted, enter the following:
/home/oracle/software/apex/images
Type A to continue. ORDS will then configure. It’ll take 1-2 minutes and finally load and show the following message.
<code class="lang-plaintext">2024-04-15T15:30:27.922Z INFO Oracle REST Data Services initialized Oracle REST Data Services version : 24.1.0.r0960841 Oracle REST Data Services server info: jetty/10.0.20 Oracle REST Data Services java info: OpenJDK 64-Bit Server VM 17.0.10+7-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