57_WolveandClaude Opus 5
d6542996fc
deploy.sh deliberately re-reads .env before rendering config.yaml and
headplane.yaml ("so config.yaml substitution sees what's actually
deployed"). That design is right, but .env was seeded only when absent, so
"what's actually deployed" could never change: `set -a; . "$ENV_FILE"`
overwrote every value passed to the run, and `set -a` re-exported the stale
ones into compose as well.
Worse, the prompts at :192-197 run 56 lines BEFORE ENV_FILE is even defined,
so an interactive re-run asked for all six required values and then threw
every answer away. Via automations.sh the same six arrive exported and meet
the same fate. The validation only greps .env for non-empty values, which
the stale ones satisfy, so the run printed DEPLOYED and exited 0.
The case that matters is a rotated OIDC_CLIENT_SECRET: headscale keeps
presenting the retired secret at pocket-id's token endpoint, and
only_start_if_oidc_is_available probes issuer discovery, not the secret, so
nothing fails at deploy time. Either the leaked credential is still live and
the rotation is fiction, or tailnet OIDC login is broken and surfaces later
at some user's `tailscale up`. A corrected HEADSCALE_DOMAIN leaves the LE
cert hostname and the OIDC redirect URI on the typo; newly-supplied
headplane OIDC creds silently leave /admin on API-key login, so the
IdP-group gating the README recommends is never in force.
Record which keys arrived in the environment BEFORE the ":=" defaults erase
the distinction -- writing a blank over a live OIDC secret is exactly the
wrong move. Pre-load .env into keys NOT passed, before prompting, so the
prompts stop asking questions they will discard (and SKIP_PROMPTS=1 no
longer dies demanding values .env already has). Then write only the passed
keys through with a set_env upsert. Secret values are never echoed; a
changed HEADSCALE_DOMAIN warns about the new cert and the redirect URI.
The `. "$ENV_FILE"` stays: once .env carries this run's values it reads back
what was passed, and .env, config.yaml, headplane.yaml and compose agree.
Verified: rotated secret lands and is not echoed; changed domain lands and
warns; new headplane creds land; a re-run passing nothing touches nothing;
SKIP_PROMPTS=1 with a configured .env and no env vars no longer dies.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
headscale
Headscale — a self-hosted Tailscale control server — behind Caddy, with OIDC login delegated to pocket-id.
Prerequisite
Register an OIDC client in pocket-id's admin UI with redirect URI:
https://${HEADSCALE_DOMAIN}/oidc/callback
Then paste its OIDC_CLIENT_ID / OIDC_CLIENT_SECRET below.
Required .env values
| Variable | Notes |
|---|---|
HEADSCALE_DOMAIN |
Public hostname (e.g. hs.example.com). Clients connect here over HTTPS. |
ACME_EMAIL |
Let's Encrypt registration email. |
TAILNET_DOMAIN |
MagicDNS suffix (e.g. tail.example.com). Must differ from HEADSCALE_DOMAIN. |
POCKETID_DOMAIN |
OIDC issuer hostname (your pocket-id). |
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET |
From the pocket-id client above. |
The deploy substitutes these into config.yaml from the embedded template. See
.env.example.
Deploy
./automations.sh # Deploy on this host → deploy: headscale
Or build + run the self-contained artifact:
./build.sh
scp deploy.sh root@host:
ssh root@host 'bash deploy.sh'
# non-interactive: pass HEADSCALE_DOMAIN, ACME_EMAIL, TAILNET_DOMAIN,
# POCKETID_DOMAIN, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, SKIP_PROMPTS=1
Unattended provisioning: cloud-init.yml.
DNS for HEADSCALE_DOMAIN must resolve to the host and 80/443 be reachable
before deploy.
Headplane (web UI)
Headplane ships in the stack, served by
Caddy at https://HEADSCALE_DOMAIN/admin. It runs API-only — it talks
to the headscale API with a key and does not get the Docker socket, so it
can't control the host. deploy.sh mints the headscale API key automatically
on first deploy (stored in .env) and generates headplane.yaml.
Login: to use OIDC via pocket-id, register a second OIDC client in pocket-id with redirect URI:
https://HEADSCALE_DOMAIN/admin/oidc/callback
and pass HEADPLANE_OIDC_CLIENT_ID / HEADPLANE_OIDC_CLIENT_SECRET (prompted
by the launcher, or set in .env). Leave them blank to use headplane's
API-key login instead. Pin the image with HEADPLANE_TAG (defaults to
latest).
Gate /admin to a superuser group: restrict it at pocket-id — edit the
headplane OIDC client and set its Allowed User Groups to your superuser
group. Only members of that group can complete the OIDC login, so only they can
reach /admin. (Enforced at the IdP, so it covers the UI regardless of
headplane's own checks.)
headplane integration is version-sensitive; if the UI doesn't come up, check
docker compose logs headplaneand verifyheadplane.yaml/ the mintedHEADPLANE_HS_API_KEYin.env.
ACL policy
A starter ACL ships in policy.hujson (installed to
$STACK_DIR/policy.hujson on first deploy; your edits survive re-deploys).
headscale uses Tailscale's legacy acls format, not the newer grants
syntax from the Tailscale admin console — the bundled policy is that default
translated over (per-user self-access, a tag:shared everyone can reach, and
SSH to your own devices). Some pieces (autogroup:self, the ssh block) are
newer/experimental in headscale; a permissive fallback is included in the file.
$EDITOR /srv/headscale/policy.hujson
headscale policy check # validate (host CLI wrapper)
cd /srv/headscale && docker compose restart headscale # apply