Getting Started

Get your Oracle 26ai database with APEX and ORDS running locally in just a few minutes. This guide will walk you through the complete setup process.

Prerequisites

Before you begin, make sure you have the following installed:

Required Software

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

Platform-Specific Notes

macOS Users

If you’re using macOS, read the Podman setup guide for additional configuration steps.

Windows Users

We recommend using WSL2 (Windows Subsystem for Linux) for the best experience. Follow these guides:

Quick Setup

1. Clone the Repository

git clone https://github.com/United-Codes/uc-local-apex-dev.git
cd uc-local-apex-dev

2. Make Scripts Executable

chmod +x ./local-26ai.sh ./setup.sh ./scripts/*.sh

3. Run Setup

# Setup the environment
./setup.sh

# Start the containers (use podman-compose if using Podman)
docker-compose up -d

4. Wait until DB and ORDS are ready

First wait until the docker containers are running:

docker-compose up -d
[+] Running 4/4
 ✔ Network uc-local-apex-dev_default Created
 ✔ Volume "oradata-26ai"             Created
 ✔ Container local-26ai              Healthy
 ✔ Container local-26ai-ords         Started

Then run this command to change the ORDS to use the proxied PL/SQL gateway mode:

docker exec -it local-26ai-ords bash -c \
"ords --config /etc/ords/config config --db-pool default set plsql.gateway.mode proxied"

Wait till http://localhost:8181/ords loads successfully in your browser. You should see the ORDS landing page. This can take 1 to 2 minutes depending on your system performance. You can follow the logs via docker-compose logs --follow.

5. Install APEX and configure DB

./scripts/after-first-db-start.sh

Optionally set up local SSL/HTTPS for ORDS.

If you want to save disk space you can remove the apex directory:

rm -rf ./apex

6. Restart ORDS

docker-compose restart ords-26ai

If you wait until http://localhost:8181/ords loads successfully, you should now see the APEX module loaded. Click go or go to http://localhost:8181/ords/apex to login.

If you get an error message saying “Account Is Locked” run the following:

./scripts/unexpire-accounts.sh

You can now reload the APEX page at http://localhost:8181/ords/apex and should see no more error messages.

If you don’t want APEX to force you to change passwords, you can also run the disable password expiration script:

./scripts/disable-password-expiration.sh

7. PATH Configuration

For easier script access, add the repository to your PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="/Users/username/path/to/uc-local-apex-dev:$PATH"

Then use scripts from anywhere:

local-26ai.sh create-user newproject
local-26ai.sh backup-all
local-26ai.sh stop

Next Steps

Now that your environment is running:

Create your first workspace: local-26ai.sh create-user myproject
Explore the available scripts: local-26ai.sh --help
Start developing your APEX applications

Access Your Environment

Once setup is complete, you can access:

APEX: http://localhost:8181/ords/apex
ORDS Landing: http://localhost:8181/ords/\_/landing
Database: ai:1521 (Service: FREEPDB1)

Default APEX Credentials

Username: admin or the schema/workspace name you created
Password: Welcome_1