9ba4a478ee
- Updated Mermaid diagrams in the deployment and development guides for better visual representation and consistency. - Improved formatting and clarity in the Kubernetes local deployment and IAM migration guides, including detailed workflows and troubleshooting sections. - Enhanced the Vietnamese documentation to align with the English version, ensuring consistency across guides. - Added quick tips and common issues sections to facilitate user navigation and understanding.
258 lines
7.0 KiB
Markdown
258 lines
7.0 KiB
Markdown
# 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 and Install"]
|
|
Clone --> Env["3. Configure Environment - Shared and Service-Specific"]
|
|
Env --> DB["4. Setup Database - Migrate and Seed"]
|
|
DB --> Run["5. Run Project - Native/Docker/Hybrid"]
|
|
Run --> Dev["6. Development Loop - Watch Mode"]
|
|
Dev --> Test["7. Testing and 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:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
|
|
style End fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
|
|
style Prerequisites fill:#7F8C8D,color:#fff
|
|
style Clone fill:#7F8C8D,color:#fff
|
|
style Env fill:#E67E22,color:#fff
|
|
style DB fill:#E67E22,color:#fff
|
|
style Run fill:#2980B9,color:#fff
|
|
style Dev fill:#2980B9,color:#fff
|
|
style Test fill:#3498DB,color:#fff
|
|
style Mode1 fill:#8E44AD,color:#fff
|
|
style Mode2 fill:#8E44AD,color:#fff
|
|
style Mode3 fill:#8E44AD,color:#fff
|
|
```
|
|
|
|
## 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.
|