supalerk-ar66 ca65dbff4c feat: Add initial Docker setup and development environment documentation.

2026-02-05 11:01:17 +07:00

16 KiB

Raw Blame History

Development Environment Setup Guide

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Developer Machines                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Frontend    │  │  Frontend    │  │   Backend    │      │
│  │  (Student)   │  │  (Admin)     │  │   (API)      │      │
│  │  Port: 3000  │  │  Port: 3001  │  │  Port: 4000  │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                  │                  │              │
│         └──────────────────┴──────────────────┘              │
│                            │                                 │
└────────────────────────────┼─────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│              Proxmox Server (Shared Services)                │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Docker Compose Stack                     │  │
│  │                                                        │  │
│  │  ┌────────────┐  ┌────────────┐                    │  │
│  │  │ PostgreSQL │  │   MinIO    │                    │  │
│  │  │ Port: 5432 │  │ Port: 9000 │                    │  │
│  │  └────────────┘  └────────────┘  └────────────┘     │  │
│  │                                                        │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐     │  │
│  │  │  Mailhog   │  │   Adminer  │  │  Forgejo   │     │  │
│  │  │ Port: 1025 │  │ Port: 8080 │  │ Port: 3030 │     │  │
│  │  │ Port: 8025 │  │            │  │ Port: 2222 │     │  │
│  │  └────────────┘  └────────────┘  └────────────┘     │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  IP: 192.168.1.100 (example)                                │
└─────────────────────────────────────────────────────────────┘

📦 Services on Proxmox Server

1. PostgreSQL - Database

Port: 5432
Purpose: Main application database
Access: All developers

2. MinIO - S3-compatible Storage

Port: 9000 (API), 9001 (Console)
Purpose: File storage (videos, documents, images)
Access: Backend + Developers

3. Mailhog - Email Testing

Port: 1025 (SMTP), 8025 (Web UI)
Purpose: Catch all emails in development
Access: All developers

4. Adminer - Database Management

Port: 8080
Purpose: Web-based database management
Access: All developers

5. Forgejo - Git Server

Port: 3030 (HTTP), 2222 (SSH)
Purpose: Self-hosted Git repository (like GitHub/GitLab)
Access: All developers

🐳 Docker Compose Configuration

Create this file on your Proxmox server:

`/opt/elearning-dev/docker-compose.yml`

version: "3.8"

services:
  # PostgreSQL Database
  postgres:
    image: postgres:16-alpine
    container_name: elearning-postgres
    restart: unless-stopped
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: elearning_dev
      POSTGRES_USER: elearning
      POSTGRES_PASSWORD: dev_password_change_in_prod
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=en_US.UTF-8"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init-scripts:/docker-entrypoint-initdb.d
    networks:
      - elearning-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U elearning"]
      interval: 10s
      timeout: 5s
      retries: 5

  # MinIO - S3 Compatible Storage
  minio:
    image: minio/minio:latest
    container_name: elearning-minio
    restart: unless-stopped
    ports:
      - "9000:9000" # API
      - "9001:9001" # Console
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin123
      MINIO_BROWSER_REDIRECT_URL: http://192.168.1.100:9001
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"
    networks:
      - elearning-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  # MinIO Client - Create buckets on startup
  minio-init:
    image: minio/mc:latest
    container_name: elearning-minio-init
    depends_on:
      - minio
    entrypoint: >
      /bin/sh -c "
      sleep 5;
      /usr/bin/mc alias set myminio http://minio:9000 minioadmin minioadmin123;
      /usr/bin/mc mb myminio/courses --ignore-existing;
      /usr/bin/mc mb myminio/videos --ignore-existing;
      /usr/bin/mc mb myminio/documents --ignore-existing;
      /usr/bin/mc mb myminio/images --ignore-existing;
      /usr/bin/mc mb myminio/attachments --ignore-existing;
      /usr/bin/mc anonymous set download myminio/images;
      echo 'MinIO buckets created successfully';
      exit 0;
      "
    networks:
      - elearning-network

  # Mailhog - Email Testing
  mailhog:
    image: mailhog/mailhog:latest
    container_name: elearning-mailhog
    restart: unless-stopped
    ports:
      - "1025:1025" # SMTP
      - "8025:8025" # Web UI
    networks:
      - elearning-network

  # Adminer - Database Management UI
  adminer:
    image: adminer:latest
    container_name: elearning-adminer
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      ADMINER_DEFAULT_SERVER: postgres
      ADMINER_DESIGN: dracula
    networks:
      - elearning-network
    depends_on:
      - postgres

  # Forgejo - Self-hosted Git Server
  forgejo:
    image: codeberg.org/forgejo/forgejo:1.21
    container_name: elearning-forgejo
    restart: unless-stopped
    ports:
      - "3030:3000" # HTTP
      - "2222:22" # SSH
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=postgres:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=elearning
      - FORGEJO__database__PASSWD=dev_password_change_in_prod
    volumes:
      - forgejo_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - elearning-network
    depends_on:
      - postgres

