live: heartbeat sync 2026-10-18T16:47:59-07:00 (Refs #11)

2026-10-18 16:47:59 -07:00
1 parent a550db6027
commit 979e9ef711
@@ -0,0 +1,49 @@
+---
+name: dankclaw-pihole-lan-dns-record
+description: "Add/repair a LAN DNS record for a new *.franksdank.cloud service on Dankclaw's Pi-hole v6 (hosts/custom.list path), plus the public Porkbun A record step and client cache gotchas."
+---
+
+Use when a new `*.franksdank.cloud` service resolves publicly/LAN-needs a local address, on Dankclaw (Pi-hole v6 container, quadlet `pihole.container`).
+
+## Ground truth layout (verified 2026-10-11)
+
+- Quadlet: `~/.config/containers/systemd/pihole.container`; volumes `/home/dank/Containers/pihole/{etc-pihole,etc-dockers,addn-hosts}`.
+- **LAN records live in `/home/dank/Containers/pihole/etc-pihole/hosts/custom.list`** — plain hosts format: `192.168.0.143 gitea.franksdank.cloud`. This is the boring, working path.
+- `pihole.toml` `[[dns.records]]` array is EMPTY on this host — do not expect v6 UI-style records there.
+- `gravity.db` exists but has NO `domain` table (v6 layout) — do not insert local records into SQLite.
+
+## Procedure (30 s, proven)
+
+```bash
+ssh dankclaw 'echo "192.168.0.143 <name>.franksdank.cloud" | sudo tee -a /home/dank/Containers/pihole/etc-pihole/hosts/custom.list >/dev/null \
+ && podman exec pihole pihole restartdns'
+ssh dankclaw 'getent hosts <name>.franksdank.cloud'   # must resolve
+dig +short <name>.franksdank.cloud @192.168.0.143     # from any LAN box
+```
+
+Hosts files are read-only-readable only via sudo (dir owned by uid 100999). `sudo -n` works on dankclaw.
+
+## API maze — DON'T re-explore
+
+- FTL API base is `/api` at the web port (8083) **with `Host: pi.hole` header**; `/admin/api/*` → bad_request hint; bare 127.0.0.1 without the vhost → 404 `not_found`.
+- Login: `POST /api/login {"password": <WEBPASSWORD from /home/dank/Containers/pihole/env>}` → session in `X-Cors` header/cookie.
+- `POST /api/apps/domains/custom` → **404 on this build** (FTL version predates it); `/api/customdns/custom` also absent. There is no container sqlite3. Use custom.list.
+
+## Public record (off-LAN reachability)
+
+Porkbun API, keys in `/home/dank/Containers/caddy/env` (`PORKBUN_API_KEY`, `PORKBUN_API_SECRET_KEY`):
+
+```bash
+curl -sL -X POST https://api.porkbun.com/api/json3/domain/api/create/franksdank.cloud \
+  -H "Content-Type: application/json" \
+  -d "{\"apikey\":\"$K\",\"secretapi\":\"$S\",\"name\":\"<name>\",\"type\":\"A\",\"content\":\"71.227.227.172\",\"ttl\":\"600\"}"
+```
+
+- `json3` path 302-redirects → **`-L` required**; no-`-s` to see status.
+- Porkbun edge (openresty) intermittently 503s — transient; retry later, don't burn turns. Public record is OPTIONAL when LAN-only subscribers exist.
+- Wildcard `*.franksdank.cloud` TLS is already covered: Caddy + Porkbun DNS-01 (caddy-porkbun image), so a new subdomain needs NO new cert work — just the Caddyfile site block + reload.
+
+## Client-side cache gotchas
+
+- Workstation (systemd-resolved): negative cache survives Pi-hole changes; `sudo resolvectl flush-caches` needs a TTY (faillock-sensitive — no `-S` guessing). Non-interactive proof: `curl --resolve <name>.franksdank.cloud:443:192.168.0.143 https://<name>.franksdank.cloud/...`; cache self-expires (SOA negative TTL).
+- Dankclaw/Dankserver resolve via Pi-hole directly — verify there first.