Skip to main content

Traefik

Reverse proxy and TLS termination for all RavenmaskOS services.

Overview​

Traefik is the edge router that handles all incoming traffic, terminates TLS, and routes requests to backend services based on hostname.

PropertyValue
Imagetraefik:v3.2
Containertraefik
URLtraefik.ravenhelm.dev
Ports80, 443 (external)
Config~/ravenhelm/services/traefik/
Data~/ravenhelm/data/traefik/

Architecture​

Internet → :443 → Traefik → Backend Services
                     │
                     ├── TLS Termination (Let's Encrypt)
                     ├── Automatic HTTPS redirect
                     ├── Basic Auth (dashboard)
                     └── Docker provider (auto-discovery)

Configuration​

Static Configuration​

~/ravenhelm/data/traefik/config/traefik.yml:

api:
  dashboard: true
  insecure: false

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
    network: ravenhelm_net
  file:
    directory: /etc/traefik/dynamic
    watch: true

certificatesResolvers:
  letsencrypt:
    acme:
      email: nate@ravenhelm.dev
      storage: /certs/acme.json
      dnsChallenge:
        provider: route53
        delayBeforeCheck: 0

Docker Labels​

Services are exposed via Docker labels:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.myservice.rule=Host(`myservice.ravenhelm.dev`)"
  - "traefik.http.routers.myservice.entrypoints=websecure"
  - "traefik.http.routers.myservice.tls.certresolver=letsencrypt"
  - "traefik.http.services.myservice.loadbalancer.server.port=8080"

Quick Commands​

# View logs
docker logs -f traefik

# Restart
docker restart traefik

# Check certificate status
docker exec traefik cat /certs/acme.json | jq '.letsencrypt.Certificates[].domain'

# View active routers
curl -s http://localhost:8080/api/http/routers | jq '.[].name'

Health Check​

# Dashboard accessible
curl -s -o /dev/null -w "%{http_code}" https://traefik.ravenhelm.dev

# Certificate valid
echo | openssl s_client -servername traefik.ravenhelm.dev -connect traefik.ravenhelm.dev:443 2>/dev/null | openssl x509 -noout -dates

Troubleshooting​

Issue: 404 Not Found​

Symptoms: Service returns 404 even though container is running

Diagnosis:

# Check if container has correct labels
docker inspect <container> | jq '.[0].Config.Labels'

# Check if on correct network
docker network inspect ravenhelm_net | jq '.[0].Containers'

Solutions:

  1. Verify traefik.enable=true label exists
  2. Confirm container is on ravenhelm_net network
  3. Check router rule matches expected hostname

Issue: Certificate Errors​

Symptoms: Browser shows certificate warning

Diagnosis:

# Check ACME log
docker logs traefik 2>&1 | grep -i acme

# Verify DNS
dig +short service.ravenhelm.dev

Solutions:

  1. Verify AWS credentials in .env
  2. Check DNS propagation
  3. Delete acme.json and restart (forces renewal)

Issue: 502 Bad Gateway​

Symptoms: Traefik can reach router but backend fails

Diagnosis:

# Check backend container
docker ps | grep <service>

# Check internal connectivity
docker exec traefik wget -qO- http://<container>:<port>/health

Solutions:

  1. Verify backend container is running
  2. Check backend port matches label
  3. Verify backend is on ravenhelm_net

Runbooks​