Run Oracle APEX 26.1 Locally

I have been maintaining and daily driving uc-local-apex-dev for over a year now. My take is that a local development environment empowers developers (and especially AI agents) to quickly develop, test, and iterate on their code without the friction of deploying to a shared environment. I already wrote about it in a previous blog post.

That’s why, beyond just a docker-compose file, uc-local-apex-dev also includes a set of scripts to help you fix issues so you don’t have to fight your setup:

• Scripts
  • create-user: Adds a new DB schema, adds an APEX workspace, REST enables it, gives common grants, and adds the connection to SQL Developer.
  • clear-schema: Drops all objects in a schema, useful to quickly reset your environment
  • backup-all: Exports all data, APEX apps, and ORDS REST definitions to a backup folder. It can be restored with an import script.
  • test-script-install: Runs a SQL script in an empty schema and tells you whether it succeeded or not.
• Maintained: If there is a new DB or ORDS release, I show you how to upgrade your local environment safely and keep it up to date.
• Nice default settings: APEX sessions don’t time out, APEX is installed in its own tablespace, disk space saving settings, optional local HTTPS, etc.

See more details on the project page.

These are the prerequisites:

• Docker or podman (or any Docker-compatible container runtime)
• docker-compose / podman-compose
• SQLcl with the sql command in PATH
• Bash-compatible shell

If you are on macOS, you can follow this guide on how to use podman as the runtime with the Docker CLI. For Windows users, I highly recommend using WSL2, which allows you to run it in a native Linux environment.

If you are ready, you can follow the installation guide. You will have a local 26ai database with APEX 26.1 and ORDS 26.1.1 up and running in no time.

This depends on which version you are currently running. Open the folder where you have uc-local-apex-dev installed and check the version with git branch --show-current.

Perfect! You are already on the latest version. Just run these commands from the folder where you have uc-local-apex-dev installed to update your local environment:

./local-26ai.sh stop
git pull
./local-26ai.sh start
./local-26ai.sh upgrade-apex

I recommend first upgrading to 26.2 and then following the instructions above. See the migrate to 26.2 guide for more details.

You are still on a 23ai database. Unfortunately, the upgrade to 26ai requires exporting all data, creating a new database, and importing everything again. So here are your options:

Start over — I don’t care about my data

Choose this if you only use your local environment for experiments or quick tests and don’t mind losing what’s currently in it. You delete your current environment and start with a fresh and clean 26ai db:

docker-compose down
docker volume rm oradata
rm .env

Then you can switch to the 26.2 branch and follow the installation guide to set up a new 26ai environment.

Run APEX 26.1 with the 23ai database

Choose this if you want to try out APEX 26.1 right now but aren’t ready to deal with a database upgrade yet. You keep your existing 23ai database and only swap in the new APEX version. This is totally fine, and you can still upgrade to 26ai later:

#!/usr/bin/env bash

set -e

source ./scripts/util/load_env.sh
source ./scripts/util/get_ws_settings.sh

echo "Downloading APEX"

rm -rf ./apex || true
rm -rf ./apex-images || true

wget https://download.oracle.com/otn_software/apex/apex-latest.zip
unzip apex-latest.zip
rm apex-latest.zip
rm -rf ./META-INF || true

echo "Installing APEX"

cd ./apex || exit 1

sql -name "$DB_CONN_NAME" <<SQL
@apexins.sql SYSAUX SYSAUX TEMP /i/
exit;
SQL

Upgrade to 26ai

Choose this if you want to keep your existing data and move to the latest stack. Follow all the migration guides relevant to your current version to get to 26.2, and then follow the instructions in the 26.2 section above.

Have fun testing the new features of APEX 26.1!