volumes:
  postgres_data:
    driver: local
  minio_data:
    driver: local

  forgejo_data:
    driver: local

networks:
  elearning-network:
    driver: bridge

🚀 Setup Instructions

Step 1: Prepare Proxmox Server

# SSH to Proxmox server
ssh root@192.168.1.100

# Create directory
mkdir -p /opt/elearning-dev
cd /opt/elearning-dev

# Create docker-compose.yml (paste content above)
nano docker-compose.yml

# Create init scripts directory
mkdir init-scripts

Step 2: Create Database Init Script (Optional)

Create /opt/elearning-dev/init-scripts/01-create-extensions.sql:

-- Enable required PostgreSQL extensions
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pg_trgm";

-- Create Forgejo database
CREATE DATABASE forgejo;
GRANT ALL PRIVILEGES ON DATABASE forgejo TO elearning;

-- Create additional schemas if needed
-- CREATE SCHEMA IF NOT EXISTS analytics;

Step 3: Start Services

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

# Check specific service
docker-compose logs -f postgres

Step 4: Verify Services

# Test PostgreSQL
docker exec -it elearning-postgres psql -U elearning -d elearning_dev -c "SELECT version();"


# Test MinIO
curl http://192.168.1.100:9000/minio/health/live

💻 Developer Machine Setup

Frontend (Student) - Port 3000

Directory: /path/to/frontend-student

.env.local:

# API Configuration
NUXT_PUBLIC_API_BASE=http://localhost:4000/api
NEXT_PUBLIC_WS_URL=ws://localhost:4000

# MinIO/S3 Configuration
NUXT_PUBLIC_S3_ENDPOINT=http://192.168.1.100:9000
NUXT_PUBLIC_S3_BUCKET=courses


# App Configuration
NUXT_PUBLIC_APP_NAME=E-Learning Platform
NUXT_PUBLIC_APP_URL=http://localhost:3000

Start Command:

npm run dev
# or
yarn dev

Frontend (Admin) - Port 3001

Directory: /path/to/frontend-admin

.env.local:

# API Configuration
NUXT_PUBLIC_API_BASE=http://localhost:4000/api
NEXT_PUBLIC_WS_URL=ws://localhost:4000

# MinIO/S3 Configuration
NUXT_PUBLIC_S3_ENDPOINT=http://192.168.1.100:9000
NUXT_PUBLIC_S3_BUCKET=courses


# App Configuration
NUXT_PUBLIC_APP_NAME=E-Learning Admin
NUXT_PUBLIC_APP_URL=http://localhost:3001

package.json (modify dev script):

{
  "scripts": {
    "dev": "next dev -p 3001"
  }
}

Start Command:

npm run dev
# or
yarn dev

Backend (API) - Port 4000

Directory: /path/to/backend

.env:

# Application
NODE_ENV=development
PORT=4000
APP_URL=http://localhost:4000

# Database
DATABASE_URL=postgresql://elearning:dev_password_change_in_prod@192.168.1.100:5432/elearning_dev
DB_HOST=192.168.1.100
DB_PORT=5432
DB_NAME=elearning_dev
DB_USER=elearning
DB_PASSWORD=dev_password_change_in_prod


# MinIO/S3
S3_ENDPOINT=http://192.168.1.100:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin123
S3_BUCKET_COURSES=courses
S3_BUCKET_VIDEOS=videos
S3_BUCKET_DOCUMENTS=documents
S3_BUCKET_IMAGES=images
S3_BUCKET_ATTACHMENTS=attachments
S3_REGION=us-east-1
S3_USE_SSL=false

# Email (Mailhog)
SMTP_HOST=192.168.1.100
SMTP_PORT=1025
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM=noreply@elearning.local
SMTP_FROM_NAME=E-Learning Platform

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=7d

# CORS
CORS_ORIGIN=http://localhost:3000,http://localhost:3001

# File Upload
MAX_FILE_SIZE=104857600  # 100MB
ALLOWED_VIDEO_TYPES=video/mp4,video/webm
ALLOWED_DOCUMENT_TYPES=application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document
ALLOWED_IMAGE_TYPES=image/jpeg,image/png,image/gif

Start Command:

npm run dev
# or
yarn dev

🔧 Useful Commands

