The Oracle AI Database 26ai Free - Developer Environment offers a clean, fully containerized development stack designed for modern application development, in-depth technical learning, and hands-on exploration of Oracle's latest AI-powered capabilities. By combining Oracle Database 26ai Free, APEX 24.2, ORDS 25.3, and SQLcl into a unified Docker-based environment, this setup simplifies installation. It provides a consistent, reproducible workspace across macOS, Linux, and Windows WSL2 environments.
This environment is specifically tailored for PL/SQL developers, APEX builders, database administrators (DBAs), architects, instructors, and the broader Oracle community. It serves as a reliable and portable foundation for rapid prototyping, REST API development, workshops, and classroom training. Users can discover and test the latest features of Oracle Database 26ai, experiment with AI-enhanced SQL and application patterns, and build full-stack solutions all without requiring production-scale infrastructure.
Designed to facilitate learning through practical experience, this setup allows users to start instantly, iterate quickly, reset easily, and explore safely. With its isolated, predictable, and developer-friendly design, this environment accelerates experimentation, promotes community adoption, and helps professionals stay current with Oracle's evolving innovations. Whether you're showcasing new features, teaching future Oracle developers, contributing to community knowledge, or building internal tools, this environment provides a fast, modern, and reliable foundation for your projects.
⚠️ DEVELOPMENT AND TRAINING ENVIRONMENT ONLYThis environment is intended solely for development, testing, evaluation, and educational purposes. It is not secured, hardened, or optimized for production workloads. For production-grade deployments, organizations should consult Oracle's official deployment guidelines and work with Oracle Support or certified Oracle partners to ensure appropriate architecture, security, and compliance.
- Overview
- Key Features
- Use Cases
- Prerequisites
- Getting Started
- Architecture
- Built-in Tools & Scripts
- Configuration
- Troubleshooting / FAQ
- Documentation
- Change Log / Release History
- Contributors
- License
- Oracle Database 26ai Free, preconfigured for local development
- APEX 24.2 + ORDS 25.3 fully integrated and ready to use
- SQLcl & SQL*Plus included for scripting, labs, and automation
- Clean Docker Compose setup (Database + Management Server)
- Compatible with Linux, macOS (Intel/ARM), and Windows WSL2
- Simple environment variables and port mapping for easy configuration
- Built-in scripts for APEX installation, health checks, and utilities
- Developer-friendly structure ideal for training, demos, and workshops
| Use Case | Description |
|---|---|
| Isolated Development and Testing Environment | Reproducible, containerized Oracle instances that enable developers to test changes, isolate work streams, and keep clean project environments without impacting the local system. |
| Technology Exploration and Feature Discovery | A secure, isolated sandbox for exploring Oracle AI Database’s newest features, enhancements, and modern development workflows, enabling developers to learn through experimentation. |
| Proof of Concept (POC) | A flexible, temporary environment for creating prototypes, validating technical approaches, and showcasing Oracle AI Database capabilities without the complexity of a complete production infrastructure. |
| APEX Application Development | An all-in-one, low-code development platform featuring APEX 24.2, ORDS 25.3, and database services. Ideal for designing, testing, and deploying enterprise-level applications. |
| Community, Collaboration, and Open Source | A shared workspace that supports testing, collaborative projects, hackathons, knowledge exchange, and community-driven innovation within the Oracle ecosystem. |
| Professional Training and Education | A comprehensive, hands-on learning platform focusing on Oracle Database, SQL, PL/SQL, APEX, and Oracle REST Data Services (ORDS). Perfect for instructors, workshops, bootcamps, certification preparation, and Oracle community training projects. |
| Resource | Minimum | Recommended |
|---|---|---|
| Operating System | - | Linux, macOS, or Windows with WSL2 |
| CPU | 2 cores (x86_64 or ARM64) | 2+ cores (x86_64 or ARM64) |
| RAM | 4 GB | 8 GB or more |
| Disk Space | 12 GB free | 20+ GB available disk space |
| Swap Space | - | 2 GB (or twice RAM) |
| Docker Engine | - | 24.0.0 or later |
| Docker Compose | - | v2.20.0 or later |
- Docker Desktop (or Docker Engine + Docker Compose): Required for running and managing all containers.
- Git: Used for cloning the repository and pulling updates.
- Visual Studio Code: Ideal for editing configuration files, environment variables, and scripts. It also offers excellent support through Docker and SQL/PLSQL extensions.
- Modern Web Browser: Necessary for accessing APEX and ORDS. Supported browsers include Chrome, Firefox, Edge, and Safari.
- Internet Connection: Required to download Docker images during the initial setup.
- Docker Network: The default subnet is 192.168.1.0/24 (this is customizable in the docker-compose.yml file).
- Firewall Permissions: Docker must be granted permission to create and manage local container networks.
- Open Host Ports: Ensure that the following ports are not in use by other services:
| Port | Service | Protocol |
|---|---|---|
| 3000 | Demasy Labs Management Server | HTTP |
| 8080 / 8443 | ORDS and APEX web access | HTTP |
| 1521 | Oracle Database Listener | TCP |
| 5500 | Enterprise Manager (optional) | HTTP |
| 3000 | Management API | HTTP |
| 8080 | Oracle ORDS/APEX | HTTP |
📌 Notes
- Oracle Database, SQLcl, and SQL*Plus are pre-installed in the container - no separate installation required.
- Oracle APEX and ORDS must be installed manually using the provided script inside the container.
bash /usr/demasy/scripts/apex/install-apex.sh
git clone https://github.com/demasy/oracle-database.git
cd oracle-databasecp .env.example .env
chmod 600 .envEdit .env and set the following required parameters:
# Absolutely Required - Container Won't Start Without These
ENV_DB_PASSWORD=YourSecurePassword123!
ENV_DB_SID=FREE
ENV_DB_SERVICE=FREEPDB1
ENV_DB_CHARACTERSET=AL32UTF8
ENV_NETWORK_SUBNET=192.168.1.0/24
ENV_NETWORK_GATEWAY=192.168.1.1
ENV_IP_DB_SERVER=192.168.1.110
ENV_IP_APP_SERVER=192.168.1.120
ENV_DB_PORT_LISTENER=1521
ENV_SERVER_PORT=3000
ENV_DB_POOL_MIN=1
ENV_DB_POOL_MAX=5
ENV_DB_POOL_INCREMENT=1
ENV_DB_USER=system
ENV_DB_CLIENT=/opt/oracle/instantclient
ENV_DB_CPU_LIMIT=2
ENV_DB_MEMORY_LIMIT=4g
ENV_SERVER_CPU_LIMIT=3.0
ENV_SERVER_MEMORY_LIMIT=3g
ENV_SRC_ORACLE_SQLCL=https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip
ENV_SRC_ORACLE_SQLPLUS=https://download.oracle.com/otn_software/linux/instantclient/2390000/instantclient-sqlplus-linux.arm64-23.9.0.25.07.zip
ENV_SRC_ORACLE_APEX=https://download.oracle.com/otn_software/apex/apex-latest.zip
ENV_SRC_ORACLE_ORDS=https://download.oracle.com/otn_software/java/ords/ords-latest.zip
# Required Only If Using APEX
ENV_APEX_ADMIN_PASSWORD=YourAPEXPassword123
ENV_APEX_ADMIN_USERNAME=ADMIN
ENV_APEX_EMAIL=your-email@example.com
ENV_APEX_DEFAULT_WORKSPACE=INTERNALSecurity Best Practices:
- Use strong passwords with mixed case, numbers, and symbols
- Never commit
.envfiles to version control- Restrict file permissions to owner only (
chmod 600)- Rotate passwords regularly in production environments
- Use different credentials for each environment
Build the Docker images with a clean build:
docker-compose build --no-cacheStart all services in detached mode:
docker-compose up -dStart with real-time logs for debugging:
docker-compose upTo stop, press Ctrl+C and run:
docker-compose downStart only specific services:
# Database only
docker-compose up -d demasylabs-oracle-database
# Management server only
docker-compose up -d demasylabs-oracle-serverdocker ps --filter "name=oracle-al-database-26ai" --filter "name=demasy-server"Expected output:
CONTAINER ID IMAGE STATUS PORTS
abc123def456 oracle-database:26ai Up 2 minutes (healthy) 0.0.0.0:1521->1521/tcp
def456ghi789 demasy-server:latest Up 2 minutes (healthy) 0.0.0.0:3000->3000/tcp
Monitor database startup (takes 5-10 minutes on first run):
docker logs -f oracle-al-database-26aiLook for: DATABASE IS READY TO USE!
Test the management server:
curl http://localhost:3000/healthExpected response:
{
"status": "healthy",
"timestamp": "2025-11-25T12:00:00.000Z"
}Access the management container:
docker exec -it demasy-server bashConnect to the database:
sqlclExpected output:
Connected to:
Oracle AI Database 26ai Free Release 23.26.0.0.0 - Develop, Learn, and Run for Free
Version 23.26.0.0.0
SQL>
# 1. Clone and setup
git clone https://github.com/demasy/oracle-database.git
cd oracle-database
cp .env.example .env
# Edit .env with your configuration
# 2. Build and start
docker-compose build --no-cache
docker-compose up -d
# 3. Verify
docker ps
docker logs -f oracle-al-database-26ai # Wait for "READY TO USE"
curl http://localhost:3000/health
# 4. (Optional) Run the APEX & ORDS installer inside the database container
docker exec -it oracle-db-container bash
/usr/demasy/scripts/apex/install-apex.sh
exit
# APEX / ORDS Web UI: open http://localhost:8080 (or your configured port) in a browser
# 5. Connect
docker exec -it demasy-server sqlclThe environment consists of two primary containerized services:
┌───────────────────────────────────────────────────────┐
│ Docker Environment │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Management │ │ Oracle AI │ │
│ │ Server │◄────────┤ Database 26ai │ │
│ │ (Node.js) │ │ + APEX 24.2 │ │
│ │ │ │ + ORDS 25.3 │ │
│ │ - Health Check │ │ │ │
│ │ - API Endpoints │ │ Ports: │ │
│ │ - SQLcl Client │ │ - 1521 (DB) │ │
│ │ │ │ - 5500 (EM) │ │
│ │ Port: 3000 │ │ - 8080 (ORDS) │ │
│ └──────────────────┘ └──────────────────┘ │
│ 192.168.1.20 192.168.1.10 │
└───────────────────────────────────────────────────────┘
| Component | Details |
|---|---|
| Base Image | Oracle AI Database 26ai Free Edition |
| Container Name | oracle-al-database-26ai |
| Database Name | DEMASY |
| Exposed Ports | • 1521 (Database Listener) • 5500 (Enterprise Manager Express) |
| Network | 192.168.1.10 |
| Resources | • CPU: 1 core • Memory: 3GB |
| Health Check | Every 30s via SQL connectivity test |
| Component | Details |
|---|---|
| Base Image | Node.js 20.19.4 |
| Container Name | demasy-server |
| Exposed Port | 3000 (API & Health Check) |
| Network | 192.168.1.20 |
| Resources | • CPU: 1 core • Memory: 512MB |
| Integrations | • Oracle SQLcl • Oracle APEX • Oracle Instant Client 23.7 |
| Connection Pool | • Min: 1 • Max: 5 • Increment: 1 |
| Component | Version | Release Date | Status |
|---|---|---|---|
| Oracle AI Database | 26ai Free | 2025 | ✅ Production-Ready |
| Oracle APEX | 24.2.0 | October 2024 | ✅ Current Release |
| Oracle ORDS | 25.3.1 | November 2024 | ✅ Current Release |
| Oracle SQLcl | 25.3 | November 2024 | ✅ Current Release |
| Oracle Instant Client | 23.7 | 2024 | ✅ Stable |
| Node.js | 20.19.4 LTS | 2024 | ✅ Long-Term Support |
| Docker Engine | 24.0.0+ | - | ✅ Required |
| Docker Compose | v2.20.0+ | - | ✅ Required |
| Platform | Architecture | SQL*Plus | SQLcl | APEX | Status |
|---|---|---|---|---|---|
| Linux (Ubuntu/Debian) | AMD64 (x86_64) | ✅ | ✅ | ✅ | Fully Supported |
| Linux (Ubuntu/Debian) | ARM64 (aarch64) | ✅ | ✅ | Supported | |
| macOS (Intel) | AMD64 (x86_64) | ✅ | ✅ | ✅ | Fully Supported |
| macOS (Apple Silicon) | ARM64 (M1/M2/M3) | ✅ | ✅ | Supported | |
| Windows (WSL2) | AMD64 (x86_64) | ✅ | ✅ | ✅ | Supported |
⚠️ Note: SQL*Plus is not natively available on ARM64. SQLcl is automatically used as a fallback.
All scripts are organized in a structured directory layout for better maintainability:
Container Path Structure:
/usr/demasy/scripts/
├── cli/ # User-facing CLI tools
│ ├── sqlcl-connect.sh # SQLcl database connection
│ └── sqlplus-connect.sh # SQL*Plus connection
│
├── oracle/
│ ├── admin/ # Administrative tools
│ │ └── healthcheck.sh # System health monitoring
│ │
│ ├── apex/ # APEX management
│ │ ├── install.sh # APEX + ORDS installation
│ │ ├── uninstall.sh # APEX removal
│ │ ├── start.sh # Start ORDS
│ │ └── stop.sh # Stop ORDS
Command Aliases:
| Command Alias | Target Script | Purpose |
|---|---|---|
sqlcl |
/usr/demasy/scripts/cli/sqlcl-connect.sh |
Connect via SQLcl |
sqlplus |
/usr/demasy/scripts/cli/sqlplus-connect.sh |
Connect via SQL*Plus |
oracle |
/usr/demasy/scripts/cli/sqlcl-connect.sh |
Alias for SQLcl |
healthcheck |
/usr/demasy/scripts/oracle/admin/healthcheck.sh |
Run health check |
install-apex |
/usr/demasy/scripts/oracle/apex/install.sh |
Install APEX |
uninstall-apex |
/usr/demasy/scripts/oracle/apex/uninstall.sh |
Remove APEX |
start-apex |
/usr/demasy/scripts/oracle/apex/start.sh |
Start ORDS |
stop-apex |
/usr/demasy/scripts/oracle/apex/stop.sh |
Stop ORDS |
📝 Note: All scripts are organized using best practices with a flat structure (max three levels). For detailed documentation, see
src/scripts/README.md.
For comprehensive guides, see the src/docs directory:
- Service Management - Container operations, logs, and diagnostics
- Oracle APEX Installation - APEX setup, ORDS configuration, and endpoints
- Database Connectivity - Connection methods, parameters, and examples
- Monitoring & Logs - Health checks, logging, and resource monitoring
- Configuration Reference - Environment variables and settings
- Troubleshooting - Common issues and solutions
| Version | Date | Type | Description |
|---|---|---|---|
| v1.0.0 | 2025-12-01 | Release | Foundation Release initial public release including Oracle 26ai Free, APEX 24.2, ORDS 25.3, SQLcl, Docker Compose setup, core scripts, and full documentation. |
- Oracle Database 26ai Free container image
- APEX 24.2, ORDS 25.3, SQLcl integration
- Docker Compose setup (DB + Management Server)
- Core shell scripts (healthcheck, install-apex, SQLcl / SQL*Plus helpers)
- Complete documentation, including architecture diagram, environment variable descriptions, usage instructions, and directory structure
| Author | GitHub & LinkedIn account |
|---|---|
 Ahmed El-Demasy (Creator & Maintainer) Oracle Solutions Architect Oracle ACE |
We welcome you to join and contribute to the Oracle AI Database 26ai Free - Docker Development Environment. If you are interested in helping, please don’t hesitate to contact us at founder@demasy.io
If you find any issue or have a great idea in mind, please create an issue on GitHub.
This project is licensed under the MIT License - see the LICENSE file for details.
Code with love ❤️ in Egypt for the Oracle development community.