cd ..
relayd(1) Mizuchi Labs Manual relayd(1)

NAME

Ditching DNS Duct Tape

DATE

│ 3 min read

TAGS

#docker #swarm #devops #golang #traefik #selfhosted

If you run Docker Swarm and use Traefik as your ingress controller, you already know the pain.

Routing traffic inside the cluster is a breeze. But making sure your external DNS providers (like Cloudflare, Hetzner, or even your local Pi-hole) actually point to the right nodes? That is usually a nightmare of duct-tape cron jobs, messy API scripts, or heavy enterprise tools that consume way too much memory.

I got tired of manually syncing my DNS records every time I spun up a new container or changed a Traefik routing label. So, I built a tool to fix it.

So, I built relayd

relayd is a lightweight DNS update daemon specifically built for Docker and Docker Swarm.

Instead of requiring you to maintain a separate configuration file of domains and IPs, relayd just listens to your Docker daemon. It reads the labels you are already putting on your containers for Traefik, figures out what domain needs to point where, and pushes the update to your DNS provider automatically.

Why I built it this way

Honestly, the manual DNS management was just bothering me. Managing records across my home lab and multiple Proxmox environments became a tedious chore every time I moved a service around. I wanted a simple tool that just handled this one specific task without the overhead of a massive orchestration platform.

  • Powered by libdns: Instead of writing janky, isolated API calls for every single DNS provider, I used the libdns interfaces. This means relayd natively supports a huge list of providers right out of the box without reinventing the wheel.
  • Written in Go: I write pretty much everything in Go these days. It makes it easy to ship as a single compiled binary and keeps deployments completely self-contained.

Currently, it supports:

  • AWS Route53
  • Cloudflare
  • DigitalOcean
  • Hetzner
  • Linode
  • Namecheap
  • Pi-hole
  • PowerDNS
  • RFC2136
  • Technitium (via rfc2136)
  • Scaleway
  • UniFi

How it works

It’s completely hands-off once it’s running. You just pass it your provider credentials via environment variables, mount the Docker socket so it can listen for events, and let it do its thing.

Here is a quick example of how you can configure a service to be picked up by relayd:

services:
  whoami:
    image: traefik/whoami
    labels:
      - relayd.enable=true
      # You define the domains you want to update here
      - relayd.hosts=whoami.example.com
      # Or if you're using traefik it will use the Traefik labels
      - traefik.enable=true
      - traefik.http.routers.whoami.rule=Host(`whoami.example.com`)

If you spin up this container, relayd sees it, checks your current DNS records, and creates or updates the A or AAAA records as needed. When the container goes down, it cleans up after itself.

No more manual DNS portal logins. No more stale records pointing to dead nodes.

If you’re managing a Swarm cluster and want to reclaim your sanity, give it a spin. The setup instructions and full Docker Compose examples are all in the repository.

Since it’s built on libdns, adding new providers is pretty straightforward. If your DNS provider isn’t on the list yet, issues and PRs are always welcome!

Check it out on GitHub →