Quick Start

Get DomU DNS running on a Raspberry Pi 3B in under 5 minutes. No database setup, no Docker required.

Prerequisites

Raspberry Pi 3B (or newer) with Debian Bookworm/Raspbian
Go 1.24+ on your build machine (for compiling)
SSH access to the Raspberry Pi
Port 53 not occupied (stop systemd-resolved if needed)

No database required. DomU DNS stores all data as JSON files under /var/lib/domudns/data/. No PostgreSQL, SQLite, or Redis setup needed.

Step 1: Clone & Build

On your local machine (not the Pi), clone the repository and cross-compile for ARMv7:

bash
git clone https://github.com/mw7101/domudns.git
cd domudns

# Cross-compile for Raspberry Pi 3B (ARMv7)
make build-arm

# Binary is at: build/domudns-arm

Step 2: Install on Pi

bash
# Create directories on the Pi
ssh pi@<PI_IP> "sudo mkdir -p /etc/domudns /var/lib/domudns/data /usr/local/bin"

# Copy binary
scp build/domudns-arm pi@<PI_IP>:/tmp/domudns
ssh pi@<PI_IP> "sudo mv /tmp/domudns /usr/local/bin/domudns && sudo chmod +x /usr/local/bin/domudns"

Step 3: Minimal Configuration

Create /etc/domudns/config.yaml on the Pi:

yaml
cluster:
  role: "master"           # standalone = master without slaves
  data_dir: "/var/lib/domudns/data"

dnsserver:
  listen: "[::]:53"
  upstream:
    - "9.9.9.9"            # Quad9 (privacy-focused)
    - "149.112.112.112"

http:
  listen: ":80"

system:
  log_level: "info"

Note: Port 53 requires root privileges. If systemd-resolved is running, stop it first: sudo systemctl disable --now systemd-resolved

Step 4: Systemd Service

bash
# Copy service file (from repo)
scp scripts/domudns.service pi@<PI_IP>:/tmp/

ssh pi@<PI_IP> "
  sudo mv /tmp/domudns.service /etc/systemd/system/
  sudo systemctl daemon-reload
  sudo systemctl enable --now domudns
"

# Check status
ssh pi@<PI_IP> "sudo systemctl status domudns"

Step 5: First-Time Setup

Open the dashboard in your browser:

text
http://<PI_IP>/setup

The setup wizard will guide you through:

Setting admin username and password
Generating a secure API key
Configuring blocklist sources
Adding your local DNS zones

Verify DNS is Working

bash
# Test basic resolution
dig @<PI_IP> google.com

# Test blocklist (should return NXDOMAIN or 0.0.0.0)
dig @<PI_IP> ads.doubleclick.net

# Health check
curl http://<PI_IP>/api/health

Set as Network DNS

Configure your router to use the Pi's IP address as the primary DNS server. Most home routers have this setting under DHCP / LAN settings.

Next Configuration →