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

Local Development Deployment

This directory contains Docker Compose configuration for running the entire GoodGo platform locally.

Quick Start

# 1. Setup environment variables
cp env.local.example .env
cp env.local.example .env.local
# Edit both files with your values (JWT_SECRET, service DB URLs, Redis, 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

• iam-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 and .env.local:

Required Variables

# 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
JWT_ID_SECRET=your-super-secret-id-key-min-32-characters

# IAM + service databases (Neon PostgreSQL)
IAM_DATABASE_URL=Host=...;Port=5432;Database=iam_service;Username=...;Password=...;SSL Mode=Require
STORAGE_DATABASE_URL=Host=...;Port=5432;Database=storage_service;Username=...;Password=...;SSL Mode=Require
ORDER_DATABASE_URL=Host=...;Port=5432;Database=order_service;Username=...;Password=...;SSL Mode=Require

Optional Variables

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=replace-with-redis-password

# Observability
TRACING_ENABLED=false
JAEGER_ENDPOINT=http://jaeger:14268/api/traces

# CORS
CORS_ORIGIN=http://localhost:3000,http://localhost:3001

# Object storage and messaging
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=...
MINIO_SECRET_KEY=...
RABBITMQ_PASSWORD=...

Common Commands

# Start all services
docker-compose up -d

# Start specific service
docker-compose up -d iam-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 iam-service

# Restart service
docker-compose restart iam-service

# Rebuild service
docker-compose up -d --build iam-service

# Check service status
docker-compose ps

# Execute command in container
docker-compose exec iam-service sh

Adding New Service

1. Add service to docker-compose.yml:

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:

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

# Find process using port
lsof -i :80
lsof -i :5001

# Kill process
kill -9 <PID>

Service Won't Start

# 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

# Verify IAM_DATABASE_URL in .env/.env.local
cat .env | grep IAM_DATABASE_URL

# Test connection from service
docker-compose exec iam-service sh
# Inside container:
# curl $DATABASE_URL (won't work, but shows if var is set)

Redis Connection Issues

# Check Redis is running
docker-compose ps redis

# Test Redis connection
docker-compose exec redis redis-cli ping
# Should return: PONG

Traefik Not Routing

# 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

graph TB
 Client[ Client<br/>Browser] --> Traefik

 Traefik[ Traefik<br/>API Gateway<br/>:80, :8080]

 Traefik --> IAM[ IAM Service<br/>Authentication<br/>:5001]
 Traefik --> Admin[ Web Admin<br/>Dashboard<br/>:3000]
 Traefik --> WebClient[ Web Client<br/>Application<br/>:3001]

 IAM --> Redis[( Redis<br/>Cache<br/>:6379)]
 IAM --> DB[( PostgreSQL<br/>Neon Database)]

 classDef client fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#eee
 classDef gateway fill:#0f3460,stroke:#16213e,stroke-width:3px,color:#eee
 classDef service fill:#16213e,stroke:#533483,stroke-width:2px,color:#eee
 classDef frontend fill:#1a1a40,stroke:#6c5ce7,stroke-width:2px,color:#eee
 classDef data fill:#2d132c,stroke:#801336,stroke-width:2px,color:#eee

 class Client client
 class Traefik gateway
 class IAM service
 class Admin,WebClient frontend
 class Redis,DB data

Legend:

• Client: External users via browser
• Gateway: Traefik API Gateway (auto-routing)
• Backend: IAM Service (authentication)
• Frontend: Web Admin & Client applications
• Storage: Redis cache & PostgreSQL database

Quick Tips

Common Issues

Problem	Solution
Port conflict	Check if port 80/5001/6379 is already in use: lsof -i :<port>
Service won't start	Check logs: docker-compose logs <service-name>
Database connection	Verify DATABASE_URL in .env.local is correct
Redis connection	Ensure Redis is healthy: docker-compose exec redis redis-cli ping
Traefik routing	Check dashboard at http://localhost:8080 for route status

Development Workflow

# Quick restart (code changes)
docker-compose restart iam-service

# Full rebuild (dependency changes)
docker-compose up -d --build iam-service

# Clean restart (database issues)
docker-compose down -v && docker-compose up -d

Security Checklist

• Change default JWT_SECRET (min 32 characters)
• Use environment-specific .env / .env.local with real secrets (never commit real values)
• Verify CORS origins match your frontend URLs
• Enable HTTPS in production (not needed for local)

Monitoring

• Traefik Dashboard: http://localhost:8080 - View all routes and services
• Service Health: http://localhost/api/v1/auth/health - Check service status
• Redis CLI: docker-compose exec redis redis-cli - Query cache directly

Resources

• Traefik Configuration
• Service Template
• Development Guide
• Neon Database Guide