Homelab/docs/guides/traefik_setup_guide.md

Traefik Setup Guide for Docker Swarm

This guide provides the step-by-step instructions to correctly configure and deploy Traefik in a Docker Swarm environment, especially when dealing with potentially read-only host filesystems.

This method uses Docker Configs and Docker Volumes to manage Traefik's configuration and data, which is the standard best practice for Swarm. All commands should be run on your Docker Swarm manager node.

---

Step 1: Create the traefik.yml Configuration File

This step creates the Traefik static configuration file. You have two options:

Option A: Using sudo tee (Direct Host Write)

This command uses a HEREDOC with sudo tee to write the traefik.yml file directly to your manager node's filesystem. This is generally straightforward if your manager node's filesystem is writable.

Action:

1. IMPORTANT: Replace your-email@example.com with your actual email address in the command below.
2. Copy and paste the entire block into your Zsh terminal on the manager node.

# --- Creates the traefik.yml file ---
sudo tee ./traefik.yml > /dev/null <<'EOF'
global:
  checkNewVersion: true
  sendAnonymousUsage: false

log:
  level: INFO

api:
  dashboard: true
  insecure: false

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

providers:
  docker:
    network: traefik-public
    exposedByDefault: false

certificatesResolvers:
  leresolver:
    acme:
      email: "your-email@example.com"
      storage: "/letsencrypt/acme.json"
      dnsChallenge:
        provider: duckdns
        delayBeforeCheck: "120s"
EOF

Option B: Using docker run (Via Temporary Container)

This method creates the traefik.yml file inside a temporary busybox container and then copies it to your manager node's current directory. This is useful if you prefer to avoid direct sudo tee or if you're working in an environment where direct file creation is restricted.

Action:

1. IMPORTANT: Replace your-email@example.com with your actual email address in the command below.
2. Copy and paste the entire block into your Zsh terminal on the manager node.

# --- Creates the traefik.yml file in a temporary container and copies it out ---
docker run --rm -i -v "$(pwd):/host" busybox sh -c 'cat > /host/traefik.yml <<\'EOF\'
checkNewVersion: true
sendAnonymousUsage: false

log:
  level: INFO

api:
  dashboard: true
  insecure: false

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

providers:
  docker:
    network: traefik-public
    exposedByDefault: false

certificatesResolvers:
  leresolver:
    acme:
      email: "your-email@example.com"
      storage: "/letsencrypt/acme.json"
      dnsChallenge:
        provider: duckdns
        delayBeforeCheck: 30s
        resolvers:
          - "192.168.1.196:53"
          - "192.168.1.245:53"
          - "192.168.1.62:53"
EOF'

Note on Versioning: The traefik:latest tag can introduce unexpected breaking changes, as seen here. For production or stable environments, it is highly recommended to pin to a specific version in your stack file, for example: image: traefik:v2.11 or image: traefik:v3.0.

---

Step 2: Create the Docker Swarm Config

This command ingests the traefik.yml file (created in Step 1) into Docker Swarm, making it securely available to services.

Action: Run the following command on your manager node.

docker config create traefik.yml ./traefik.yml

---

Step 3: Create the Let's Encrypt Volume

This creates a managed Docker Volume that will persist your TLS certificates.

Action: Run the following command on your manager node.

docker volume create traefik_letsencrypt

---

Step 4: Prepare the acme.json File

Traefik requires an acme.json file to exist with the correct permissions before it can start. This command creates the empty file inside the volume you just made.

Action: Run the following command on your manager node.

docker run --rm -v traefik_letsencrypt:/letsencrypt busybox sh -c "touch /letsencrypt/acme.json && chmod 600 /letsencrypt/acme.json"

---

Step 5: Update and Deploy the networking-stack.yml

You can now deploy your networking-stack using the YAML below. It has been modified to use the Swarm config and volume instead of host paths.

Action:

1. IMPORTANT: Replace YOUR_DUCKDNS_TOKEN with your actual DuckDNS token in the environment section.
2. Upload this YAML content to Portainer to deploy your stack.

version: '3.9'

networks:
  traefik-public:
    external: true

volumes:
  traefik_letsencrypt:
    external: true

configs:
  traefik_yml:
    external: true
    name: traefik.yml

services:
  traefik:
    image: traefik:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - traefik_letsencrypt:/letsencrypt
    networks:
      - traefik-public
    environment:
      - "DUCKDNS_TOKEN=YOUR_DUCKDNS_TOKEN"
    configs:
      - source: traefik_yml
        target: /traefik.yml
    deploy:
      labels:
        - "traefik.enable=true"
        - "traefik.http.routers.traefik.rule=Host(`traefik.sj98.duckdns.org`)"
        - "traefik.http.routers.traefik.entrypoints=websecure"
        - "traefik.http.routers.traefik.tls.certresolver=leresolver"
        - "traefik.http.routers.traefik.service=api@internal"
      placement:
        constraints:
          - node.role == manager

  whoami:
    image: traefik/whoami
    networks:
      - traefik-public
    deploy:
      labels:
        - "traefik.enable=true"
        - "traefik.http.routers.whoami.rule=Host(`whoami.sj98.duckdns.org`)"
        - "traefik.http.routers.whoami.entrypoints=websecure"
        - "traefik.http.routers.whoami.tls.certresolver=leresolver"
        - "traefik.http.services.whoami.loadbalancer.server.port=80"

---

Step 6: Clean Up (Optional)

Since the configuration is now stored in Docker Swarm, you can remove the local traefik.yml file from your manager node's filesystem.

Action: Run the following command on your manager node.

rm ./traefik.yml

---

Troubleshooting and Removal

If you encounter an error and need to start the setup process over, follow these steps to cleanly remove all the components you created. Run these commands on your Docker Swarm manager node.

Step 1: Remove the Stack

First, remove the deployed stack from your Swarm.

Action:

• In Portainer, go to "Stacks", select your networking-stack, and click "Remove".

Step 2: Remove the Docker Config

This removes the Traefik configuration that was stored in the Swarm.

Action:

docker config rm traefik.yml

Step 3: Remove the Docker Volume

This deletes the volume that was storing your Let's Encrypt certificates. Warning: This will delete your existing certificates.

Action:

docker volume rm traefik_letsencrypt

Step 4: Remove the Local Config File (If Present)

If you didn't delete the traefik.yml file in the optional clean-up step, remove it now.

Action:

rm ./traefik.yml

After completing these steps, your environment will be clean, and you can safely re-run the setup guide from the beginning.

---

Step 7: Verify Traefik Dashboard

Once your networking-stack is deployed and Traefik has started, you can verify its functionality by accessing the Traefik dashboard.

Action:

1. Open your web browser and navigate to the Traefik dashboard:

   • Traefik Dashboard: https://traefik.sj98.duckdns.org

   You should see the Traefik dashboard, listing your routers and services. If you see a certificate warning, it might take a moment for Let's Encrypt to issue the certificate. If the dashboard loads, Traefik is running correctly.