Publish privacy-safe Headscale deployment examples

README.md

@@ -0,0 +1,111 @@
+# Headscale + Headplane + Traefik
+
+This repository contains privacy-safe example files for running a self-hosted
+Headscale control plane with the Headplane web UI behind Traefik and automatic
+Let's Encrypt certificates.
+
+Only `README.md`, `.gitignore`, and files ending in `.example` are published.
+Real configuration, credentials, databases, generated keys, certificates,
+backups, and container images are ignored by design.
+
+## Architecture
+
+- **Headscale** provides the Tailscale-compatible control plane and embedded DERP/STUN.
+- **Headplane** provides the administration UI at `/admin`.
+- **Traefik** terminates HTTPS and routes requests to Headscale or Headplane.
+
+The example pins Headscale `v0.29.2`, Headplane `0.7.0`, and Traefik `v3.7.9`.
+
+## Requirements
+
+- A Linux server with Docker Engine and Docker Compose v2
+- A public IPv4 address
+- A domain such as `headscale.example.com` pointing to that address
+- Inbound `80/tcp`, `443/tcp`, and `3478/udp` allowed by the firewall
+
+## Prepare configuration
+
+Clone the repository, then create the ignored runtime files from the examples:
+
+```bash
+cp docker-compose.yml.example docker-compose.yml
+cp headscale/config/config.yaml.example headscale/config/config.yaml
+cp headscale/config/acl.hujson.example headscale/config/acl.hujson
+cp headplane/config/config.yaml.example headplane/config/config.yaml
+cp traefik/traefik.yml.example traefik/traefik.yml
+cp traefik/dynamic/headscale.yml.example traefik/dynamic/headscale.yml
+
+mkdir -p headscale/data headscale/run headplane/data traefik/letsencrypt
+touch traefik/letsencrypt/acme.json
+chmod 600 traefik/letsencrypt/acme.json
+```
+
+Replace the example values in the copied files:
+
+- `headscale.example.com`: the public control-plane domain
+- `dns.example.com`: the MagicDNS base domain
+- `203.0.113.10`: the server's public IPv4 address
+- `admin@example.com`: the Let's Encrypt account email
+- `REPLACE_WITH_OPENSSL_RAND_HEX_32`: output of `openssl rand -hex 32`
+
+Do not put real credentials in a file ending in `.example`.
+
+## Start and configure
+
+Validate the Compose model, then start Headscale and Traefik first:
+
+```bash
+docker compose config --quiet
+docker compose up -d headscale traefik
+```
+
+Create an API key for Headplane:
+
+```bash
+docker compose exec headscale headscale apikeys create --expiration 365d
+```
+
+Set the resulting key as `headscale.api_key` in the ignored
+`headplane/config/config.yaml`, set a random cookie secret, and start Headplane:
+
+```bash
+docker compose up -d headplane
+docker compose ps
+```
+
+Headscale is served at `https://headscale.example.com`; Headplane is served at
+`https://headscale.example.com/admin`.
+
+## Add a user and client
+
+```bash
+docker compose exec headscale headscale users create default
+docker compose exec headscale headscale preauthkeys create \
+  --user default --reusable --expiration 24h
+```
+
+Join a client with the generated pre-auth key:
+
+```bash
+tailscale up \
+  --login-server https://headscale.example.com \
+  --auth-key YOUR_PREAUTH_KEY
+```
+
+## Optional OIDC
+
+The Headscale and Headplane examples include commented OIDC sections. Copy and
+uncomment them only in the ignored runtime configuration files. Keep the OIDC
+client secret out of Git and use the same public issuer and client details in
+both services.
+
+## Operations
+
+```bash
+docker compose logs -f headscale headplane traefik
+docker compose pull
+docker compose up -d
+```
+
+Back up `headscale/data`, `headplane/data`, and `traefik/letsencrypt` securely.
+These directories contain private state and are intentionally never published.