maxamill/dnsweaver repository overview

⁠dnsweaver

Automatic DNS records for containers, VMs & clusters.

dnsweaver reads hostnames from seven sources and writes records to eleven DNS providers. A container starts with a Traefik label or a Proxmox VM boots, and the record appears; when they go away, so does it. Think of it as external-dns for the homelab.

📚 Documentation⁠ · 🐙 GitHub⁠ · 🔖 Releases⁠

⁠Why dnsweaver?

• Proxmox VE auto-DNS — A records for VMs and LXCs from the PVE API. Almost nothing else does this.
• Self-hosted DNS, first-class — Technitium, Pi-hole, AdGuard Home, dnsmasq, OPNsense, and pfSense.
• Seven sources — Traefik, Caddy, nginx-proxy, native labels, Kubernetes, Proxmox VE, and Incus in one binary. Run one or all at once.
• Split-horizon — Internal and external records from the same labels (e.g. Technitium internally, Cloudflare externally).
• Single static Go binary — ~15 MB, multi-arch (amd64/arm64), zero runtime dependencies.

⁠Supported Sources

Enable any combination with DNSWEAVER_SOURCES.

⁠Supported Providers

⁠Tags

• latest — latest stable release
• vX.Y.Z — specific release (recommended for production)

Multi-arch images are published for linux/amd64 and linux/arm64.

Also available on GitHub Container Registry: ghcr.io/maxfield-allison/dnsweaver.

⁠Quick Start

services:
  dnsweaver:
    image: maxamill/dnsweaver:latest
    restart: unless-stopped
    environment:
      - DNSWEAVER_INSTANCES=internal-dns
      - DNSWEAVER_INTERNAL_DNS_TYPE=technitium
      - DNSWEAVER_INTERNAL_DNS_URL=http://dns.internal:5380
      - DNSWEAVER_INTERNAL_DNS_TOKEN_FILE=/run/secrets/technitium_token
      - DNSWEAVER_INTERNAL_DNS_ZONE=home.example.com
      - DNSWEAVER_INTERNAL_DNS_RECORD_TYPE=A
      - DNSWEAVER_INTERNAL_DNS_TARGET=192.0.2.100
      - DNSWEAVER_INTERNAL_DNS_DOMAINS=*.home.example.com
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    secrets:
      - technitium_token

secrets:
  technitium_token:
    external: true

A container carrying this label gets an A record created automatically:

labels:
  - "traefik.http.routers.myapp.rule=Host(`myapp.home.example.com`)"

When the container stops, the record is removed.

See the Getting Started guide⁠ for the full walkthrough, Kubernetes and Proxmox setup, and provider-specific configuration.

⁠License

MIT⁠ · Maintained by Maxfield Allison⁠