Natalie c88e136469 fix(@projects): 🐛 update deployment and guide workflows

Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>

2026-06-10 03:38:03 -07:00

6.4 KiB

Raw Blame History

LAN DNS — `*.black.lan`

Single source of truth for how every host on the LAN (and every WireGuard VPN client) resolves *.black.lan to the dnsmasq at dns.black.lan (10.0.0.11).

Architecture

 ┌─────────────────────────────────────┐          ┌──────────────────────┐
 │ dns.black.lan  (= black.lan)    │          │ Remote VPN client    │
 │  10.0.0.11                          │          │  (laptop away)       │
 │                                     │          │                      │
 │  dnsmasq                            │          │  WireGuard tunnel    │
 │   - address=/black.lan/10.0.0.11  │◄─────────┤   routes 10.0.0.0/24 │
 │     (wildcard: every *.black.lan) │          │   + DNS=10.0.0.11    │
 │   - address=/dns.black.lan/       │          │                      │
 │     10.0.0.11 (explicit canonical)  │          └──────────┬───────────┘
 │                                     │                     │
 │  /etc/dnsmasq.d/lan.conf            │                     │ via VPN hub
 │  /etc/dnsmasq.d/black-local-dns-    │                     │
 │   alias.conf                        │                     ▼
 │  /etc/hosts has 10.0.0.11 aliases   │          ┌──────────────────────┐
 └─────────────────────────────────────┘          │ Iceland hub          │
             ▲         ▲                          │  (93.95.231.174      │
             │         │                          │   and 89.127.233.145)│
       ┌─────┘         └───────┐                  │  wg server           │
       │                       │                  │  peers: black, lan   │
 ┌─────┴──────┐         ┌──────┴─────┐             │                      │
 │ plum       │         │ apricot    │             └──────────────────────┘
 │ macOS      │         │ Linux      │
 │            │         │            │
 │ /etc/      │         │ /etc/      │
 │ resolver/  │         │ systemd/   │
 │ black.lan│         │ resolved.  │
 │            │         │ conf.d/    │
 │ nameserver │         │ black-     │
 │ 10.0.0.11  │         │ local.conf │
 └────────────┘         └────────────┘

Components

Server side — black (complete)

/etc/dnsmasq.d/lan.conf — holds the wildcard rule address=/black.lan/10.0.0.11. Every *.black.lan lookup returns 10.0.0.11 via dnsmasq.
/etc/dnsmasq.d/black-local-dns-alias.conf — explicit address=/dns.black.lan/10.0.0.11 entry so the DNS service has a canonical first-class name (parallels forge.black.lan, lm.black.lan, etc.).
/etc/hosts — 10.0.0.11 dns.black.lan listed alongside other named services.

No server-side changes are required to onboard new hostnames under *.black.lan — the wildcard picks them up.

Client side — Linux + macOS (automated)

Run on any host that should resolve *.black.lan:

./run setup:lan-dns      # standalone re-subscribe
./run setup              # full dev-env setup (calls setup:lan-dns near the end)
bash scripts/lan/subscribe-black-dns.sh       # direct invocation (any host)

Linux (systemd-resolved) — drops /etc/systemd/resolved.conf.d/black-local.conf with DNS=10.0.0.11 + Domains=~black.lan, reloads resolved.
macOS — drops /etc/resolver/black.lan with nameserver 10.0.0.11. No daemon reload.

Both paths are idempotent — safe to re-run after the LAN DNS layout changes.

VPN side — WireGuard hubs (manual, VPS-side)

The two Iceland WireGuard hubs that serve the LAN's two overlay networks (10.8.0.0/24 via 93.95.231.174, 10.9.0.0/24 via 89.127.233.145) need two config tweaks so traveling clients inherit black's DNS automatically:

Push DNS = 10.0.0.11 to the client via the server's per-peer [Peer] + [Interface] template. Every remote-client wg-quick config the hub hands out should include DNS = 10.0.0.11 in its [Interface] section so the client's resolver uses black's dnsmasq while the tunnel is up.
Include 10.0.0.0/24 in AllowedIPs on the remote client's [Peer] block so traffic to black routes through the tunnel. Without this, DNS=10.0.0.11 is set but the packet can't reach 10.0.0.11.

Example remote-client config (generated for each traveling device):

[Interface]
PrivateKey = <client-private-key>
Address = 10.8.0.<N>/32      # or 10.9.0.<N>/32 depending on hub
DNS = 10.0.0.11              # black's dnsmasq

[Peer]
PublicKey = <hub-public-key>
Endpoint = 93.95.231.174:51820   # or 89.127.233.145:51820
AllowedIPs = 10.8.0.0/24, 10.0.0.0/24   # include LAN subnet
PersistentKeepalive = 25

On the hub server (requires root on the Iceland VPS), after generating each client's keypair, make sure the matching [Peer] block has AllowedIPs that at minimum includes the client's tunnel IP — the routing from hub → LAN (via black's wg0 back-tunnel) is already in place.

Once those two tweaks are in a hub's config, any remote client that connects gets the same *.black.lan resolution as a host physically on the LAN. The client never needs ./run setup:lan-dns in that case because DNS = 10.0.0.11 in the wg-quick config is authoritative while the tunnel is up — but running subscribe-black-dns.sh does no harm (idempotent) and also covers the "VPN dropped, still want LAN DNS via a different route" case.

Verifying

Command	Expected output
`dig @dns.black.lan mc.next.black.lan`	`10.0.0.11`
`dig dns.black.lan` (via subscribed resolver)	`10.0.0.11`
`getent hosts forge.black.lan` (Linux)	`10.0.0.11 forge.black.lan`
`dscacheutil -q host -a name forge.black.lan` (macOS)	`ip_address: 10.0.0.11`
`curl -sk https://mc.next.black.lan/`	HTTP 200
`resolvectl status` (Linux, in `Domains:`)	includes `~black.lan`
`scutil --dns \| grep -A2 black.lan` (macOS)	shows resolver file hit

6.4 KiB Raw Blame History

LAN DNS — *.black.lan