Skip to content

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.

Key Features

  • Multi-Provider Support

    Route different domains to different DNS providers. Technitium, Cloudflare, Pi-hole, dnsmasq, and webhook—all at once.

    Providers

  • Split-Horizon DNS

    Create internal and external records from the same container labels automatically. One label, multiple zones.

    Split-Horizon Guide

  • Docker & Swarm Native

    Works with standalone Docker and Docker Swarm clusters. Socket proxy compatible for enhanced security.

    Docker Sources

  • Observable

    Prometheus metrics, health endpoints, and structured logging built-in. Know what's happening.

    Observability

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`)" # (1)!
    1. dnsweaver extracts hostnames from Traefik, Caddy, and native labels

  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

Quick Start

Minimal Docker Compose

services:
  dnsweaver:
    image: maxamill/dnsweaver:latest
    environment:
      - DNSWEAVER_INSTANCES=internal-dns # (1)!
      - DNSWEAVER_INTERNAL_DNS_TYPE=technitium # (2)!
      - 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 # (3)!
      - DNSWEAVER_INTERNAL_DNS_DOMAINS=*.home.example.com # (4)!
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    secrets:
      - technitium_token
  1. Comma-separated list of provider instance names
  2. Provider type: technitium, cloudflare, pihole, dnsmasq, or webhook
  3. Target IP for A records (or CNAME target hostname)
  4. Domain patterns to match—wildcards supported

Getting Started Configuration

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 A, AAAA, CNAME, TXT Custom integrations

Next Steps