darman/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: condense comments across the repo

Browse Source 
Comments had drifted into multi-paragraph narrative (git commit
lineage, debugging stories, restated code) in several hot spots
(scripts/deploy, hermes-agent.nix, flake.nix, gitea.nix, headscale.nix).
Trim every comment to its load-bearing "why" — gotchas, safety
warnings, and non-obvious rationale survive verbatim in substance,
just tightened to 1-2 sentences; historical narrative and anything
already covered in CLAUDE.md is cut. No code/logic changed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UJqEmY1y3AYX3JoX4Y6b21
This commit is contained in:
darman
2026-09-18 21:36:30 +02:00
co-authored by Claude Sonnet 5
parent 3899290c5b
commit 6f24ab69ad
47 changed files with 1051 additions and 1965 deletions
Download Patch File Download Diff File Expand all files Collapse all files
services/vpn/headscale.nix
+39 -77
View File
@@ -1,14 +1,10 @@
{ config, ... }:
# Headscale — self-hosted control server for the tailnet. Every host's
# services/vpn/tailscale.nix points --login-server at https://vpn.mgaction.town
# (this host). MagicDNS base_domain "orbit.sol" matches the
# "jupiter.orbit.sol" names used in this repo's Caddy vhosts
# (hosts/neptun/configuration.nix) — changing base_domain means changing
# those too, and re-pointing neptun's dnsmasq stub at the new suffix.
#
# TLS terminates at Caddy (see the host's configuration.nix); headscale
# itself only listens on localhost.
# Headscale — self-hosted control server for the tailnet; every host's
# services/vpn/tailscale.nix points --login-server at https://vpn.mgaction.town.
# TLS terminates at Caddy; headscale itself only listens on localhost. Changing
# base_domain below also means updating this repo's Caddy vhosts and neptun's
# dnsmasq stub, which assume "orbit.sol".
{
services.headscale = {
enable = true;
@@ -18,89 +14,55 @@
server_url = "https://vpn.mgaction.town";
dns = {
# Deliberately OUTSIDE mgaction.town. That zone has a wildcard A+AAAA
# pointing at neptun, and DNS wildcards match multi-label names — so
# with base_domain = hosts.mgaction.town, `jupiter.hosts.mgaction.town`
# resolved publicly to NEPTUN and Caddy proxied to itself: a silent
# loop rather than a lookup failure.
#
# `.sol` is the LAN domain pihole serves, so this nests the tailnet
# inside it: planets sit on the LAN as jupiter.sol, and reach each
# other in orbit as jupiter.orbit.sol. Resolution is unambiguous
# because tailscale matches routes by LONGEST suffix, so orbit.sol
# goes to MagicDNS even when everything else funnels to pihole.
#
# Never give a LAN host the name `orbit`: pihole's
# `address=/<host>.sol/<ip>` lines match a name AND everything under
# it, so an `orbit` host would swallow this entire zone.
# Deliberately outside mgaction.town: that zone has a wildcard A+AAAA at
# neptun, so a name under it would resolve publicly to neptun and Caddy
# would proxy to itself. Nested under `.sol` (pihole's LAN domain) so
# jupiter.sol (LAN) and jupiter.orbit.sol (tailnet) resolve unambiguously
# — tailscale matches by longest suffix. Never name a LAN host `orbit`:
# pihole's `address=/<host>.sol/<ip>` would swallow this whole zone.
base_domain = "orbit.sol";
# pihole on mercury, over the tailnet — so every roaming device gets
# ad blocking and .sol names wherever it is, not just on the LAN.
# Deliberately NO public fallback: tailscale treats the list as a set,
# so adding 9.9.9.9 here would let queries slip past the filter
# whenever mercury is briefly slow. Strict blocking, at the cost of
# mercury being a single point of failure for tailnet DNS.
#
# ⚠️ A hardcoded tailnet address, so it changes if mercury re-enrols
# — check `headscale nodes list` if DNS dies tailnet-wide.
# pihole on mercury, over the tailnet, so roaming devices get ad blocking
# and .sol names everywhere. Deliberately no public fallback — tailscale
# treats this as a set, so adding one would let queries slip past the
# filter whenever mercury is briefly slow, at the cost of mercury being a
# single point of failure for tailnet DNS.
# ⚠️ Hardcoded tailnet address — check `headscale nodes list` if it
# changes (mercury re-enrolled) and DNS dies tailnet-wide.
nameservers.global = [ "100.64.0.7" ];
# Must be set, and must be HERE rather than via the module's
# `dns.split` option. nixpkgs renders that option one level too high
# (a sibling of `nameservers:`), but headscale reads
# dns.nameservers.split (hscontrol/types/config.go:722) and so does
# headplane. So the module's option is dead, and the missing key makes
# headplane's DNS page die with
# TypeError: Cannot convert undefined or null to object
# from Object.keys(config.dns.nameservers.split).
# Must be set here, not via the module's `dns.split` option — nixpkgs
# renders that one level too high, but headscale (and headplane) read
# dns.nameservers.split; the missing key crashes headplane's DNS page.
nameservers.split = { };
# Point every node's resolver at MagicDNS, which forwards on to the
# global nameserver above. That is the only way to get pihole onto a
# roaming device: with this false, globalResolvers land in the
# netmap's FallbackResolvers (hscontrol/types/config.go:826-830) and a
# phone with carrier DNS never consults them.
#
# The cost is that every node's DNS now depends on mercury and on the
# home connection, so mercury going down costs name resolution
# everywhere, not just `.sol`. neptun and mercury opt out of this
# individually with --accept-dns=false — see their configuration.nix.
# Routes every node's resolver through MagicDNS to the global nameserver
# above — the only way pihole reaches a roaming device (otherwise it
# lands in netmap's FallbackResolvers and carrier DNS never consults it).
# Cost: all DNS now depends on mercury and the home connection; neptun
# and mercury opt out individually with --accept-dns=false.
override_local_dns = true;
};
# Authentik as the login provider, so `tailscale up --login-server ...`
# sends you to a browser instead of needing a pre-auth key. This is a
# SEPARATE Authentik application from headplane's — its own provider,
# slug `headscale`, redirect https://vpn.mgaction.town/oidc/callback
# (headscale's own callback; headplane's is under /admin).
#
# ⚠️ headscale performs OIDC discovery at STARTUP and a failure is
# FATAL ("creating OIDC provider from issuer config: 404 Not Found") —
# it will not boot, taking the whole tailnet's control plane with it.
# Never point `issuer` at an application that doesn't exist yet; verify
# with:
# Authentik as the login provider (own application, slug `headscale`,
# separate from headplane's) so `tailscale up --login-server ...` opens a
# browser instead of needing a pre-auth key; headless hosts still use those.
# ⚠️ headscale does OIDC discovery at startup and a failure is fatal — it
# won't boot, taking the whole control plane with it. Never point `issuer`
# at an application that doesn't exist yet; verify with
# curl -s <issuer>.well-known/openid-configuration
#
# Headless hosts still enrol with pre-auth keys. Note also that users
# created here are distinct from `headscale users create` ones: matching
# is by the OIDC `sub` claim against the user's providerId, and 0.28
# dropped map_legacy_users, so CLI-made users never gain one.
# Users created here are matched by OIDC `sub`, so `headscale users
# create`-made users never link to one (0.28 dropped map_legacy_users).
oidc = {
issuer = "https://auth.mgaction.town/application/o/headscale/";
client_id = "14vhRYaLiONHmI2YFIxbQEveJDLu5cCvzSkTb9oq";
client_secret_path = config.sops.secrets.headscale_oidc_client_secret.path;
};
# Run our own DERP relay instead of pulling Tailscale's map.
#
# With the default (urls = [controlplane.tailscale.com/derpmap/default],
# auto_update_enabled = true) headscale fetches that map at startup and
# treats failure as FATAL — so a DNS blip or a Tailscale outage stops the
# control server from booting at all. A self-hosted control plane that
# can't start without Tailscale's infrastructure rather misses the point.
#
# The relay itself rides Caddy on :443 (hence the flush_interval -1 on
# that vhost); only STUN needs its own UDP port.
# Run our own DERP relay instead of pulling Tailscale's map: the default
# fetches that map at startup and treats a failure as fatal, so a DNS blip
# or Tailscale outage would stop this control server from booting at all.
# The relay rides Caddy on :443 (hence flush_interval -1 on that vhost);
# only STUN needs its own UDP port.
derp = {
urls = [ ];
auto_update_enabled = false;