dnsweaver

Automatic DNS record management for Docker containers with multi-provider support.

dnsweaver watches Docker events and automatically creates and deletes DNS records for services with reverse proxy labels (Traefik, etc.). Unlike single-provider tools, dnsweaver supports split-horizon DNS and multiple DNS providers simultaneously.

📚 Full Documentation

Features

• 🔀 Multi-Provider Support — Route different domains to different DNS providers
• 🌐 Split-Horizon DNS — Internal and external records from the same container labels
• 🐳 Docker & Swarm Native — Works with standalone Docker and Docker Swarm clusters
• 🔒 Socket Proxy Compatible — Connect via TCP to a Docker socket proxy for improved security
• 🏷️ Traefik Integration — Parses traefik.http.routers.*.rule labels to extract hostnames
• 📊 Observable — Prometheus metrics, health endpoints, structured logging
• 🔑 Secrets Support — Docker secrets compatible via _FILE suffix variables

Supported Providers

Provider	Record Types	Notes
Technitium	A, AAAA, CNAME, SRV, TXT	Full-featured self-hosted DNS
Cloudflare	A, AAAA, CNAME, TXT	With optional proxy support
Pi-hole	A, AAAA, CNAME	API or file mode
dnsmasq	A, AAAA, CNAME	File-based configuration
Webhook	Any	Custom integrations

Quick Start

Installation

# Docker Hub
docker pull maxamill/dnsweaver:latest

# GitHub Container Registry
docker pull ghcr.io/maxfield-allison/dnsweaver:latest

Basic Example

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=10.0.0.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

How It Works

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Docker Events  │────▶│  dnsweaver   │────▶│  DNS Providers  │
│  (start/stop)   │     │  (matching)  │     │  (A/CNAME/SRV)  │
└─────────────────┘     └──────────────┘     └─────────────────┘

1. A container starts with a Traefik label:

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

2. dnsweaver extracts the hostname and matches it against configured provider domain patterns

3. The matching provider creates the DNS record:

   • A record: myapp.home.example.com → 10.0.0.100
   • CNAME: myapp.example.com → proxy.example.com

4. When the container stops, the DNS record is automatically cleaned up

Documentation

Topic	Description
Getting Started	Installation and first configuration
Configuration	Environment variables reference
Providers	Provider-specific setup guides
Split-Horizon DNS	Internal + external records
Docker Swarm	Swarm deployment guide
Observability	Metrics, logging, and health checks
FAQ	Common questions and troubleshooting

Split-Horizon DNS Example

Manage internal and external DNS from the same container labels:

environment:
  - DNSWEAVER_INSTANCES=internal,external

  # Internal: Technitium → private IP
  - DNSWEAVER_INTERNAL_TYPE=technitium
  - DNSWEAVER_INTERNAL_RECORD_TYPE=A
  - DNSWEAVER_INTERNAL_TARGET=10.0.0.100
  - DNSWEAVER_INTERNAL_DOMAINS=*.example.com

  # External: Cloudflare → tunnel CNAME
  - DNSWEAVER_EXTERNAL_TYPE=cloudflare
  - DNSWEAVER_EXTERNAL_RECORD_TYPE=CNAME
  - DNSWEAVER_EXTERNAL_TARGET=tunnel.example.com
  - DNSWEAVER_EXTERNAL_DOMAINS=*.example.com

With this configuration, when app.example.com starts:

• Internal DNS → A record → 10.0.0.100
• External DNS → CNAME record → tunnel.example.com

Contributing

Contributions are welcome! See CONTRIBUTING for guidelines.

License

MIT License