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

```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

- **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.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 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**:

```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 iam-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  │
                    └───────┬───────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ iam-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)