DNS in one picture

Raspberry Pi with Docker Compose · the recommended home setup, about 10 minutes

1. Prepare the Pi. Raspberry Pi OS (64-bit recommended) on a Pi 3, 4, 5, or Zero 2 W, with a fixed address (set a DHCP reservation in your router), and Docker:

   curl -fsSL https://get.docker.com | sh
   sudo usermod -aG docker $USER    # log out and back in

2. Free port 53. If Pi-hole or another DNS server runs on the Pi, stop it. Check: sudo ss -ulpn 'sport = :53' should print nothing.
3. Download the bundle and start it.

   mkdir ~/telltale && cd ~/telltale
   curl -fsSLO https://raw.githubusercontent.com/paimonsoror/telltaledns/main/deploy/compose/compose.yaml
   curl -fsSLO https://raw.githubusercontent.com/paimonsoror/telltaledns/main/deploy/compose/telltale.toml
   docker compose up -d
   docker compose ps        # STATUS shows "healthy" within a minute

4. Test it from another computer (replace the address with your Pi's):

   dig @192.168.1.2 example.com          # an address: it resolves
   dig @192.168.1.2 doubleclick.net      # 0.0.0.0 or NXDOMAIN: the blocklist works

   On Windows: nslookup example.com 192.168.1.2.
5. Create the admin account. Print the one-time setup token and open the UI at http://<pi>:8053/:

   docker compose exec telltale telltale auth setup-token

Updating: docker compose pull && docker compose up -d. Editing the config: change telltale.toml, then docker compose kill -s HUP applies it without dropping a query. On an SD card, the starter config keeps the query log for 7 days; a USB SSD is better for longer history.

Raspberry Pi or Linux, native (systemd)

No Docker: a single static binary as a sandboxed systemd service, on any systemd distribution (x86-64, arm64, or 32-bit ARM). The installer checks the release's signature and checksum before installing anything, so read it, then run it:

curl -fsSLO https://raw.githubusercontent.com/paimonsoror/telltaledns/main/deploy/systemd/install.sh
less install.sh
sudo sh install.sh                 # the latest release; --edge: builds from main
sudo -u telltale telltale auth setup-token -c /etc/telltale/telltale.toml

• It asks first: press Enter for the recommended settings, or walk me through the options to pick upstreams (encrypted presets or your own server), starting blocklists (or none), the listen address, the first admin (a setup token, or a password now), and the query log's retention and privacy. Every step shows its default; Enter keeps it. Piped or automated runs (and --yes) ask nothing.
• It creates a telltale user, writes the config to /etc/telltale/telltale.toml (never overwriting yours), and keeps data in /var/lib/telltale.
• If systemd-resolved holds port 53 (Ubuntu, some Debian setups), it offers to turn the stub listener off (--disable-resolved-stub does it without asking).
• Updates: sudo telltale self-update --restart (add --channel edge if you installed with --edge). The previous binary is kept as telltale.old.
• Logs: journalctl -u telltale -f. Reload after editing the config: sudo systemctl reload telltale.
• Uninstall: sudo sh install.sh --uninstall. It removes the service and binary, offers to give the machine its own resolver back (systemd-resolved, as it was before), and keeps your config and data unless you ask it to delete them (--purge).

Docker

docker run -d --name telltale --read-only --cap-drop ALL \
  -p 53:53/udp -p 53:53/tcp -p 8053:8053 -p 9153:9153 \
  -v "$PWD/telltale.toml:/etc/telltale/telltale.toml:ro" \
  -v telltale-data:/var/lib/telltale \
  ghcr.io/paimonsoror/telltale:latest
docker exec telltale telltale auth setup-token

amd64, arm64, and arm/v7; about 13 MiB compressed, web UI included; runs as a non-root user. Published ports can hide each device's own address behind Docker's (the UI warns if they do): on a home network, --network host (or the Pi Compose bundle) makes sure each device shows up as itself. A starter config is in step 2.

Kubernetes with Helm

helm install telltale oci://ghcr.io/paimonsoror/charts/telltale \
  -n telltale --create-namespace \
  --set service.dns.annotations."metallb\.universe\.tf/loadBalancerIPs"=192.168.1.53
kubectl -n telltale get svc telltale-dns     # EXTERNAL-IP: your DNS server address
kubectl -n telltale exec telltale-0 -- /usr/local/bin/telltale auth setup-token \
  -c /etc/telltale/00-chart.toml -c /etc/telltale/10-values.toml

• Every option: helm show values oci://ghcr.io/paimonsoror/charts/telltale > values.yaml prints the chart's commented values file; the Helm values reference lists each key with its default and meaning. Keep what you change in your own file and pass it with -f.
• Chart versions: without --version, Helm installs the newest stable release (chart and image versions match). Builds from main publish X.Y.Z-edge.N charts with the :edge image: add --devel for the newest, or pin one with --version.
• Keep externalTrafficPolicy: Local (the default): with Cluster, every query looks like it came from a node, and TelltaleDNS shows a "client IPs appear masked" banner.
• Your settings go in config: (TOML, the same keys as the configuration reference); secrets come from existing Secrets.
• Encrypted DNS for phones: encrypted.dot.enabled / encrypted.doh.enabled with a cert-manager certificate.
• Monitoring: serviceMonitor.enabled, prometheusRule.enabled, grafanaDashboard.enabled.
• More pods: mode: scaled adds resolver pods beside the controller (below).

From source

git clone https://github.com/paimonsoror/telltaledns
cd telltaledns
cargo build --release
sudo ./target/release/telltale run -c telltale.toml   # a config from step 2
dig @127.0.0.1 example.com

Needs a recent Rust toolchain (the repository pins it). The first start creates a one-time setup token; telltale auth setup-token prints it. Open the web UI on port 8053 and use it to create your admin.