Problem

When enabling SSL/TLS in docker-compose.yml, the gateway container gets stuck in "starting" state and never becomes healthy.

Steps to Reproduce

1. Enable SSL in docker-compose.yml:

   environment:
     - SSL=true
     - CERT_FILE=/app/certs/cert.pem
     - KEY_FILE=/app/certs/key-encrypted.pem
     - KEY_FILE_PASSWORD=${KEY_FILE_PASSWORD}

2. Generate certificates:

   make certs-passphrase

3. Start services:

   make docker-prod
   make compose-up

4. Check status:

   docker compose ps

Expected Behavior

Gateway container should show status: Up (healthy)

Actual Behavior

• Gateway shows status: Up (starting) indefinitely
• docker compose logs gateway shows workers stuck at "Waiting for application startup"
• Healthcheck never passes

Additional Issues

When SSL is configured:

1. TLS handshake errors appear in gateway logs when nginx connects:

   [INFO] TCP handshake failed with error: TlsAcceptError {
     error: Custom { kind: InvalidData, error: InvalidMessage(InvalidContentType) }
   }
   

2. 502 Bad Gateway from nginx proxy at http://localhost:8080

3. No documentation for configuring TLS in docker-compose deployments

Environment

• Docker Compose deployment
• HTTP_SERVER: granian (also affects gunicorn)
• Self-signed certificates with passphrase protection
• Container: mcpgateway/mcpgateway:latest

Root Cause

1. Healthcheck issue: Using curl -f on HTTPS endpoint with self-signed cert fails SSL verification
2. Nginx connection pool: Reuses old HTTP connections to now-HTTPS gateway
3. Missing nginx SSL config: Backend connections not configured for HTTPS
4. Missing documentation: No guidance for TLS setup in containers

Proposed Solution

1. Fix healthcheck to skip SSL verification: curl -fk https://localhost:4444/health
2. Add nginx backend SSL configuration with proxy_ssl_verify off for self-signed certs
3. Create comprehensive TLS configuration documentation
4. Update certificate generation to use AES256 encryption properly

🧩 Affected Component

Select the area of the project impacted:

• mcpgateway - API
• mcpgateway - UI (admin panel)
• mcpgateway.wrapper - stdio wrapper
• Federation or Transports
• CLI, Makefiles, or shell scripts
• Container setup (Docker/Podman/Compose)
• Other (explain below)