Update project configuration and enhance service template with new features
- Updated `.gitignore` to clarify environment variable handling. - Enhanced `pnpm-lock.yaml` with new dependencies for Jest and Supertest, including type definitions. - Improved bilingual documentation in `SKILL.md` files for better clarity on comment patterns and project rules. - Refined `docker-compose.yml` for local development, adding detailed instructions and access points. - Updated environment variable example in `env.local.example` for better guidance on configuration. - Removed outdated architecture documentation from the service template. - Enhanced Dockerfile for improved security and performance during builds. - Added Swagger documentation setup in the service template for better API documentation. - Improved error handling and logging middleware for enhanced debugging capabilities.
This commit is contained in:
Ho Ngoc Hai
263
docs/en/guides/local-deployment.md
Normal file
263
docs/en/guides/local-deployment.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# Local Development Deployment
|
||||
|
||||
This directory contains Docker Compose configuration for running the entire GoodGo platform locally.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Setup environment variables
|
||||
cp env.local.example .env.local
|
||||
# Edit .env.local with your values (JWT_SECRET, DATABASE_URL, etc.)
|
||||
|
||||
# 2. Start all services
|
||||
docker-compose up -d
|
||||
|
||||
# 3. Check service status
|
||||
docker-compose ps
|
||||
|
||||
# 4. View logs
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
## Access Points
|
||||
|
||||
| Service | URL | Description |
|
||||
|---------|-----|-------------|
|
||||
| **Traefik Dashboard** | http://localhost:8080 | API Gateway dashboard |
|
||||
| **Auth Service** | http://localhost/api/v1/auth | Authentication API |
|
||||
| **Web Admin** | http://admin.localhost | Admin dashboard |
|
||||
| **Web Client** | http://localhost | Client application |
|
||||
| **Redis** | localhost:6379 | Cache (direct access) |
|
||||
|
||||
## Services
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- **Traefik** (Port 80, 8080): API Gateway with automatic service discovery
|
||||
- **Redis** (Port 6379): Shared cache and session store
|
||||
|
||||
### Backend Services
|
||||
|
||||
- **auth-service** (Port 5001): Authentication and user management
|
||||
- Routes: `/api/v1/auth`, `/api/v1/users`
|
||||
- Health: http://localhost/api/v1/auth/health
|
||||
|
||||
### Frontend Applications
|
||||
|
||||
- **web-admin** (Port 3000): Admin dashboard (Next.js)
|
||||
- **web-client** (Port 3001): Client application (Next.js)
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Environment variables are managed in `.env.local`:
|
||||
|
||||
### Required Variables
|
||||
|
||||
```bash
|
||||
# Authentication (MUST be same across all services)
|
||||
JWT_SECRET=your-super-secret-jwt-key-min-32-characters
|
||||
JWT_REFRESH_SECRET=your-super-secret-refresh-key-min-32-characters
|
||||
|
||||
# Database (Neon PostgreSQL)
|
||||
DATABASE_URL=postgresql://user:pass@host.neon.tech/db?sslmode=require
|
||||
```
|
||||
|
||||
### Optional Variables
|
||||
|
||||
```bash
|
||||
# Redis
|
||||
REDIS_HOST=redis
|
||||
REDIS_PORT=6379
|
||||
|
||||
# Observability
|
||||
TRACING_ENABLED=false
|
||||
JAEGER_ENDPOINT=http://jaeger:14268/api/traces
|
||||
|
||||
# CORS
|
||||
CORS_ORIGIN=http://localhost:3000,http://localhost:3001
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
docker-compose up -d
|
||||
|
||||
# Start specific service
|
||||
docker-compose up -d auth-service
|
||||
|
||||
# Stop all services
|
||||
docker-compose down
|
||||
|
||||
# Stop and remove volumes
|
||||
docker-compose down -v
|
||||
|
||||
# View logs (all services)
|
||||
docker-compose logs -f
|
||||
|
||||
# View logs (specific service)
|
||||
docker-compose logs -f auth-service
|
||||
|
||||
# Restart service
|
||||
docker-compose restart auth-service
|
||||
|
||||
# Rebuild service
|
||||
docker-compose up -d --build auth-service
|
||||
|
||||
# Check service status
|
||||
docker-compose ps
|
||||
|
||||
# Execute command in container
|
||||
docker-compose exec auth-service sh
|
||||
```
|
||||
|
||||
## Adding New Service
|
||||
|
||||
1. **Add service to docker-compose.yml**:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
my-new-service:
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: services/my-new-service/Dockerfile
|
||||
container_name: my-new-service-local
|
||||
env_file:
|
||||
- .env.local
|
||||
environment:
|
||||
- PORT=5002
|
||||
- SERVICE_NAME=my-new-service
|
||||
- DATABASE_URL=${DATABASE_URL}
|
||||
- REDIS_HOST=${REDIS_HOST}
|
||||
- JWT_SECRET=${JWT_SECRET}
|
||||
ports:
|
||||
- "5002:5002"
|
||||
depends_on:
|
||||
redis:
|
||||
condition: service_healthy
|
||||
traefik:
|
||||
condition: service_started
|
||||
networks:
|
||||
- microservices-network
|
||||
restart: unless-stopped
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.my-new-service.rule=PathPrefix(`/api/v1/my-new-service`)"
|
||||
- "traefik.http.services.my-new-service.loadbalancer.server.port=5002"
|
||||
```
|
||||
|
||||
2. **Start the service**:
|
||||
|
||||
```bash
|
||||
docker-compose up -d my-new-service
|
||||
```
|
||||
|
||||
3. **Access the service**:
|
||||
- Via Traefik: http://localhost/api/v1/my-new-service
|
||||
- Direct: http://localhost:5002
|
||||
|
||||
## Traefik Configuration
|
||||
|
||||
Traefik is configured via:
|
||||
- **Static config**: `infra/traefik/traefik.yml`
|
||||
- **Dynamic config**: `infra/traefik/dynamic/`
|
||||
- **Service discovery**: Docker labels in this file
|
||||
|
||||
Services are automatically discovered by Traefik using Docker labels. No manual route configuration needed.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
```bash
|
||||
# Find process using port
|
||||
lsof -i :80
|
||||
lsof -i :5001
|
||||
|
||||
# Kill process
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### Service Won't Start
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
docker-compose logs service-name
|
||||
|
||||
# Rebuild without cache
|
||||
docker-compose build --no-cache service-name
|
||||
docker-compose up -d service-name
|
||||
```
|
||||
|
||||
### Database Connection Issues
|
||||
|
||||
```bash
|
||||
# Verify DATABASE_URL in .env.local
|
||||
cat .env.local | grep DATABASE_URL
|
||||
|
||||
# Test connection from service
|
||||
docker-compose exec auth-service sh
|
||||
# Inside container:
|
||||
# curl $DATABASE_URL (won't work, but shows if var is set)
|
||||
```
|
||||
|
||||
### Redis Connection Issues
|
||||
|
||||
```bash
|
||||
# Check Redis is running
|
||||
docker-compose ps redis
|
||||
|
||||
# Test Redis connection
|
||||
docker-compose exec redis redis-cli ping
|
||||
# Should return: PONG
|
||||
```
|
||||
|
||||
### Traefik Not Routing
|
||||
|
||||
```bash
|
||||
# Check Traefik dashboard
|
||||
open http://localhost:8080
|
||||
|
||||
# Verify service has correct labels
|
||||
docker-compose config | grep -A 5 "labels:"
|
||||
|
||||
# Check Traefik logs
|
||||
docker-compose logs traefik
|
||||
```
|
||||
|
||||
## Network Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Client │
|
||||
└───────────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────┐
|
||||
│ Traefik │ :80, :8080
|
||||
│ API Gateway │
|
||||
└───────┬───────┘
|
||||
│
|
||||
┌───────────────────┼───────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ auth-service │ │ web-admin │ │ web-client │
|
||||
│ :5001 │ │ :3000 │ │ :3001 │
|
||||
└──────┬───────┘ └──────────────┘ └──────────────┘
|
||||
│
|
||||
├─────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────┐ ┌─────────────┐
|
||||
│ Redis │ │ PostgreSQL │
|
||||
│ :6379 │ │ (Neon) │
|
||||
└──────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Traefik Configuration](../../infra/traefik/)
|
||||
- [Service Template](../../services/_template/)
|
||||
- [Development Guide](../../docs/en/guides/development.md)
|
||||
- [Neon Database Guide](../../docs/en/guides/neon-database.md)
|
||||
Reference in New Issue
Block a user