Skip to content
/ oracle-database Public

This development environment combines Oracle Database 23c Free Edition with modern tooling for an optimal learning and development experience:

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

demasy/oracle-database

BranchesTags

Repository files navigation

🛠 Oracle Database Development Environment

License Oracle Database Docker Node.js PRs Welcome

🚀 Explore, Learn, and Build with Oracle Database 23c

A modern containerized environment for database development and learning


This development environment combines Oracle Database 23c Free Edition with modern tooling for an optimal learning and development experience:

Core Components:

  • 📦 Oracle Database 23c - Latest features and capabilities
  • 🔧 Node.js Management Server - Modern API and monitoring
  • 🐳 Docker Containers - Consistent and portable setup
  • ⚡ SQLcl Integration - Advanced database interaction tools

Perfect For:

  • � Development - Rapid prototyping and application development
  • 🔬 Testing - Isolated environment for feature testing
  • � Learning - Hands-on database administration practice
  • 🏫 Training - Structured workshops and courses
  • 🧪 Research - Database feature exploration and testing

Designed and maintained by Demasy to provide a consistent, reproducible database workspace across any development machine.


📋 Prerequisites

Required

  • Docker Engine 24.0.0+
  • Docker Compose v2.20.0+
  • 4GB RAM, 10GB storage
  • Ports: 1521 (DB), 5500 (EM), 3000 (API)

Recommended

  • SQLcl for database operations
  • Container orchestration experience
  • Basic Oracle Database knowledge

🚀 Quick Start Guide

📥 Installation

Clone Repository
git clone https://github.com/demasy/oracle-database.git
cd oracle-database

⚙️ Configuration

Set Up Environment
# Create configuration file from template
cp .env.example .env
chmod 600 .env        # Set secure file permissions
Configure Database
# Required Settings
ORACLE_PWD=your_secure_password      # Database admin (SYS/SYSTEM) password
DATABASE_NAME=DEMASY                 # Your database name (max 8 chars)

# Regional Settings
TZ=Asia/Riyadh                      # Container timezone
Optional Settings
# Connection Pool (defaults shown)
DEMASYLABS_DB_POOL_MIN=1            # Minimum connections
DEMASYLABS_DB_POOL_MAX=5            # Maximum connections
DEMASYLABS_DB_POOL_INCREMENT=1      # Growth increment

# Network Settings (defaults shown)
DEMASYLABS_DB_PORT=1521             # Database listener port
DEMASYLABS_DB_SERVICE=FREE          # Service name

🔒 Security Notes:

  • Use a strong password (min. 8 chars, mixed case, numbers, symbols)
  • Never commit .env to version control
  • Keep file permissions restricted to owner only
  • Change default passwords after first login

🏗 Build Process

Build Docker Services
# Clean build without cache
docker-compose build --no-cache

🌟 Launch

Start Services
Option 1: Launch All Services
# Start in interactive mode (with logs)
docker compose up

# Or in detached mode (background)
docker compose up -d
Option 2: Start Database Only
# Start database in background
docker compose up -d demasylabs-oracle-database

# View initialization progress
docker logs -f oracle-database-23ai
Option 3: Start Management Server Only
# Start server in background
docker compose up -d demasylabs-oracle-server

# View server logs
docker logs -f demasy-server
Option 4: Development Mode
# Start database in background, server in foreground
docker compose up -d demasylabs-oracle-database
docker compose up demasylabs-oracle-server

✅ Verification

Check Database Status
# Wait for database initialization (approx. 5-10 minutes)
docker logs -f oracle-database-23ai
Verify Server Health
# HTTP endpoint health check
curl http://localhost:3000/health

# Expected response:
# {"status":"healthy","timestamp":"YYYY-MM-DD HH:mm:ss"}
Test Database Connection
# Connect to management server
docker exec -it demasy-server bash

# Run SQLcl connection test
sqlcl

🎯 Features

  • Oracle Free Database 23c
  • Node.js-based management server
  • Oracle SQLcl integration
  • Automated health monitoring
  • Connection pooling
  • Custom networking
  • Resource management
  • Persistent logging

🔐 Environment Setup

# Copy template and edit
cp .env.example .env

# Required Settings
ORACLE_PWD=your_secure_password     # Database system password
TZ=Asia/Riyadh                      # Timezone
DATABASE_NAME=DEMASY                # Database name

