steffen 5ba78886d2 Add SD image pipeline, documentation overhaul, and fix module issues

- Add automatic SD image builds for Raspberry Pi via Forgejo Actions
- Enable binfmt emulation on cryodev-main for aarch64 cross-builds
- Add sd-image.nix module to cryodev-pi configuration
- Create comprehensive docs/ structure with installation guides
- Split installation docs into: first-install (server), reinstall, new-client (Pi)
- Add lib/utils.nix and apps/rebuild from synix
- Fix headplane module for new upstream API (tale/headplane)
- Fix various module issues (mailserver stateVersion, option conflicts)
- Add placeholder secrets.yaml files for both hosts
- Remove old INSTRUCTIONS.md (content moved to docs/)

2026-03-11 08:41:58 +01:00

1.9 KiB

Raw Blame History

Headplane

Headplane is a web-based admin interface for Headscale.

References

GitHub

Setup

DNS

Set a CNAME record for headplane.cryodev.xyz pointing to your main domain.

Generate Secrets

Cookie Secret (for session management):

nix-shell -p openssl --run 'openssl rand -hex 16'

Agent Pre-Auth Key (for Headplane's built-in agent):

# First, create a dedicated user
sudo headscale users create headplane-agent

# Then create a reusable pre-auth key
sudo headscale preauthkeys create --expiration 99y --reusable --user headplane-agent

Add to Secrets

Edit hosts/cryodev-main/secrets.yaml:

sops hosts/cryodev-main/secrets.yaml

headplane:
  cookie_secret: "your-generated-hex-string"
  agent_pre_authkey: "your-preauth-key"

Configuration

# hosts/cryodev-main/services/headplane.nix
{ config, ... }:
{
  sops.secrets."headplane/cookie_secret" = { };
  sops.secrets."headplane/agent_pre_authkey" = { };
  
  services.headplane = {
    enable = true;
    settings = {
      server = {
        cookie_secret_file = config.sops.secrets."headplane/cookie_secret".path;
      };
      headscale = {
        url = "https://headscale.cryodev.xyz";
      };
      agent = {
        enable = true;
        authkey_file = config.sops.secrets."headplane/agent_pre_authkey".path;
      };
    };
  };
}

Usage

Access Headplane at https://headplane.cryodev.xyz.

Features

View and manage users
View connected nodes
Manage routes and exit nodes
View pre-auth keys

Troubleshooting

Check Service Status

sudo systemctl status headplane

View Logs

sudo journalctl -u headplane -f

Agent Not Connecting

Verify the agent pre-auth key is valid:

sudo headscale preauthkeys list --user headplane-agent

If expired, create a new one and update the secrets file.

1.9 KiB Raw Blame History