pos-system/microservices/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
cp env.local.example .env.local
# Chỉnh sửa cả 2 file với các giá trị của bạn (JWT_SECRET, DB URL từng service, Redis, v.v.)

# 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 và .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
JWT_ID_SECRET=your-super-secret-id-key-min-32-characters

# IAM + database từng service (Neon PostgreSQL)
IAM_DATABASE_URL=Host=...;Port=5432;Database=iam_service;Username=...;Password=...;SSL Mode=Require
STORAGE_DATABASE_URL=Host=...;Port=5432;Database=storage_service;Username=...;Password=...;SSL Mode=Require
ORDER_DATABASE_URL=Host=...;Port=5432;Database=order_service;Username=...;Password=...;SSL Mode=Require

Biến Tùy Chọn

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=replace-with-redis-password

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

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

# Object storage và messaging
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=...
MINIO_SECRET_KEY=...
RABBITMQ_PASSWORD=...

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 IAM_DATABASE_URL trong .env/.env.local
cat .env | grep IAM_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 / .env.local theo từng môi trường, không commit secret thật
• 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