# Connection Settings (preconfigured)
DEMASYLABS_DB_HOST=oracle-database-23ai
DEMASYLABS_DB_PORT=1521
DEMASYLABS_DB_SERVICE=FREE
DEMASYLABS_DB_POOL_MAX=5

🔒 Security: Never commit .env file to version control

🏗 Architecture

The environment consists of two main containerized services:

Database Service

demasylabs-oracle-database

Component Details
Base Image Oracle Free Database 23c
Container Name oracle-database-23ai
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

Management Server

demasylabs-oracle-server

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

⚙️ Service Management

Container Operations

Database Service

Stop Database
docker stop oracle-database-23ai
Start Database
docker start oracle-database-23ai
Restart Database
docker restart oracle-database-23ai
Remove Database Container
docker rm -f oracle-database-23ai
Access Database Shell
docker exec -it oracle-database-23ai bash
View Database Logs
# View all logs
docker logs oracle-database-23ai

# Follow logs in real-time
docker logs -f oracle-database-23ai

# View last 100 lines
docker logs --tail 100 oracle-database-23ai

# View logs with timestamps
docker logs -t oracle-database-23ai
Monitor Database
# View container details
docker inspect oracle-database-23ai

# View resource usage
docker stats oracle-database-23ai

# Check container health
docker inspect --format='{{.State.Health.Status}}' oracle-database-23ai
Database Port Status
# Check if database port is listening
netstat -an | grep 1521

# Check Enterprise Manager Express port
netstat -an | grep 5500
Backup Database
# Create a backup of the container
docker commit oracle-database-23ai oracle-db-backup:$(date +%Y%m%d)

Management Server

Stop Server
docker stop demasy-server
Start Server
docker start demasy-server
Restart Server
docker restart demasy-server
Remove Container
docker rm -f demasy-server
Access Shell
docker exec -it demasy-server bash
View Logs
# View all logs
docker logs demasy-server

# Follow logs in real-time
docker logs -f demasy-server

# View last 100 lines
docker logs --tail 100 demasy-server
Check Container Status
# View container details
docker inspect demasy-server

# View resource usage
docker stats demasy-server

🔌 Database Connectivity

Connection Methods

1. SQL*Plus (Traditional)

sqlplus / as sysdba

2. Oracle SQLcl (Modern CLI)

Multiple connection options available:

a. Using Preconfigured Aliases (Recommended)
# From management server container
sqlcl     # Primary connection command
oracle    # Alternative alias
b. Using Direct SQL Command
sql       # Uses symlink in /usr/local/bin
c. Using Custom Connection String
sql ${username}/${password}@localhost:1521/FREE as sysdba

Connection Parameters

Parameter Environment Variable Default Value
Host DEMASYLABS_DB_HOST oracle-database-23ai
Port DEMASYLABS_DB_PORT 1521
Service DEMASYLABS_DB_SERVICE FREE
SID DEMASYLABS_DB_SID FREE
User DEMASYLABS_DB_USER system
Password ORACLE_PWD from .env

Connection Pool Settings

Parameter Value Environment Variable
Minimum Size 1 DEMASYLABS_DB_POOL_MIN
Maximum Size 5 DEMASYLABS_DB_POOL_MAX
Increment 1 DEMASYLABS_DB_POOL_INCREMENT
  • Hostname: localhost (or 192.168.1.10)
  • Port: 1521
  • Service Name: FREE
  • SID: FREE
  • Default User: system
  • Database Name: DEMASY

Monitoring and Logs

  • Database logs are managed with JSON file driver
    • Max size: 10MB per file
    • Max files: 3
  • Application logs are stored in the demasylabs_logs volume
  • Health checks run every 30 seconds for both services

Health Check

You can check the server's health status in two ways:

  1. Using HTTP endpoint:
curl http://localhost:3000/health

or open in your browser:

  1. Using command line:
# Connect to the server container
docker exec -it demasy-server bash

# Run health check
healthcheck

Expected output if healthy:

Server is healthy.

Note: The health check runs automatically every 30 seconds as part of the container's health monitoring.

Network Configuration

  • Custom network: demasylabs_network
  • Subnet: 192.168.1.0/24
  • Database IP: 192.168.1.10
  • Server IP: 192.168.1.20

👤 Author

Ahmed El Demasy

Built with ❤️ by Demasy

About

This development environment combines Oracle Database 23c Free Edition with modern tooling for an optimal learning and development experience:

Topics

docker oracle oracle-database oracle-developer oracle-database-23ai

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages