pos-system/docs/vi/guides/local-deployment.md

Hướng dẫn Local Deployment

Thư mục này chứa cấu hình Docker Compose để chạy toàn bộ nền tảng GoodGo ở local.

Bắt Đầu Nhanh

# 1. Thiết lập biến môi trường
cp env.local.example .env.local
# Chỉnh sửa .env.local với các giá trị của bạn (JWT_SECRET, DATABASE_URL, etc.)

# 2. Khởi động tất cả services
docker-compose up -d

# 3. Kiểm tra trạng thái service
docker-compose ps

# 4. Xem logs
docker-compose logs -f

Điểm Truy Cập

Service	URL	Mô Tả
Traefik Dashboard	http://localhost:8080	Dashboard API Gateway
Auth Service	http://localhost/api/v1/auth	API xác thực
Web Admin	http://admin.localhost	Dashboard quản trị
Web Client	http://localhost	Ứng dụng client
Redis	localhost:6379	Cache (truy cập trực tiếp)

Services

Hạ Tầng

• Traefik (Port 80, 8080): API Gateway với automatic service discovery
• Redis (Port 6379): Cache và session store chung

Backend Services

• iam-service (Port 5001): Xác thực và quản lý người dùng
  • Routes: /api/v1/auth, /api/v1/users
  • Health: http://localhost/api/v1/auth/health

Frontend Applications

• web-admin (Port 3000): Dashboard quản trị (Next.js)
• web-client (Port 3001): Ứng dụng client (Next.js)

Cấu Hình Môi Trường

Biến môi trường được quản lý trong .env.local:

Biến Bắt Buộc

# Xác thực (PHẢI giống nhau cho tất cả services)
JWT_SECRET=your-super-secret-jwt-key-min-32-characters
JWT_REFRESH_SECRET=your-super-secret-refresh-key-min-32-characters

# Database (Neon PostgreSQL)
DATABASE_URL=postgresql://user:pass@host.neon.tech/db?sslmode=require

Biến Tùy Chọn

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# Observability
TRACING_ENABLED=false
JAEGER_ENDPOINT=http://jaeger:14268/api/traces

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

Các Lệnh Thường Dùng

# Khởi động tất cả services
docker-compose up -d

# Khởi động service cụ thể
docker-compose up -d iam-service

# Dừng tất cả services
docker-compose down

# Dừng và xóa volumes
docker-compose down -v

# Xem logs (tất cả services)
docker-compose logs -f

# Xem logs (service cụ thể)
docker-compose logs -f iam-service

# Restart service
docker-compose restart iam-service

# Rebuild service
docker-compose up -d --build iam-service

# Kiểm tra trạng thái service
docker-compose ps

# Thực thi lệnh trong container
docker-compose exec iam-service sh

Thêm Service Mới

1. Thêm service vào docker-compose.yml:

services:
  my-new-service:
    build:
      context: ../..
      dockerfile: services/my-new-service/Dockerfile
    container_name: my-new-service-local
    env_file:
      - .env.local
    environment:
      - PORT=5002
      - SERVICE_NAME=my-new-service
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_HOST=${REDIS_HOST}
      - JWT_SECRET=${JWT_SECRET}
    ports:
      - "5002:5002"
    depends_on:
      redis:
        condition: service_healthy
      traefik:
        condition: service_started
    networks:
      - microservices-network
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-new-service.rule=PathPrefix(`/api/v1/my-new-service`)"
      - "traefik.http.services.my-new-service.loadbalancer.server.port=5002"

2. Khởi động service:

docker-compose up -d my-new-service

3. Truy cập service:
   • Qua Traefik: http://localhost/api/v1/my-new-service
   • Trực tiếp: http://localhost:5002

Cấu Hình Traefik

Traefik được cấu hình qua:

• Static config: infra/traefik/traefik.yml
• Dynamic config: infra/traefik/dynamic/
• Service discovery: Docker labels trong file này

Services tự động được discover bởi Traefik sử dụng Docker labels. Không cần cấu hình route thủ công.

Khắc Phục Sự Cố

Port Đã Được Sử Dụng

