chamomind/elearning
7
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages 3 Wiki Activity Actions

docs: Add Forgejo and development setup guides, and refactor API documentation structure.

Browse source
This commit is contained in:
JakkrapartXD 2025-12-23 16:02:17 +07:00
parent 7b1ed6f6cc
commit a6427b2083
9 changed files with 2446 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

650
docs/development_setup.md Normal file
View file

@ -0,0 +1,650 @@
# 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 │ │ Redis │ │ │
│ │ │ Port: 5432 │ │ Port: 9000 │ │ Port: 6379 │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
│ │ │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ 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. Redis - Cache & Session
- **Port**: 6379
- **Purpose**: Caching, session storage, queue
- **Access**: Backend only
### 4. Mailhog - Email Testing
- **Port**: 1025 (SMTP), 8025 (Web UI)
- **Purpose**: Catch all emails in development
- **Access**: All developers
### 5. Adminer - Database Management
- **Port**: 8080
- **Purpose**: Web-based database management
- **Access**: All developers
### 6. 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
# Redis - Cache & Session Store
redis:
image: redis:7-alpine
container_name: elearning-redis
restart: unless-stopped
ports:
- "6379:6379"
command: redis-server --appendonly yes --requirepass dev_redis_password
volumes:
- redis_data:/data
networks:
- elearning-network
healthcheck:
test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
interval: 10s
timeout: 3s
retries: 5
# 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
redis_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 Redis
docker exec -it elearning-redis redis-cli -a dev_redis_password ping
# 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
# Redis
REDIS_URL=redis://:dev_redis_password@192.168.1.100:6379
REDIS_HOST=192.168.1.100
REDIS_PORT=6379
REDIS_PASSWORD=dev_redis_password
# 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 | - |
| **Redis** | 192.168.1.100:6379 | Password: dev_redis_password |
| **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/)
- [Redis Documentation](https://redis.io/documentation)