Getting Started

Get your Oracle 23ai 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.

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-23ai.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 untull the docker containers are running:

docker-compose up -d
[+] Running 4/4
 ✔ Network docker-apex-24-1_default  Created
 ✔ Volume "oradata"                  Created
 ✔ Container local-23ai              Healthy
 ✔ Container local-ords              Started

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 confiure DB

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

Optionally set up local SSL/HTTPS for ORDS.

If you want to save diskspace you can remove the apex directory:

rm -rf ./apex

6. Restart ORDS

docker-compose restart ords

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 messsage saying “Account Is Locked” do the following:

sql -name local-23ai-sys

Check which accounts are locked:

select username, account_status
  from dba_users
 where (username like 'APEX%' or username like 'ORDS%')
   and not regexp_like(username, 'APEX_[0-9]+');

For any locked accounts, run (change c_username value):

DECLARE
  c_username CONSTANT VARCHAR2(128) := 'APEX_PUBLIC_USER';
  l_unexpire_command VARCHAR2(4000);
BEGIN
  EXECUTE IMMEDIATE 'ALTER USER ' || c_username || ' ACCOUNT UNLOCK';

  SELECT 'alter user ' || name || q'< identified by values '>' || spare4 || ';' || password || q'<'>'
    INTO l_unexpire_command
    FROM sys.user$
   WHERE name = c_username;

  EXECUTE IMMEDIATE l_unexpire_command;
END;
/

If you re-run the query, you should see that the account is now unlocked. Exit the sql shell with exit;.

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

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-23ai.sh create-user newproject
local-23ai.sh backup-all
local-23ai.sh stop

Next Steps

Now that your environment is running:

Create your first workspace: local-23ai.sh create-user myproject
Explore the available scripts: local-23ai.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