Skip to content
uc-local-apex-dev

Getting Started

This guide installs an Oracle 26ai database with APEX and ORDS on your machine.

Before you start

Section titled “Before you start”

Install these programs first:

  • Docker or Podman — the scripts support both. They use docker when both are installed. On macOS, read the Podman setup guide.
  • Compose — the docker compose or podman compose subcommand. The standalone docker-compose and podman-compose tools do not work.
  • SQLcl with the sql command in your PATH. SQLcl needs a working Java runtime.
  • unzip, and curl or wget.
  • A bash-compatible shell.

On Windows, use WSL2 (Windows Subsystem for Linux). Oracle containers run better there than on native Windows. Then install everything above inside WSL2. These guides show the steps: Install Ubuntu on WSL2, Install docker in Ubuntu, and Install SQLcl in Linux.

Install

Section titled “Install”

  1. Clone the repository

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

  2. Run the installer

    Terminal window
    ./install.sh

    The installer asks no questions. It generates an .env file with a random SYS password, pulls the images, and starts the containers. Then it installs APEX with the defaults for development and configures ORDS.

    The installer needs 20 to 40 minutes. Most of that time is the download of the Oracle database image. At the end it shows a === Done === banner.

    If the shell reports Permission denied, then run:

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

    To read what each step does, or to select a container engine, read Installation Details.

  3. Log into APEX

    Open http://localhost:8181/ords/apex. Log in to the INTERNAL workspace with the user ADMIN. The password is the ORACLE_PASSWORD value from the generated .env file.

  4. Create your first workspace

    Terminal window
    ./local-26ai.sh create-user myproject

    This command creates a database schema and an APEX workspace. It also adds the new user to SQLcl and to VS Code.

    Log in to the new workspace with the user ADMIN and the password Welcome_1. This is a different password from the INTERNAL workspace. Read Creating Users for the options.

Access your environment

Section titled “Access your environment”

Default APEX credentials

Section titled “Default APEX credentials”
  • INTERNAL workspace: ADMIN / value of ORACLE_PASSWORD in .env
  • Your own workspaces (created with create-user): ADMIN or the schema name / Welcome_1 (or the value of ORACLE_PASSWORD when WORKSPACE_USE_INTERNAL_PASSWORD=true in .env)

The password of the database schema is not the APEX password. It is the generated <NAME>_USER_PASSWORD value in .env.

Next steps

Section titled “Next steps”

Run the commands from any directory

Section titled “Run the commands from any directory”

The local-26ai.sh wrapper gives you every feature of this project. To run it from any directory, add the repository to your PATH:

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

Useful commands

Section titled “Useful commands”

Run local-26ai.sh --help for the full list. These commands are the most useful ones for a new environment:

  • local-26ai.sh stop and local-26ai.sh start: shut the database down cleanly, then start it again.
  • local-26ai.sh backup-all: export every schema, APEX workspace, application, and ORDS module to ./backups/export. Read Backups.
  • local-26ai.sh test-app-install app.sql: install an APEX application export into a clean test schema, and show the invalid objects. Read Install Apps or Scripts.
  • local-26ai.sh used-space: show the used database space against the 12GB limit of the Free edition.
Section titled “More guides”