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

# 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