Passer au contenu
homelab-docs

Traefik

Le contenu de cette page n'est pas encore traduit dans votre langue. Vous pouvez consulter la version originale en anglais.

Traefik is a modern reverse proxy and load balancer that makes deploying microservices easy. It automatically discovers services and configures itself to route traffic to them, making it an ideal choice for managing your homelab’s network traffic.

Purpose

Section titled “Purpose”

Traefik serves as a reverse proxy and load balancer that sits between the internet and your internal services. It automatically:

  • Routes incoming requests from your domain names (like dozzle.nixlab.ch) to the correct internal services
  • Handles SSL/TLS certificates automatically using Let’s Encrypt
  • Discovers Docker services automatically and configures routing rules

Prerequisites

Section titled “Prerequisites”

Before setting up Traefik, you need to:

  1. Possess a domain name (purchased from any registrar like Infomaniak)

  2. Transfer nameservers to Cloudflare for easier DNS management

    You can follow these documentation steps from Infomaniak and Cloudflare

  3. Create a Cloudflare API token

  4. Configure DNS records in Cloudflare

    • Add an A record pointing to your server’s IP address
    • Add a wildcard CNAME record (*.nixlab.ch) pointing to your domain (nixlab.ch)
    • Set both records to “DNS only” (no proxy)

Docker Compose Configuration

Section titled “Docker Compose Configuration”
compose.yaml
services:
  traefik:
    image: traefik:latest
    container_name: traefik
    ports:
      - 80:80 # HTTP entrypoint
      - 443:443 # HTTPS entrypoint
      - 8080:8080 # (Optional) Enable Dashboard, don't do in production
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /run/docker.sock:/run/docker.sock:ro
      - /opt/containers/traefik/config/traefik.yaml:/etc/traefik/traefik.yaml:ro
      - /opt/containers/traefik/config/dynamic:/etc/traefik/dynamic:ro
      - /opt/containers/traefik/certs:/var/traefik/certs/:rw
    environment:
      - CF_DNS_API_TOKEN=${CF_DNS_API_TOKEN}  # <-- Change this to your Cloudflare access token
      - CF_API_EMAIL=${CF_API_EMAIL}
    networks:
      - traefik_proxy
    labels:
      - "traefik.enable=true"
      # HTTP EntryPoint
      # - "traefik.http.routers.traefik-http.entrypoints=web"
      # - "traefik.http.routers.traefik-http.rule=Host(`traefik.nixlab.ch`)"


      # HTTPS EntryPoint
      - "traefik.http.routers.traefik-https.tls=true"
      - "traefik.http.routers.traefik-https.entrypoints=websecure"
      - "traefik.http.routers.traefik-https.tls.certresolver=cloudflare"
      - "traefik.http.routers.traefik-https.rule=Host(`traefik.nixlab.ch`)"


      # Services
      - "traefik.http.services.traefik.loadbalancer.server.port=8080"
    restart: unless-stopped


networks:
  traefik_proxy:
    external: true  # Make sure this network exists, create it with: docker network create traefik_proxy

Configuration

Section titled “Configuration”

Create the configuration file at /opt/containers/traefik/config/traefik.yaml:

traefik.yaml
global:
  checkNewVersion: false
  sendAnonymousUsage: false


log:
  level: DEBUG # [TRACE, DEBUG, INFO, WARN, ERROR, FATAL]


api:
  dashboard: true
  insecure: true
  debug: false


entryPoints:
  web:
    address: :80
    forwardedHeaders:
      trustedIPs: &trustedIps
        # Start of Cloudlare's public IP list
        - 103.21.244.0/22
        - 103.22.200.0/22
        - 103.31.4.0/22
        - 104.16.0.0/13
        - 104.24.0.0/14
        - 108.162.192.0/18
        - 131.0.72.0/22
        - 141.101.64.0/18
        - 162.158.0.0/15
        - 172.64.0.0/13
        - 173.245.48.0/20
        - 188.114.96.0/20
        - 190.93.240.0/20
        - 197.234.240.0/22
        - 198.41.128.0/17
        - 2400:cb00::/32
        - 2606:4700::/32
        - 2803:f800::/32
        - 2405:b500::/32
        - 2405:8100::/32
        - 2a06:98c0::/29
        - 2c0f:f248::/32
        # End of Cloudlare's public IP list
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https


  websecure:
    address: :443
    forwardedHeaders:
      trustedIPs: *trustedIps # use the same trusted IPs as for web entrypoint
    http:
      tls:
        certResolver: cloudflare
        domains:
          - main: nixlab.ch
            sans:
              - '*.nixlab.ch'


providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
    network: traefik_proxy


  file:
    directory: /etc/traefik/dynamic
    watch: true


certificatesResolvers:
  cloudflare:
    acme:
      email: your@email.com # Your email for Let's Encrypt notifications
      storage: /var/traefik/certs/cloudflare-acme.json
      caServer: https://acme-v02.api.letsencrypt.org/directory # prod (default)
      # caServer: https://acme-staging-v02.api.letsencrypt.org/directory # staging
      keyType: EC256
      dnsChallenge:
        provider: cloudflare
        resolvers:
          - "1.1.1.1:53"
          - "8.8.8.8:53"

Setup Instructions

Section titled “Setup Instructions”

  1. Create the necessary directories:

    Terminal window
    mkdir -p /opt/containers/traefik/config/dynamic
    mkdir -p /opt/containers/traefik/certs

  2. Create the Traefik network:

    Terminal window
    docker network create traefik_proxy

  3. Create your .env file with your Cloudflare credentials:

    CF_DNS_API_TOKEN=your_cloudflare_api_token
    CF_API_EMAIL=your_email@example.com

  4. Update the email address in traefik.yaml for Let’s Encrypt notifications

  5. Start Traefik:

    Terminal window
    docker-compose up -d

Usage with Other Services

Section titled “Usage with Other Services”

To expose other services through Traefik, add these labels to their Docker Compose configurations:

# Example for Dozzle service
services:
  dozzle:
    image: amir20/dozzle:latest
    container_name: dozzle
    networks:
      - traefik_proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dozzle.rule=Host(`dozzle.nixlab.ch`)"
      - "traefik.http.routers.dozzle.entrypoints=websecure"
      - "traefik.http.routers.dozzle.tls=true"
      - "traefik.http.routers.dozzle.tls.certresolver=cloudflare"
      - "traefik.http.services.dozzle.loadbalancer.server.port=8080"


networks:
  traefik_proxy:
    external: true

How It Works

Section titled “How It Works”

  1. Domain Routing: When someone visits dozzle.nixlab.ch, Traefik receives the request and forwards it to your Dozzle container based on the routing rules defined in Docker labels.

  2. Automatic HTTPS: The configuration uses Cloudflare’s DNS challenge to automatically obtain and renew SSL certificates from Let’s Encrypt, ensuring all your services are accessible via HTTPS.

  3. Service Discovery: Traefik monitors your Docker containers and automatically creates routes when you add the appropriate labels to your services.

  4. Certificate Management: The cloudflare certificate resolver uses DNS challenges to prove domain ownership. Certificates are stored in /var/traefik/certs/ and automatically renewed.

This setup eliminates the need to manually configure SSL certificates or update DNS records for each service - Traefik handles everything automatically once properly configured.

References