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

Triển Khai Phát Triển Cục Bộ

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

┌─────────────────────────────────────────────────────────────┐
│                         Client                               │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │    Traefik    │ :80, :8080
                    │  API Gateway  │
                    └───────┬───────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ iam-service │    │  web-admin   │    │  web-client  │
│    :5001     │    │    :3000     │    │    :3001     │
└──────┬───────┘    └──────────────┘    └──────────────┘
       │
       ├─────────────┐
       │             │
       ▼             ▼
┌──────────┐  ┌─────────────┐
│  Redis   │  │ PostgreSQL  │
│  :6379   │  │   (Neon)    │
└──────────┘  └─────────────┘

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