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ị)

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

### Option 2: Setup Thủ Công

**Step 1: Shared Environment**
```bash
cp deployments/local/env.local.example deployments/local/.env.local
```

**Step 2: Service Environment**
```bash
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:

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

```bash
# 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`:
```bash
DATABASE_URL=postgresql://user:pass@ep-xxx.neon.tech/goodgo_auth_dev?sslmode=require&pgbouncer=true
```

### Run Migrations

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

```json
{
  "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

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

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

```bash
# 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](docs/vi/guides/local-development.md)
- [Neon Database Guide](docs/vi/guides/neon-database.md)
- [Service README](services/auth-service/README.md)

## 🎉 Ready to Go!

Sau khi setup xong:

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

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

Happy coding! 🚀