Install with Docker
The image is ghcr.io/operomtl/opdns-node, for linux/amd64 and
linux/arm64. It contains the static node binary and Alpine’s Unbound,
which the node starts and supervises. It runs as an unprivileged user that
may bind port 53. Data lives in the volume at /var/lib/opdns.
Tags: each release is tagged with its version (v1.2.3, never moved);
v1.2 and v1 follow the newest release of that line, and latest the
newest stable release (pre-releases such as v1.3.0-rc1 move none of
them). Pin a version, or a digest, for anything you care about.
The linux/amd64 image is about 35 MB compressed (86 MB unpacked).
Free port 53
Section titled “Free port 53”On many Linux distributions systemd-resolved listens on
127.0.0.53:53, which conflicts with publishing port 53 on all addresses.
Either publish on the LAN address only (-p 192.168.1.10:53:53/udp), or
turn off its stub listener:
[Resolve]DNSStubListener=nothen sudo systemctl restart systemd-resolved.
If port 53 is still taken, the node refuses to start and its log names the
program holding the port when it can see it (a binary install, or a
container on the host network), for example
dnsmasq (pid 733) holds port 53/tcp, with the fix for that program:
port=0 in dnsmasq’s configuration keeps its DHCP and drops its DNS;
another Pi-hole or DNS server must be stopped or moved to another address.
sudo ss -lunpt 'sport = :53' shows the same on the host.
Run it
Section titled “Run it”The dashboard’s Nodes → Add a node dialog shows this command with your enrolment code filled in (see Enrol a node):
docker run -d --name opdns-node --restart unless-stopped --read-only \ -p 53:53/udp -p 53:53/tcp \ -p 127.0.0.1:8053:8053 \ -v opdns-node:/var/lib/opdns \ -e OPDNS_ENROL_TOKEN=<enrolment-code> \ ghcr.io/operomtl/opdns-node:<version>Save this as compose.yaml in an empty directory. It runs as is, with
host networking (why):
# opdns-node with Docker Compose, host networking: the recommended way to# run the self-hosted node in a container.## OPDNS_NODE_TAG=<version> OPDNS_ENROL_TOKEN=<code> docker compose up -d## Port 53 must be free on the host: turn off systemd-resolved's stub# listener first (DNSStubListener=no) if it holds 127.0.0.53:53.services: opdns-node: # Pin a release (vX.Y.Z, or vX.Y for its patches) for anything you care # about; set OPDNS_NODE_TAG in .env. `latest` is the newest stable one. image: ghcr.io/operomtl/opdns-node:${OPDNS_NODE_TAG:-latest} restart: unless-stopped network_mode: host read_only: true # The binary binds port 53 through its file capability: keep # NET_BIND_SERVICE, drop the rest. no-new-privileges would disable that # file capability, so it is not set. cap_drop: [ALL] cap_add: [NET_BIND_SERVICE] volumes: - opdns-node:/var/lib/opdns environment: # Used once, on first start; the identity is then in the volume. OPDNS_ENROL_TOKEN: ${OPDNS_ENROL_TOKEN:-} # The status page on the host's loopback only (the image's default, # 0.0.0.0:8053, would put it on the LAN with host networking). OPDNS_PAGE_ADDR: 127.0.0.1:8053 # Shown on the status page and in /api/status (versions.image). OPDNS_IMAGE: ghcr.io/operomtl/opdns-node:${OPDNS_NODE_TAG:-latest}volumes: opdns-node:Then, in the same directory:
OPDNS_NODE_TAG=<version> OPDNS_ENROL_TOKEN=<enrolment-code> docker compose up -dHost, bridge or macvlan networking
Section titled “Host, bridge or macvlan networking”The node needs each client’s real source address: it names devices by it, records it in the query log, and its open-resolver guard answers only LAN sources.
- Host networking (
network_mode: host,docker run --network host) is the recommended mode: the node sees every source address, IPv4 and IPv6, and its own interfaces (the IPv6 egress check needs them). Port 53 must be free on the host. With host networking, setOPDNS_PAGE_ADDR=127.0.0.1:8053(as the Compose file does) or the status page is on the LAN. - Bridge networking with published ports (
-p 53:53/udp, the dashboard’sdocker runline) keeps the source address only while Docker forwards with iptables DNAT (rootful Docker on Linux, IPv4). Where Docker’s userland proxy forwards instead (IPv6 withoutip6tables, rootless Docker or Podman, Docker Desktop on macOS and Windows), every query arrives from the bridge gateway (172.17.0.1): every device is one client, the query log shows that address, and the guard admits everything, because that gateway is a private address. Query the node from a LAN device and look at the client address of that query in the dashboard’s query log: if it is the gateway, switch to host networking. - macvlan gives the container its own address on the LAN, so it sees source addresses like host networking while port 53 on the host stays with another program (systemd-resolved, or a Pi-hole you are replacing). Use the Compose file below. The host itself cannot reach a macvlan container over that interface.
For macvlan, save this as compose.macvlan.yaml and set the parent
interface, subnet, gateway and the node’s address for your network:
# opdns-node with Docker Compose on a macvlan network: the node gets its# own address on the LAN, so it sees every client's real source address# and port 53 on the host can stay with another program.## OPDNS_ENROL_TOKEN=<code> OPDNS_LAN_IF=eth0 OPDNS_LAN_SUBNET=192.168.1.0/24 \# OPDNS_LAN_GATEWAY=192.168.1.1 OPDNS_NODE_ADDR=192.168.1.53 \# docker compose -f compose.macvlan.yaml up -d## Pick OPDNS_NODE_ADDR outside the router's DHCP pool, and point the# router's DHCP DNS server at it. A macvlan container cannot talk to its own# host over that interface (a kernel rule): the host itself resolves through# something else, or through a macvlan sub-interface on the host. The# status page listens on the node's address (port 8053), open to the LAN# sources its allowlist admits: set a page password.services: opdns-node: image: ghcr.io/operomtl/opdns-node:${OPDNS_NODE_TAG:-latest} restart: unless-stopped read_only: true cap_drop: [ALL] cap_add: [NET_BIND_SERVICE] networks: lan: ipv4_address: ${OPDNS_NODE_ADDR:-192.168.1.53} volumes: - opdns-node:/var/lib/opdns environment: OPDNS_ENROL_TOKEN: ${OPDNS_ENROL_TOKEN:-} OPDNS_IMAGE: ghcr.io/operomtl/opdns-node:${OPDNS_NODE_TAG:-latest}networks: lan: driver: macvlan driver_opts: parent: ${OPDNS_LAN_IF:-eth0} ipam: config: - subnet: ${OPDNS_LAN_SUBNET:-192.168.1.0/24} gateway: ${OPDNS_LAN_GATEWAY:-192.168.1.1}volumes: opdns-node:With macvlan the status page is on the LAN: set a page password.
OPDNS_IMAGE is shown on the status page and in /api/status
(versions.image): set it to the image you run, ideally with its digest
(ghcr.io/operomtl/opdns-node:v1.2.3@sha256:…), since a container cannot
read its own image digest.
The node installs a list artifact only if its Ed25519 signature verifies.
You do not need to configure the key: by default
(lists.trust_cloud_key: true) an enrolled node learns it from the cloud
on every profile pull and keeps it in lists_keys.json in the volume, so
it can verify lists after a restart without the internet. To pin keys
yourself instead, set OPDNS_LISTS_PUBLIC_KEYS and
OPDNS_LISTS_TRUST_CLOUD_KEY=false
(list signing keys).
OPDNS_ENROL_TOKEN is used once, on first start; after that the node’s
identity is in the volume and the variable is ignored. It is safe to leave
in the Compose file, but the code is single-use and expires after 15
minutes anyway.
A container started with neither an enrolment code, an existing identity
in its volume, nor a standalone profile does not serve DNS: it prints
how to enrol and exits with status 2. With --restart unless-stopped it
keeps restarting and printing the same message until you add the code.
Check it
Section titled “Check it”docker logs opdns-nodeshows the enrolment and “loaded” lines.docker exec opdns-node opdns-node statusprints mode, node id, profile, link state and versions.- Open
http://127.0.0.1:8053/on the host for the status page. dig @<host-address> example.comanswers.- The dashboard’s Nodes page shows the node online.
The image has a health check on /healthz; docker ps shows it as
healthy once Unbound answers and a profile and lists are loaded.
Point your network at it
Section titled “Point your network at it”Set your router’s DHCP DNS server (option 6, and IPv6 RDNSS if you use IPv6) to the node’s LAN address. Queries from every device then go to the node.
Encrypted DNS on the node
Section titled “Encrypted DNS on the node”The node listens for plain DNS by default. For DNS-over-TLS, DoH, DoQ or DoH3 on your LAN, give it a certificate for a name your devices use and set the listeners, for example:
ports: - "853:853/tcp" - "443:443/tcp" volumes: - opdns-node:/var/lib/opdns - /etc/letsencrypt/live/dns.home.example:/certs:ro environment: OPDNS_LISTEN_DOT: ":853" OPDNS_LISTEN_DOH: ":443" OPDNS_LISTEN_TLS_CERT: /certs/fullchain.pem OPDNS_LISTEN_TLS_KEY: /certs/privkey.pem OPDNS_LISTEN_DNS_DOMAIN: dns.home.exampleRenewal needs no restart. The node checks the certificate and key files
every second and loads a new pair as soon as it changes; a pair that fails
to load is logged and the previous certificate stays in use. Connections
already open keep the certificate they started with. docker kill -s HUP opdns-node forces a reload (and a fresh profile and list pull, and
applies the reloadable configuration keys). The log
says certificate reloaded with the new expiry date.
Every key is on the configuration reference.