pos-system/docs/en/guides/local-development.md

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

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

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

# 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).

# 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.

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

# 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.

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

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

   # 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.

# 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.

# 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

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

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

# 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 - Deploy to Local K8s.
• Project Architecture - System architecture overview.