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

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

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

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

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

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

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

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

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

### Service Không Khởi Động

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

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

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

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

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

```bash
# 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](../../infra/traefik/)
- [Service Template](../../services/_template/)
- [Hướng Dẫn Phát Triển](development.md)
- [Hướng Dẫn Neon Database](neon-database.md)