This content originally appeared on DEV Community and was authored by Luc Allaire
Every Traefik service you expose already has a Host() rule that declares its public hostname. That information exists exactly once — in a Docker label — and propagates nowhere useful.
So you end up maintaining three or four systems by hand: Cloudflare for public DNS, NetBird for internal VPN-only hostnames, Uptime Kuma for monitoring — with groups, tags, and status pages configured per service. Add a container and you need to update everything manually. Remove it 4 months later and those records stay unless you remember to clean them up.
traefik-mesh-companion makes the container definition the single source of truth and syncs the rest automatically.
What It Does
A Go sidecar that watches the Docker socket and syncs your Traefik routing labels to:
- NetBird — internal mesh VPN DNS records
- Cloudflare — A records or CNAMEs to a CF Tunnel endpoint
- Uptime Kuma — monitors, status page groups, tags, domain bindings
- Gatus (via Gatus Bridge) — endpoints and groups
A single Docker Compose sidecar. No Kubernetes, no Helm, no operator.
How It Works
Split-Horizon DNS via Entrypoints
No new label namespace for DNS routing. Two env vars filter your existing entrypoint labels:
INTERNAL_FILTER=internal # routers on this entrypoint → NetBird
EXTERNAL_FILTER=https # routers on this entrypoint → Cloudflare
Your existing Traefik labels stay exactly as-is:
# Matches INTERNAL_FILTER → NetBird only
traefik.http.routers.dashboard.rule: "Host(`dashboard.internal.example.com`)"
traefik.http.routers.dashboard.entrypoints: internal
# Matches EXTERNAL_FILTER → Cloudflare only
traefik.http.routers.api.rule: "Host(`api.example.com`)"
traefik.http.routers.api.entrypoints: https
Force-override per container if needed:
mesh.dns.internal: "false" # exclude from internal pipeline
mesh.routers.admin.managed: "false" # exclude this router from everything
The Rule Parser
Pure-Go regex AST. Handles compound rules:
(Host(`a.example.com`) || Host(`b.example.com`)) && PathPrefix(`/v2`)
Both hostnames extracted for DNS. PathPrefix captured separately for monitor URL construction. HostRegexp intentionally skipped — you can't derive a static DNS record from a dynamic pattern.
Monitoring Label Hierarchy
The mesh.routers.* namespace sits outside Traefik's schema validator. Fallback hierarchy:
mesh.routers.<router_name>.kuma.<property> ← highest priority
mesh.routers.<router_name>.<property>
mesh.kuma.<property>
mesh.<property> ← lowest priority
Real example:
traefik.http.routers.api.rule: "Host(`api.example.com`)"
traefik.http.routers.api.entrypoints: https
mesh.routers.api.kuma.url: "/health"
mesh.routers.api.kuma.accepted_status_codes: "200, 204"
mesh.routers.api.kuma.interval: "30"
mesh.kuma.tags: "backend, prod:green"
mesh.kuma.pages: "public-status:APIs"
Tags use djb2 deterministic hashing — same tag name always maps to the same color across nodes and restarts. Override with hex: prod:#22c55e.
Quick Start
services:
mesh-companion:
image: ghcr.io/wolf-infra/traefik-mesh-companion:stable
container_name: traefik-mesh-companion
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
- SYNC_INTERVAL=1m
- LOG_LEVEL=info
# Internal (NetBird)
- INTERNAL_PROVIDER=netbird
- INTERNAL_FILTER=internal
- INTERNAL_CLEANUP=true
- NETBIRD_API_TOKEN=your_netbird_token
- NETBIRD_TARGET_IP=100.64.0.5
# External (Cloudflare)
- EXTERNAL_PROVIDER=cloudflare
- EXTERNAL_FILTER=https
- EXTERNAL_CLEANUP=true
- CLOUDFLARE_API_TOKEN=your_cf_token
- CLOUDFLARE_TARGET_DOMAIN=your-tunnel-uuid.cfargotunnel.com
# Monitoring (Uptime Kuma)
- MONITOR_PROVIDER=kuma
- KUMA_URL=http://kuma.example.com
- KUMA_USERNAME=admin
- KUMA_PASSWORD=${KUMA_PASS}
- KUMA_AUTO_ENABLE=true
- KUMA_GLOBAL_STATUS_PAGE=home-lab
Use stable — it tracks the latest release. latest tracks main and is explicitly experimental.
Advanced: Distributed Coordinator
Running multiple edge nodes writing to one Uptime Kuma? They face race conditions on status page writes — both read current state, both modify it and last write ends up stomping the other's changes.
The companion ships a built-in Distributed Coordinator. One node is the server. Clients provision monitors locally and forward status page attachment operations to the server for sequential processing.
# Primary node
- KUMA_COORDINATOR_MODE=server
- KUMA_COORDINATOR_PORT=8081
# Other nodes
- KUMA_COORDINATOR_MODE=client
- KUMA_COORDINATOR_URL=http://primary:8081
No external queue. Stateless — clients resend full state on reconnect.
Try It
GitHub: github.com/wolf-infra/traefik-mesh-companion
Full env var reference, label override docs, and Gatus Bridge config are in the README. The core.Processor interface makes adding new DNS or monitoring backends straightforward — PRs welcome.
Additional DNS backends are in development — the core.Processor interface is designed for exactly this. PRs welcome.
This content originally appeared on DEV Community and was authored by Luc Allaire
Luc Allaire | Sciencx (2026-05-08T21:00:00+00:00) Zero-Config DNS and Monitoring for Your Traefik Homelab. Retrieved from https://www.scien.cx/2026/05/08/zero-config-dns-and-monitoring-for-your-traefik-homelab/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.