elearning/docs/development_setup.md

# 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`

```yaml
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

```bash
# 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`:

```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

```bash
# 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

```bash
# 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`**:

```env
# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:4000/api
NEXT_PUBLIC_WS_URL=ws://localhost:4000

# MinIO/S3 Configuration
NEXT_PUBLIC_S3_ENDPOINT=http://192.168.1.100:9000
NEXT_PUBLIC_S3_BUCKET=courses

# App Configuration
NEXT_PUBLIC_APP_NAME=E-Learning Platform
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

**Start Command**:

```bash
npm run dev
# or
yarn dev
```

---

### Frontend (Admin) - Port 3001

**Directory**: `/path/to/frontend-admin`

**`.env.local`**:

```env
# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:4000/api
NEXT_PUBLIC_WS_URL=ws://localhost:4000

# MinIO/S3 Configuration
NEXT_PUBLIC_S3_ENDPOINT=http://192.168.1.100:9000
NEXT_PUBLIC_S3_BUCKET=courses

# App Configuration
NEXT_PUBLIC_APP_NAME=E-Learning Admin
NEXT_PUBLIC_APP_URL=http://localhost:3001
```

**package.json** (modify dev script):

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

**Start Command**:

```bash
npm run dev
# or
yarn dev
```

---

### Backend (API) - Port 4000

**Directory**: `/path/to/backend`

**`.env`**:

```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**:

```bash
npm run dev
# or
yarn dev
```

---

## 🔧 Useful Commands

### Docker Management

```bash
# 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

```bash
# 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

```bash
# 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 | -                                       |

| **Mailhog UI** | http://192.168.1.100:8025 | - |
| **Adminer** | http://192.168.1.100:8080 | - |
| **Forgejo** | http://192.168.1.100:3030 | Setup on first visit |
| **Forgejo SSH** | ssh://git@192.168.1.100:2222 | SSH key required |

---

## 📊 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

```bash
# 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

```bash
# 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

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

# Kill process
kill -9 <PID>
```

### Docker network issues

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

---

## 📝 Development Workflow

### Daily Workflow

1. **Start Proxmox Services** (if not running)

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

2. **Start Backend**

   ```bash
   cd /path/to/backend
   npm run dev
   ```

3. **Start Frontend (Student)**

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

4. **Start Frontend (Admin)**

   ```bash
   cd /path/to/frontend-admin
   npm run dev
   ```

5. **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

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

---

## 🎯 Next Steps

1. ✅ Setup Proxmox server with Docker Compose
2. ✅ Configure developer machines with `.env` files
3. ✅ Test connectivity to all services
4. ✅ Run database migrations
5. ✅ Seed initial data
6. ✅ Start development!

---

## 📚 Additional Resources

- [Docker Compose Documentation](https://docs.docker.com/compose/)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [MinIO Documentation](https://min.io/docs/)