318 lines
7.8 KiB
Markdown
318 lines
7.8 KiB
Markdown
# 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
|
|
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
|
|
|
|
```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
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```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 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
|
|
|
|
```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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```bash
|
|
# 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](../../infra/traefik/)
|
|
- [Service Template](../../services/_template/)
|
|
- [Development Guide](../../docs/en/guides/development.md)
|
|
- [Neon Database Guide](../../docs/en/guides/neon-database.md)
|