hermes-ice/homelab/entities/traefik.md

title, created, updated, type, tags, sources

title	created	updated	type	tags	sources
traefik	2026-04-28	2026-04-29	entity	services networking reverse-proxy ha docker

traefik

Role: Reverse proxy / ingress controller — HA across grizzley + ubuntu Instances: 2 (ubuntu = PRIMARY, grizzley = BACKUP) Ports: 80 (HTTP), 443 (HTTPS), 2222 (SSH proxy), 8080 (metrics) Dashboard: traefik dashboard on each instance

Overview

Traefik is the reverse proxy for the homelab. It runs in HA mode across grizzley and ubuntu, handling TLS termination for all incoming traffic. Cloudflare routes DNS to Traefik. Two separate Docker Compose stacks manage each instance independently.

Instances

Instance	Host	Role	Ports	Cert Source
traefik (ubuntu)	ubuntu (192.168.50.61)	PRIMARY — handles majority of traffic	80, 443	Syncs from grizzley via NFS
traefik-pi (grizzley)	grizzley (192.168.50.84)	BACKUP + ACME cert generation	80, 443, 2222, 8080	Cloudflare DNS challenge

Ubuntu (Primary)

Docker Compose: homelab/ubuntu/traefik/

• Network: proxy-net (bridge)
• Reads TLS certs from NFS mount at /mnt/truenas/traefik-certs/
• Prometheus metrics: port 8080
• Connects via authentik_authentik-internal for SSO middleware

Grizzley (Backup + ACME)

Docker Compose: homelab/grizzley/traefik-pi/

• Network: traefik-proxy (bridge)
• Generates wildcard certs via Cloudflare DNS challenge
• Writes certs to NFS mount /mnt/truenas/traefik-certs/grizzley
• Prometheus metrics: port 8080

HA Configuration (Keepalived VRRP)

Parameter	Value
Interface	eth0.50 (VLAN 50)
Virtual Router ID	51
grizzley State	BACKUP (priority 90)
ubuntu State	PRIMARY (higher priority)
Virtual IP	192.168.50.80/27
Auth	PASS (HomelabH)
Check Script	/etc/keepalived/check_traefik.sh (2s interval, fall 2, rise 2)

When ubuntu Traefik fails health checks, keepalived promotes grizzley to MASTER and traffic to 192.168.50.80 fails over automatically.

Certificate Flow

Cloudflare DNS Challenge
        ↓
traefik-pi on grizzley (ACME DNS challenge)
        ↓
Writes certs to /mnt/TrueNAS/traefik-certs/grizzley (NFS)
        ↓
traefik on ubuntu reads same certs from NFS mount
        ↓
Both serve *.tophermayor.com wildcard cert

Routes (Known)

Service	URL	Host
Authentik	authentik.tophermayor.com	ubuntu
Gitea	gitea.tophermayor.com	ubuntu
OpenCode (ice)	opencode-ice.tophermayor.com	ubuntu → ice:4096
Jellyfin	jellyfin.tophermayor.com	grizzley
Proxmox	proxmox.tophermayor.com	ubuntu → proxmox
Immich	immich.tophermayor.com	ubuntu
Homepage	home.tophermayor.com	ubuntu

Dynamic config files in homelab/ubuntu/traefik/config/dynamic/:

File	Services
canonical-hosts.yml	Grizzley ingress proxy, PVE OpenCode
gitea.yml	gitea.tophermayor.com
immich.yml	immich.tophermayor.com
jellyfin.yml	jellyfin.tophermayor.com
media-stack.yml	Sonarr, Radarr, SABnzbd, Prowlarr, qBittorrent
middlewares.yml	30+ middleware definitions
opencode.yml	opencode.tophermayor.com
proxmox.yml	proxmox.local.tophermayor.com

Middlewares

Middleware	Purpose
local-only@file	Restrict to local network IPs
authentik-auth@file	SSO authentication
security-headers@file	Add security headers
crowdsec-bouncer@file	Rate limiting and threat protection

Prometheus Monitoring

Both Traefik instances expose Prometheus metrics at :8080/metrics. The monitoring stack scrapes:

• Request rates
• Error rates
• Backend health

Troubleshooting

• ServiceDown alerts: see homelab-servicedown-triage skill
• DNS issues: see homelab-systemd-resolved-dns skill
• VRRP failover: check systemctl status keepalived on grizzley
• Certificate issues: check NFS mount /mnt/truenas/traefik-certs/ on both hosts
• traefik-pi not starting: check docker logs traefik-pi on grizzley

Related

• ubuntu — Primary Traefik node
• grizzley — Backup Traefik node + ACME generation
• truenas — NFS storage for cert sync
• authentik — SSO behind Traefik
• traefik-ha — Full HA concept page