How to Run Oracle APEX on your Local Machine
There are several great blog posts on this topic. In particular, this on from United Codes covers the details of each step. Marwa and I also did an APEX Instant Tip (episode 191) on this topic. This post expands upon that tip.
I have found that just asking an LLM (ChatGPT, Claude, etc.) to help you set up a local APEX environment does not go well. If you give it a little guidance, though, you can probably get there. The steps below are the high level steps. I will give more detail below them.
**Note (29-May2026): APEX 26.1 wants you to install ORDS before installing APEX. That means you need to swap steps 7 & 9.
Download and install a modern version of Java (if not already installed)
Download and install SQLcl (if not already installed)
Download, install, and run Docker Desktop (if not already installed)
Get the latest Docker image of the Oracle free database
Run that Docker image (port forwarding ports 1521) (this is FREEPDB1)
Download APEX on YOUR LOCAL MACHINE
**Install APEX (from your local machine) into the FREEPDB1 (in your Docker container)
Download ORDS on YOUR LOCAL MACHINE
**Install ORDS on YOUR LOCAL MACHINE pointed to FREEPDB1
**Note (29-May2026): APEX 26.1 wants you to install ORDS before installing APEX. That means you need to swap steps 7 & 9.
Steps 1-3
Steps 1-3 are up to you to do. They are a little different on Windows or Mac, but they are easy to do. All of these steps should be done on your local machine. That is to say, you should be able to run SQLcl on your local machine.
Step 4
You could skip step 4 and just go to step 5, but I like to do it in two steps. Step 4 takes a long time, so I like to know that I have accomplished it before moving to step 5. In order to do step 4, you need to have the Docker Desktop running. If you just installed Docker Desktop and have not used it yet, you will have something that looks like this:
From the command line, issue the following command (or, for what is currently truly the latest, the command below this command):
% docker pull container-registry.oracle.com/database/free:latest
This will download the latest version of the free database. If you want a specific version, and additional context and instructions, see the Oracle page related to this. For example, you may wish to explicitly get the 23.26.1 version (which, oddly, as of this writing, is more current than the "latest" version):
docker pull container-registry.oracle.com/database/free:23.26.1.0
Note: The Oracle page referenced above gives instructions to use Podman. That is fine as well. I happen to already use Docker, so Docker was my choice.
Step 5
Run the docker image from the command line. CHANGE THE PASSWORD that you see below. Also CHANGE THE PATH specified in -v (or leave out -v altogether). Read this whole section to understand the parameters prior to blindly running the command ;)
% docker run -d \
--name apex-db \
-p 1521:1521 \
-e ORACLE_PWD=abc123ABCyadayadayada \
-v ~/oware/docker/dbfree_apex_db/oradata:/opt/oracle/oradata \
container-registry.oracle.com/database/free:latest
or, if like me, you want 23.26.1.0
% docker run -d \
--name apex-db \
-p 1521:1521 \
-e ORACLE_PWD=abc123ABCyadayadayada \
-v ~/oware/docker/dbfree_apex_db/oradata:/opt/oracle/oradata \
container-registry.oracle.com/database/free:23.26.1.0
Below is a quick description of that command:
% docker run -d \
^^^ this tells docker to create/run a container
--name apex-db \
^^^ this is the container name
-p 1521:1521 \
^^^ tells Docker to map the local port 1521 to the container virtual port 1521 for SQLNet traffic
-e ORACLE_PWD=abc123ABCyadayadayada \
^^^ this is the database SYS password
-v ~/oware/docker/dbfree_apex_db/oradata:/opt/oracle/oradata \
container-registry.oracle.com/database/free:latest
^^^ This tells docker that I want to map the container's filesystem directory /opt/oracle/oradata to my local OS directory ~/oware/docker/dbfree_apex_db/oradata. If I destroy my container, the local directory with my database files will not get deleted.
Once you run this command you will see something like this in your Docker Desktop:
Mine shows apex-db and apex-db2 because I've done this a couple of times. (Note the different port mapping. That allows me to run two databases at the same time. I changed --name, -p, and -v to run it multiple times.)
The first time you do this it will take some time for it to run. You can follow the output with the following commands:
% docker logs apex-db
% docker logs -f apex-db
You interact with the Docker container by first opening a bash terminal. It will look something like this:
% docker exec -it apex-db bash
bash-4.4$ whoami
oracle
bash-4.4$ pwd
/home/oracle
Once you execute "docker exec -it apex-db bash" the rest of the commands are within the Docker container.
6. Download APEX -- ON YOUR LOCAL MACHINE
It's important to do this step on your local machine. This is because the Docker image is really only good for the database. It's very hard to run the middle tier component on that Docker image, so we are going to run the middle tier on the local OS. Below is the link to download APEX.
https://www.oracle.com/tools/downloads/apex-downloads/
7. Install APEX (from your local machine) into the FREEPDB1 (in your Docker container)
**Note (29-May2026): APEX 26.1 wants you to install ORDS before installing APEX. That means you need to swap steps 7 & 9.
You can follow the APEX install guide, but this is basically how you do it. You run the commands below ON YOUR LOCAL MACHINE:
% sql sys/your_password_here@localhost:1521/FREEPDB1 as sysdba
SQL> ALTER SESSION SET CONTAINER=FREEPDB1;
SQL> @apexins.sql SYSAUX SYSAUX TEMP /i/
SQL> @apxchpwd.sql
SQL> alter user apex_public_user account unlock;
Note that your database appears to be running on "localhost" port 1521. This is because when you ran the Docker container you mapped port 1521 on localhost to port 1521 in the container.
8. Download ORDS on YOUR LOCAL MACHINE
It's important to do this step on your local machine. This is because the Docker image is really only good for the database. It's very hard to run the middle tier component on that Docker image, so we are going to run the middle tier on the local OS. Below is the link to download ORDS.
https://www.oracle.com/database/sqldeveloper/technologies/db-actions/download/
9. Install ORDS on YOUR LOCAL MACHINE pointed to FREEPDB1
**Note (29-May2026): APEX 26.1 wants you to install ORDS before installing APEX. That means you need to swap steps 7 & 9.
It's important to do this step on your local machine. This is because the Docker image is really only good for the database. It's very hard to run the middle tier component on that Docker image, so we are going to run the middle tier on the local OS. I've said that three times now ;) Below are instructions to install and configure ORDS. Be sure to copy the APEX images to whatever location you define for images for ORDS.
The main command to install ORDS after downloading it is
% ords --config /etc/ords/config install
Notes
You can change /etc/ords/config above to any directory you want. It will hold the ORDS config info (obviously).
I prefer to run in TLS/SSL/HTTPS mode. When you go through the interactive install (when you run the command above), it will give you the option to set this up. Be sure to read everything along the way during the interactive install. If you just accept the defaults, you will end up running http (not https). While this is "fine," you will likely want to test things as they will be in a "real" environment. You might as well set it up for https now.
Be sure to select the option to set your "APEX Static resources location" (currently option [9]. Enter the filesystem path to your APEX image directory (part of the APEX download you did above).
Run APEX
That's it. If you have done everything above, APEX should be available at
or, if you set up to run via SSL on port 8443
Follow instructions for starting and stopping ORDS found in the ORDS documentation. If you shut things down, you first have to start your Docker container (using the Docker Desktop), then start ORDS. I use this command (from within my ORDS config directory) to start ORDS in the background:
nohup ords serve > ~/ords.log 2>&1 &