# Local Development Guide

> **EN**: Local Development Guide
>
> **VI**: Hướng dẫn phát triển cục bộ

**Last Updated**: 2026-01-05
**Difficulty**: Intermediate
**Setup Time**: 15-30 minutes

## Workflow

```mermaid
graph TD
    Start([Start]) --> Prerequisites[1. System Prerequisites]
    Prerequisites --> Clone[2. Clone & Install]
    Clone --> Env[3. Configure Environment<br/>(Shared & Service-Specific)]
    Env --> DB[4. Setup Database<br/>(Migrate & Seed)]
    DB --> Run[5. Run Project<br/>(Native/Docker/Hybrid)]
    Run --> Dev[6. Development Loop<br/>(Watch Mode)]
    Dev --> Test[7. Testing & Verify]
    Test --> End([Complete])

    subgraph "Run Modes"
        Run --> Mode1[Mode 1: Native (Fastest)]
        Run --> Mode2[Mode 2: Hybrid (Flexible)]
        Run --> Mode3[Mode 3: Full Docker (Production-like)]
    end

    style Start fill:#d4edda,stroke:#28a745,stroke-width:2px
    style End fill:#d4edda,stroke:#28a745,stroke-width:2px
    style Env fill:#fff3cd,stroke:#ffc107
    style DB fill:#fff3cd,stroke:#ffc107
    style Run fill:#cce5ff,stroke:#007bff
```

## Overview

This guide provides a detailed process for setting up a development environment for the GoodGo Microservices ecosystem. You will learn how to run services, set up databases, and establish an efficient workflow with hot-reload.

## 1. Prerequisites

Before starting, ensure your machine has the following tools installed:

- **Node.js**: Latest LTS version (v20+).
- **PNPM**: Main project package manager (`npm install -g pnpm`).
- **Docker Desktop**: Required for running infrastructure services (Redis, Local Database).
- **Git**: For source code management.
- **Neon Account** (Optional): If using Neon Database on cloud (recommended for dev).

## 2. Initial Setup

### 2.1 Clone and Install Dependencies

```bash
# EN: Clone the repository
# VI: Clone repository về máy
git clone <repository-url>
cd Base

# EN: Install dependencies using pnpm
# VI: Cài đặt các thư viện phụ thuộc bằng pnpm
pnpm install
```

### 2.2 Quick Init Script (Recommended)

The project includes an automation script for basic initialization:

```bash
# EN: Run initialization script
# VI: Chạy script khởi tạo
./scripts/setup/init-project.sh
```

> This script will:
> - Install dependencies.
> - Copy example environment files (`.env.example` -> `.env`).
> - Generate Prisma client.

## 3. Environment Configuration

The project uses a **Hybrid Environment** strategy to optimize configuration management:

### 3.1 Shared Configuration

File: `deployments/local/.env.local`
Contains variables shared across the entire system (JWT, Redis, Logging).

```bash
# EN: Create shared env file from example
# VI: Tạo file môi trường chung từ file mẫu
cp deployments/local/env.local.example deployments/local/.env.local
```

### 3.2 Service-Specific Configuration

Each service (e.g., `iam-service`) needs its own `.env.local` file containing specific details like Database URL and Port.

```bash
# EN: Create service-specific env file
# VI: Tạo file môi trường riêng cho service
cp services/iam-service/env.local.example services/iam-service/.env.local
```

**Key contents to check in `services/iam-service/.env.local`**:

```properties
# Database URL (Use Neon Tech or Local Postgres)
DATABASE_URL=postgresql://user:password@host:5432/db_name?sslmode=require

# Service Port (Must be unique per service)
PORT=5001

# Service Name
SERVICE_NAME=iam-service

# Redis Host (localhost for Native Dev, redis for Docker Dev)
REDIS_HOST=localhost
```

## 4. Setup Database

After configuring `DATABASE_URL`, you need to sync the schema and seed initial data.

```bash
# EN: Run migrations for iam-service
# VI: Chạy migration cho iam-service
./scripts/db/migrate.sh iam-service dev

# EN: Seed initial data (optional)
# VI: Tạo dữ liệu mẫu (tùy chọn)
./scripts/db/seed.sh iam-service
```

## 5. Run Modes

You can run the project in 3 ways depending on your needs:

### Mode 1: Native Development (Recommended for Backend Dev)

Run directly on the host machine. Fastest speed, fastest hot-reload.

1.  **Start Infrastructure**:
    ```bash
    # EN: Start Redis and Traefik in Docker background
    # VI: Khởi động Redis và Traefik chạy ngầm bằng Docker
    cd deployments/local
    docker-compose up -d redis traefik
    cd ../..
    ```

2.  **Run Service**:
    ```bash
    # EN: Start iam-service in watch mode
    # VI: Chạy iam-service ở chế độ watch
    pnpm --filter @goodgo/iam-service dev
    ```

### Mode 2: Hybrid Development (Flexible)

Use when you need to run multiple auxiliary services in Docker but want to dev the main service directly.

```bash
# EN: Start dependent services in Docker
# VI: Chạy các service phụ thuộc trong Docker
docker-compose -f deployments/local/docker-compose.yml up -d user-service payment-service

# EN: Run the service you are working on natively
# VI: Chạy service bạn đang làm việc trực tiếp trên máy
pnpm --filter @goodgo/iam-service dev
```

### Mode 3: Full Docker (Production Simulation)

Run the entire system in Docker. Good for Integration Testing but no hot-reload.

```bash
# EN: Start everything with Docker Compose
# VI: Chạy tất cả bằng Docker Compose
cd deployments/local
docker-compose up -d
```

## 6. Access & Verification

After startup, you can access the following endpoints:

| Service | URL | Description |
|---------|-----|-------------|
| **API Gateway** | `http://localhost/api/v1` | Main entry point via Traefik |
| **IAM Service** | `http://localhost:5001` | Direct service access |
| **Health Check** | `http://localhost:5001/health` | Service status check |
| **Metrics** | `http://localhost:5001/metrics` | Prometheus metrics |
| **API Docs** | `http://localhost:5001/api-docs` | Swagger UI |

### Health Check Validation

```bash
# EN: Check liveness
# VI: Kiểm tra liveness
curl http://localhost:5001/health/live

# EN: Check readiness
# VI: Kiểm tra readiness
curl http://localhost:5001/health/ready
```

## 7. Troubleshooting

### Port Already In Use

**Error**: `Error: listen EADDRINUSE: address already in use :::5001`

**Solution**:
```bash
# EN: Find process using port 5001
# VI: Tìm process đang chiếm port 5001
lsof -i :5001

# EN: Kill the process
# VI: Tắt process đó
kill -9 <PID>
```

### Database Connection Error

**Error**: `P1001: Can't reach database server`

**Solution**:
- Re-check `DATABASE_URL` variable.
- If using local Postgres Docker, ensure container is running (`docker ps`).
- If using Neon, check internet connection.

### Module Not Found

**Error**: Cannot find internal packages (e.g., `@goodgo/logger`).

**Solution**:
```bash
# EN: Re-install dependencies and build packages
# VI: Cài lại dependencies và build lại packages
pnpm install
pnpm build
```

## References

- [Kubernetes Guide](kubernetes-local.md) - Deploy to Local K8s.
- [Project Architecture](../../docs/en/ARCHITECTURE.en.md) - System architecture overview.