Docker Management

# Stop all services
docker-compose down

# Stop and remove volumes (⚠️ deletes data)
docker-compose down -v

# Restart specific service
docker-compose restart postgres

# View logs
docker-compose logs -f postgres

# Execute command in container
docker exec -it elearning-postgres psql -U elearning -d elearning_dev

Database Management

# Backup database
docker exec elearning-postgres pg_dump -U elearning elearning_dev > backup.sql

# Restore database
cat backup.sql | docker exec -i elearning-postgres psql -U elearning -d elearning_dev

# Access database shell
docker exec -it elearning-postgres psql -U elearning -d elearning_dev

MinIO Management

# Access MinIO Console
# Open browser: http://192.168.1.100:9001
# Username: minioadmin
# Password: minioadmin123

# Using MinIO Client (mc)
docker exec -it elearning-minio mc alias set local http://localhost:9000 minioadmin minioadmin123
docker exec -it elearning-minio mc ls local/

🌐 Access URLs

Service	URL	Credentials
Frontend (Student)	http://localhost:3000	-
Frontend (Admin)	http://localhost:3001	-
Backend API	http://localhost:4000	-
PostgreSQL	192.168.1.100:5432	elearning / dev_password_change_in_prod
MinIO Console	http://192.168.1.100:9001	minioadmin / minioadmin123
MinIO API	http://192.168.1.100:9000	-

📊 Resource Requirements

Proxmox Server (Recommended)

CPU: 4 cores
RAM: 8 GB
Storage: 50 GB (SSD recommended)
Network: 1 Gbps

Developer Machines

CPU: 2+ cores
RAM: 8 GB
Storage: 20 GB free space

🔒 Security Notes

Warning

Development Environment Only!

These credentials are for development only

Change all passwords in production

Never commit .env files to git

Use .env.example for templates

🐛 Troubleshooting

Cannot connect to PostgreSQL

# Check if container is running
docker ps | grep postgres

# Check logs
docker logs elearning-postgres

# Test connection
docker exec -it elearning-postgres pg_isready -U elearning

Cannot connect to MinIO

# Check if container is running
docker ps | grep minio

# Check logs
docker logs elearning-minio

# Test health
curl http://192.168.1.100:9000/minio/health/live

Port already in use

# Find process using port
lsof -i :5432
# or
netstat -tulpn | grep 5432

# Kill process
kill -9 <PID>

Docker network issues

# Recreate network
docker-compose down
docker network prune
docker-compose up -d

📝 Development Workflow

Daily Workflow

Start Proxmox Services (if not running)

ssh root@192.168.1.100
cd /opt/elearning-dev
docker-compose up -d

Start Backend
```
cd /path/to/backend
npm run dev
```

Start Frontend (Student)

cd /path/to/frontend-student
npm run dev

Start Frontend (Admin)
```
cd /path/to/frontend-admin
npm run dev
```
Develop & Test
- Student app: http://localhost:3000
- Admin app: http://localhost:3001
- API: http://localhost:4000
- Check emails: http://192.168.1.100:8025

End of Day

# Optional: Stop services to save resources
ssh root@192.168.1.100
cd /opt/elearning-dev
docker-compose stop

🎯 Next Steps

✅ Setup Proxmox server with Docker Compose
✅ Configure developer machines with .env files
✅ Test connectivity to all services
✅ Run database migrations
✅ Seed initial data
✅ Start development!

16 KiB Raw Blame History

Development Environment Setup Guide

🏗️ Architecture Overview

📦 Services on Proxmox Server

1. PostgreSQL - Database

2. MinIO - S3-compatible Storage

3. Mailhog - Email Testing

4. Adminer - Database Management

5. Forgejo - Git Server

🐳 Docker Compose Configuration

/opt/elearning-dev/docker-compose.yml

🚀 Setup Instructions

Step 1: Prepare Proxmox Server

Step 2: Create Database Init Script (Optional)

Step 3: Start Services

Step 4: Verify Services

💻 Developer Machine Setup

Frontend (Student) - Port 3000

Frontend (Admin) - Port 3001

Backend (API) - Port 4000

🔧 Useful Commands

Docker Management

Database Management

MinIO Management

🌐 Access URLs

📊 Resource Requirements

Proxmox Server (Recommended)

Developer Machines

🔒 Security Notes

🐛 Troubleshooting

Cannot connect to PostgreSQL

Cannot connect to MinIO

Port already in use

Docker network issues

📝 Development Workflow

Daily Workflow

End of Day

🎯 Next Steps

📚 Additional Resources

16 KiB

Raw Blame History

`/opt/elearning-dev/docker-compose.yml`