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/headplane.nix
+12 -20
View File
@@ -1,25 +1,20 @@
{ config, ... }:
# Headplane — web UI for headscale (services/vpn/headscale.nix; must be enabled
# first), running as headscale's own OS user.
# Headplane — web UI for headscale (services/vpn/headscale.nix; enable first),
# running as headscale's OS user.
#
# It reads headscale's config from the nix store, which is read-only — so the
# UI DISPLAYS the settings but can't change them. That's the intended shape
# for a declaratively-configured box (config_strict already defaults off
# upstream for exactly this reason); edit them here and rebuild instead.
# DNS extra-records are the one thing worth making editable, since they're
# data rather than config — hence the writable extra_records file below,
# which also spares headplane from restarting headscale on every change.
# It reads headscale's config from the nix store, so the UI DISPLAYS settings
# but can't change them (edit here and rebuild instead) — except DNS
# extra-records, which are data rather than config, hence the writable
# extra_records file below.
#
# Served at vpn.mgaction.town/admin (path-routed alongside headscale itself,
# see hosts/neptun/configuration.nix). base_url is the site root WITHOUT the
# /admin prefix — Headplane appends that itself, including for the OIDC
# callback.
# Served at vpn.mgaction.town/admin (path-routed with headscale, see
# hosts/neptun/configuration.nix); base_url excludes the /admin prefix, which
# Headplane appends itself including for the OIDC callback.
#
# Auth is Authentik (services/identity/authentik.nix) via OIDC. client_id,
# client_secret, and the headscale API key can't be known until
# Authentik/headscale are actually deployed, so they're placeholders below;
# direct API-key login still works as a fallback until then. Once live:
# Auth is Authentik via OIDC; client_id/client_secret/API key are placeholders
# until Authentik/headscale are deployed (direct API-key login works as a
# fallback until then). Once live:
# 1. In Authentik: create an OAuth2/OpenID Provider + Application with slug
# `headplane` and redirect URI
# https://vpn.mgaction.town/admin/oidc/callback. Copy the generated
@@ -28,9 +23,6 @@
# headplane_oidc_client_secret with the provider's client secret.
# 3. `headscale apikeys create` on the box, and replace
# headplane_headscale_api_key the same way.
#
# NOTE: Authentik issues per-application, so the issuer carries the app slug —
# it is NOT the bare host the way Zitadel's was.
{
# Writable DNS extra-records, shared by both services (they run as the same
# user). tmpfiles seeds an empty JSON array — headscale won't start against