Eve library

Yemaya API Gateway

Other

Revision 1

On this page

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: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block
  • Referrer-Policy: strict-origin-when-cross-origin

Authentication#

Forward authentication to the auth service:

  • jwt-auth: Validates JWT tokens
  • api-key-auth: Validates API keys
  • optional-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_total
  • traefik_entrypoint_request_duration_seconds
  • traefik_service_requests_total
  • traefik_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#

  1. Never expose the dashboard in production without authentication
  2. Use strong passwords for dashboard access
  3. Review rate limits based on your traffic patterns
  4. Monitor for suspicious activity using access logs
  5. Keep Traefik updated for security patches
  6. Use network policies to restrict internal traffic

Contributing#

When modifying the gateway configuration:

  1. Test changes in development first
  2. Validate configuration syntax
  3. Check for breaking changes in routing
  4. Update this documentation
  5. Test with all backend services