Traefik-based API gateway for the Yemaya creative production platform.
Overview#
The API gateway provides:
- Request Routing: Route requests to appropriate backend services
- Load Balancing: Distribute traffic across service instances
- TLS Termination: Handle HTTPS with automatic Let's Encrypt certificates
- Rate Limiting: Protect services from abuse
- Authentication: JWT and API key validation via forward auth
- CORS: Cross-origin resource sharing configuration
- Security Headers: HSTS, CSP, XSS protection, etc.
- Health Checks: Service health monitoring
- Metrics: Prometheus metrics for monitoring
- Tracing: Distributed tracing with Jaeger
Architecture#
text
┌─────────────────────────────────────────┐
│ Traefik API Gateway │
│ │
Internet ───────►│ :80 (HTTP) ──► Redirect to HTTPS │
│ :443 (HTTPS) ──► Route to services │
│ :50051 (gRPC) ──► gRPC services │
│ :8082 (Metrics) ──► Prometheus │
└───────────────────┬─────────────────────┘
│
┌────────────────────────────┼────────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ API Service │ │Auth Service │ │ WS Service │
│ :3000 │ │ :3001 │ │ :3002 │
└─────────────┘ └─────────────┘ └─────────────┘
Quick Start#
Development#
bash
# Start the gateway in development mode
docker compose -f docker-compose.dev.yml up -d
# View logs
docker compose -f docker-compose.dev.yml logs -f traefik
# Access dashboard
open http://localhost:8080
Production#
bash
# Copy environment file
cp .env.example .env
# Edit configuration
vi .env
# Generate dashboard password hash
htpasswd -nb admin yourpassword | sed -e s/\\$/\\$\\$/g
# Start the gateway
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
Configuration#
Directory Structure#
text
gateway/
├── config/
│ ├── traefik.yml # Static configuration
│ └── dynamic/
│ ├── services.yml # Service routing
│ ├── middleware.yml # Middleware definitions
│ ├── middleware-dev.yml # Development overrides
│ ├── tls.yml # TLS configuration
│ └── health.yml # Health check endpoints
├── certs/ # TLS certificates
├── scripts/
│ └── generate-dev-certs.sh # Generate dev certificates
├── docker-compose.yml # Base compose file
├── docker-compose.dev.yml # Development override
├── docker-compose.prod.yml # Production override
└── .env.example # Environment template
Environment Variables#
| Variable | Description | Default |
|---|---|---|
DOMAIN |
Base domain for routing | localhost |
ACME_EMAIL |
Let's Encrypt email | - |
TRAEFIK_DASHBOARD_USER |
Dashboard username | admin |
TRAEFIK_DASHBOARD_PASSWORD_HASH |
Bcrypt password hash | - |
LOG_LEVEL |
Logging level | INFO |
Routing#
API Routes#
| Route | Service | Description |
|---|---|---|
api.{domain}/v1/* |
api-service | Main REST API |
api.{domain}/docs |
api-service | Swagger UI |
api.{domain}/reference |
api-service | Scalar API Reference |
api.{domain}/health |
api-service | Health endpoints |
auth.{domain}/* |
auth-service | Authentication service |
ws.{domain} |
ws-service | WebSocket connections |
cdn.{domain}/* |
cdn-service | Asset delivery |
gRPC Routes#
gRPC services are available on port 50051:
- Auth Service
- User Service
- Project Service
- Asset Service
Middleware#
Rate Limiting#
| Middleware | Limit | Use Case |
|---|---|---|
rate-limit |
100 req/min | Standard API |
rate-limit-auth |
60 req/min | Auth endpoints |
rate-limit-password-reset |
5 req/hour | Password reset |
rate-limit-upload |
30 req/min | File uploads |
Security Headers#
All responses include:
Strict-Transport-Security(HSTS)Content-Security-Policy(CSP)X-Content-Type-Options: nosniffX-Frame-Options: DENYX-XSS-Protection: 1; mode=blockReferrer-Policy: strict-origin-when-cross-origin
Authentication#
Forward authentication to the auth service:
jwt-auth: Validates JWT tokensapi-key-auth: Validates API keysoptional-auth: Non-blocking auth check
Health Checks#
| Endpoint | Description |
|---|---|
/gateway/health |
Gateway health status |
/gateway/metrics |
Prometheus metrics |
Monitoring#
Prometheus Metrics#
Metrics are exposed on port 8082:
text
http://localhost:8082/metrics
Available metrics:
traefik_entrypoint_requests_totaltraefik_entrypoint_request_duration_secondstraefik_service_requests_totaltraefik_service_request_duration_seconds
Grafana Dashboard#
Import the Traefik dashboard from Grafana:
- Dashboard ID: 17346
TLS Configuration#
Development#
Generate self-signed certificates:
bash
./scripts/generate-dev-certs.sh localhost
Production#
Let's Encrypt certificates are automatically obtained and renewed.
TLS options:
- Minimum version: TLS 1.2
- Preferred: TLS 1.3
- Strong cipher suites only
Troubleshooting#
View Logs#
bash
# All logs
docker compose logs -f traefik
# Access logs only
docker compose logs -f traefik 2>&1 | grep accesslog
Debug Mode#
Enable debug logging:
bash
docker compose -f docker-compose.dev.yml up -d
Test Routes#
bash
# Test whoami service
curl http://localhost/whoami
# Test with host header
curl -H "Host: api.localhost" http://localhost/health
Check Configuration#
bash
# Validate configuration
docker compose exec traefik traefik healthcheck
# View current configuration
curl http://localhost:8080/api/rawdata/routers
Security Considerations#
- Never expose the dashboard in production without authentication
- Use strong passwords for dashboard access
- Review rate limits based on your traffic patterns
- Monitor for suspicious activity using access logs
- Keep Traefik updated for security patches
- Use network policies to restrict internal traffic
Contributing#
When modifying the gateway configuration:
- Test changes in development first
- Validate configuration syntax
- Check for breaking changes in routing
- Update this documentation
- Test with all backend services