pos-system/SETUP_GUIDE.md

Environment Setup Guide - Hướng Dẫn Thiết Lập Môi Trường

🎯 Tổng Quan

Dự án sử dụng Hybrid Environment Configuration với 2 levels:

1. Shared Environment (deployments/local/.env.local) - Configs dùng chung
2. Service-Specific Environment (services/<service>/.env.local) - Configs riêng

Lợi Ích

• ✅ JWT secrets giống nhau → Services có thể verify tokens của nhau
• ✅ Mỗi service có database riêng → Đúng microservices pattern
• ✅ Override configs dễ dàng → REDIS_HOST khác nhau cho Docker/Native
• ✅ Không duplicate → Maintain dễ hơn

🚀 Quick Start

Option 1: Sử Dụng Script (Khuyến nghị)

# Tự động tạo tất cả env files
./scripts/dev/setup-env.sh

Option 2: Setup Thủ Công

Step 1: Shared Environment

cp deployments/local/env.local.example deployments/local/.env.local

Step 2: Service Environment

cp services/auth-service/env.local.example services/auth-service/.env.local

📝 Cấu Hình Chi Tiết

1. Shared Environment (deployments/local/.env.local)

Chứa configs dùng chung cho TẤT CẢ services:

# JWT Secrets - PHẢI GIỐNG NHAU cho tất cả services
JWT_SECRET=dev-jwt-secret-change-in-production-min-32-chars
JWT_REFRESH_SECRET=dev-refresh-secret-change-in-production-min-32-chars

# Redis (Docker hostname)
REDIS_HOST=redis
REDIS_PORT=6379

# Common
NODE_ENV=development
LOG_LEVEL=debug
CORS_ORIGIN=http://localhost:3000,http://localhost:3001

2. Service Environment (services/auth-service/.env.local)

Chứa configs RIÊNG cho từng service:

# Database riêng cho service này
DATABASE_URL=postgresql://user:pass@ep-xxx.neon.tech/goodgo_auth_dev?sslmode=require&pgbouncer=true

# Service configs
PORT=5001
SERVICE_NAME=auth-service

# Override cho native dev (Redis trong Docker)
REDIS_HOST=localhost

🗄️ Database Setup

Tạo Databases Trong Neon

Mỗi service cần database riêng:

1. Truy cập: https://console.neon.tech

2. Tạo databases:

   • goodgo_auth_dev → auth-service
   • goodgo_user_dev → user-service
   • goodgo_product_dev → product-service
   • etc.

3. Copy connection string vào services/<service>/.env.local:

DATABASE_URL=postgresql://user:pass@ep-xxx.neon.tech/goodgo_auth_dev?sslmode=require&pgbouncer=true

Run Migrations

# Auth service
./scripts/db/migrate.sh auth-service dev

# Seed data (optional)
./scripts/db/seed.sh auth-service

🔧 Cách Hoạt Động

Loading Order

Services load environment theo thứ tự:

1. Shared env (deployments/local/.env.local)

   • JWT_SECRET, JWT_REFRESH_SECRET
   • REDIS_HOST=redis, REDIS_PORT
   • NODE_ENV, LOG_LEVEL, CORS_ORIGIN

2. Service env (.env.local)

   • DATABASE_URL (riêng cho service)
   • PORT (riêng cho service)
   • REDIS_HOST=localhost (override cho native dev)

Package.json Configuration

{
  "scripts": {
    "dev": "dotenv -e ../../deployments/local/.env.local -e .env.local -- tsx watch src/main.ts"
  }
}

Sử dụng dotenv-cli để load multiple env files.

📂 File Structure

Base/
├── deployments/local/
│   ├── env.local.example          # Template cho shared env
│   └── .env.local                 # Shared env (gitignored)
│
├── services/
│   ├── auth-service/
│   │   ├── env.example            # Old template (deprecated)
│   │   ├── env.local.example      # New template cho service env
│   │   └── .env.local             # Service env (gitignored)
│   │
│   └── user-service/
│       ├── env.local.example
│       └── .env.local
│
└── scripts/dev/
    └── setup-env.sh               # Auto setup script

⚠️ Important Notes

1. JWT Secrets

MUST BE IDENTICAL across all services:

• Services cần verify JWT tokens của nhau
• Nếu khác nhau → authentication sẽ fail

2. Database URLs

MUST BE DIFFERENT for each service:

• Mỗi service có database riêng (microservices pattern)
• Ví dụ:
  • auth-service → goodgo_auth_dev
  • user-service → goodgo_user_dev

3. Redis Host

Khác nhau tùy môi trường:

• Shared env: REDIS_HOST=redis (Docker hostname)
• Service env: REDIS_HOST=localhost (override cho native dev)

Khi chạy native, Redis trong Docker → dùng localhost

4. Git Ignore

Tất cả .env.local files đã được gitignored:

• deployments/local/.env.local
• services/*/.env.local

NEVER commit actual env files!

🎓 Examples

Example 1: Auth Service Native Dev

# 1. Setup env
cp services/auth-service/env.local.example services/auth-service/.env.local

# 2. Edit .env.local
DATABASE_URL=postgresql://user:pass@ep-xxx.neon.tech/goodgo_auth_dev?sslmode=require
PORT=5001
REDIS_HOST=localhost  # Override cho native dev

# 3. Start Redis in Docker
cd deployments/local && docker-compose up -d redis

# 4. Run service
pnpm --filter @goodgo/auth-service dev

Example 2: Multiple Services

# 1. Setup all envs
./scripts/dev/setup-env.sh

# 2. Edit each service's .env.local with different DATABASE_URL

# 3. Start infrastructure
cd deployments/local && docker-compose up -d redis traefik

# 4. Run all services
pnpm dev

🔍 Troubleshooting

Database Connection Failed

# Check if .env.local exists
ls -la services/auth-service/.env.local

# Check DATABASE_URL
cat services/auth-service/.env.local | grep DATABASE_URL

# Test connection
cd services/auth-service && pnpm prisma db pull

JWT Secret Warning

Nếu thấy warning "Using default JWT_SECRET":

• Check deployments/local/.env.local có JWT_SECRET chưa
• Check service có load đúng env files chưa

Redis Connection Failed

Khi chạy native:

• Check Redis container đang chạy: docker ps | grep redis
• Check REDIS_HOST=localhost trong service .env.local

📚 Tài Liệu Thêm

• Local Development Guide
• Neon Database Guide
• Service README

🎉 Ready to Go!

Sau khi setup xong:

# Start everything
./scripts/dev/start-all.sh

# Or selective
pnpm --filter @goodgo/auth-service dev

Happy coding! 🚀