Overview

Add a --profile tls option to docker-compose that enables HTTPS on the Nginx caching proxy with zero manual configuration. Certificates are auto-generated on first run if not present.

🎯 User Experience Goals

📋 Tasks

Phase 1: Create TLS-enabled nginx config

• Create infra/nginx/nginx-tls.conf with SSL enabled (copy of nginx.conf with SSL blocks uncommented)
• Add HTTP→HTTPS redirect option (configurable)
• Ensure SSE/WebSocket work over TLS

Phase 2: Add cert_init service

• Add cert_init service to docker-compose.yml (profile: tls)
• Use alpine/openssl image (small, has openssl)
• Generate certs only if ./certs/cert.pem doesn't exist
• Match cert generation logic from make certs

Phase 3: Add nginx TLS profile override

• Add nginx service override with profiles: ["tls"]
• Mount ./certs:/app/certs:ro
• Mount nginx-tls.conf instead of nginx.conf
• Expose port 8443:443
• Add depends_on: cert_init with service_completed_successfully
• Update healthcheck to support HTTPS

Phase 4: Makefile integration

• Add make docker-tls target
• Add make docker-tls-down target
• Update help text

Phase 5: Documentation

• Add TLS section to docker-compose comments
• Document custom cert usage
• Document combining with other profiles

🔧 Implementation Details

cert_init service:

cert_init:
  image: alpine/openssl:latest
  volumes:
    - ./certs:/certs
  entrypoint: ["/bin/sh", "-c"]
  command:
    - |
      if [ -f /certs/cert.pem ] && [ -f /certs/key.pem ]; then
        echo "✅ Certificates found in ./certs - using existing"
        exit 0
      fi
      echo "🔏 Generating self-signed TLS certificate..."
      mkdir -p /certs
      openssl req -x509 -newkey rsa:4096 -sha256 -days 365 -nodes \
        -keyout /certs/key.pem -out /certs/cert.pem \
        -subj "/CN=localhost" \
        -addext "subjectAltName=DNS:localhost,DNS:gateway,DNS:nginx,IP:127.0.0.1"
      chmod 644 /certs/cert.pem
      chmod 640 /certs/key.pem
      echo "✅ TLS certificate generated in ./certs"
  profiles: ["tls"]

Makefile targets:

docker-tls:                      ## Start with TLS enabled (auto-generates certs)
    docker compose --profile tls up -d

docker-tls-down:                 ## Stop TLS-enabled stack
    docker compose --profile tls down

✅ Acceptance Criteria

• make docker-tls starts stack with HTTPS on port 8443
• First run auto-generates self-signed certs in ./certs/
• Subsequent runs reuse existing certs
• Custom certs in ./certs/ are used instead of generating new ones
• SSE endpoints work over TLS (/servers/*/sse)
• WebSocket endpoints work over TLS (/servers/*/ws)
• Admin UI accessible at https://localhost:8443/admin
• Combined profiles work: docker compose --profile tls --profile monitoring up -d
• HTTP (8080) still works alongside HTTPS (8443)

🧠 Environment Info

📎 Related

• Existing targets: make certs, make serve-ssl
• Existing profiles: monitoring, testing, benchmark
• nginx config: infra/nginx/nginx.conf