AdGuard Home without the setup wizard, in one OpenTofu-style config

[jamesconwaydev]

Hi all. I built an AdGuard Home circuit for Conn3x, a fork of OpenTofu that configures servers over SSH: https://github.com/conn3xorg/circuit-adguardhome. If you already create your VMs with OpenTofu or Terraform, the same conn3x apply now sets AdGuard Home up on them, no setup wizard involved.

module "adguardhome" {
  source = "github.com/conn3xorg/circuit-adguardhome?ref=v0.1.0"

  hosts                = { dns = "192.168.1.2" }
  ssh_private_key_file = "~/.ssh/id_ed25519"

  admin_password = var.adguard_password

  rewrites = {
    "nas.home.arpa"     = "192.168.1.20"
    "printer.home.arpa" = "192.168.1.21"
  }
}

It installs v0.107.79 from your release tarball, checks it against checksums.txt, and runs it under systemd as its own user with only CAP_NET_BIND_SERVICE and --no-check-update. The admin password is hashed with bcrypt on the host, so the plaintext never reaches Conn3x's state or plan. By default it answers loopback and private ranges only, so it can't end up an open resolver, and on Ubuntu and Debian it moves systemd-resolved's stub out of the way.

The interesting part was that AdGuard Home rewrites AdGuardHome.yaml as it runs, which would make every plan show a change. So the circuit keeps the settings it owns in a separate file, and only when that changes does it build a new config, check it with --check-config, and swap it in. The cost, which the README spells out: settings changed in the web UI go back to their defaults the next time an input changes. If there's a better way to own part of the config, I'd love to hear it.

CI applies it on Rocky Linux 10, Fedora 45, Ubuntu 24.04 and Debian 13, then checks that doubleclick.net is blocked, example.com resolves, a rewrite answers, and /control/status takes the right password and refuses a wrong one. By hand it ran on Ubuntu 24.04 and Rocky Linux 10 droplets through a reboot.

Questions and "you're doing it wrong" both welcome.