# Tìm process đang dùng port
lsof -i :80
lsof -i :5001

# Kill process
kill -9 <PID>

Service Không Khởi Động

# Kiểm tra logs
docker-compose logs service-name

# Rebuild không dùng cache
docker-compose build --no-cache service-name
docker-compose up -d service-name

Vấn Đề Kết Nối Database

# Xác minh DATABASE_URL trong .env.local
cat .env.local | grep DATABASE_URL

# Test connection từ service
docker-compose exec iam-service sh

Vấn Đề Kết Nối Redis

# Kiểm tra Redis đang chạy
docker-compose ps redis

# Test Redis connection
docker-compose exec redis redis-cli ping
# Nên trả về: PONG

Traefik Không Định Tuyến

# Kiểm tra Traefik dashboard
open http://localhost:8080

# Xác minh service có labels đúng
docker-compose config | grep -A 5 "labels:"

# Kiểm tra Traefik logs
docker-compose logs traefik

Kiến Trúc Network

graph TB
    Client[👤 Client<br/>Browser] --> Traefik
    
    Traefik[🌐 Traefik<br/>API Gateway<br/>:80, :8080]
    
    Traefik --> IAM[🔐 IAM Service<br/>Authentication<br/>:5001]
    Traefik --> Admin[⚙️ Web Admin<br/>Dashboard<br/>:3000]
    Traefik --> WebClient[🌍 Web Client<br/>Application<br/>:3001]
    
    IAM --> Redis[(💾 Redis<br/>Cache<br/>:6379)]
    IAM --> DB[(🗄️ PostgreSQL<br/>Neon Database)]
    
    classDef client fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#eee
    classDef gateway fill:#0f3460,stroke:#16213e,stroke-width:3px,color:#eee
    classDef service fill:#16213e,stroke:#533483,stroke-width:2px,color:#eee
    classDef frontend fill:#1a1a40,stroke:#6c5ce7,stroke-width:2px,color:#eee
    classDef data fill:#2d132c,stroke:#801336,stroke-width:2px,color:#eee
    
    class Client client
    class Traefik gateway
    class IAM service
    class Admin,WebClient frontend
    class Redis,DB data

Chú Giải:

• 👤 Client: Người dùng truy cập qua trình duyệt
• 🌐 Gateway: Traefik API Gateway (định tuyến tự động)
• 🔐 Backend: IAM Service (xác thực)
• ⚙️ Frontend: Ứng dụng Web Admin & Client
• 💾 Storage: Redis cache & PostgreSQL database

Quick Tips

🚨 Các Vấn Đề Thường Gặp

Vấn Đề	Giải Pháp
Xung đột port	Kiểm tra port 80/5001/6379 đã được sử dụng: lsof -i :<port>
Service không khởi động	Kiểm tra logs: docker-compose logs <service-name>
Kết nối database	Xác minh DATABASE_URL trong .env.local chính xác
Kết nối Redis	Đảm bảo Redis healthy: docker-compose exec redis redis-cli ping
Traefik routing	Kiểm tra dashboard tại http://localhost:8080 để xem trạng thái routes

🎯 Development Workflow

# Restart nhanh (thay đổi code)
docker-compose restart iam-service

# Rebuild đầy đủ (thay đổi dependencies)
docker-compose up -d --build iam-service

# Clean restart (vấn đề database)
docker-compose down -v && docker-compose up -d

🔐 Security Checklist

• ✅ Thay đổi JWT_SECRET mặc định (tối thiểu 32 ký tự)
• ✅ Sử dụng .env.local riêng cho từng môi trường (không commit)
• ✅ Xác minh CORS origins khớp với frontend URLs
• ✅ Bật HTTPS trong production (không cần cho local)

📊 Monitoring

• Traefik Dashboard: http://localhost:8080 - Xem tất cả routes và services
• Service Health: http://localhost/api/v1/auth/health - Kiểm tra trạng thái service
• Redis CLI: docker-compose exec redis redis-cli - Query cache trực tiếp

Tài Liệu Tham Khảo

• Cấu Hình Traefik
• Service Template
• Hướng Dẫn Phát Triển
• Hướng Dẫn Neon Database