feat(headscale): add self-hosted Tailscale control server #5

Merged

ashie merged 2 commits from franz-kafka/nixos-vps:feat/headscale into main

2026-03-19 20:18:58 +00:00

franz-kafka commented

2026-03-19 15:40:31 +00:00

Owner

Summary

Adds Headscale — a self-hosted Tailscale control server. All your devices get secure WireGuard mesh VPN connectivity without trusting Tailscale's SaaS.

What it does

Runs a Tailscale-compatible control server on vpn.ashisgreat.xyz
Devices authenticate via pre-shared API keys (OIDC optional, documented)
Uses Tailscale's public DERP relays for NAT traversal
MagicDNS for device hostname resolution
SQLite backend (fine for personal use)

Module features

Nginx reverse proxy with WebSocket support
Optional OIDC authentication (Google, GitHub, etc.)
Auto-added to backup paths
headscale CLI in system packages

After deploying

Add DNS record: vpn.ashisgreat.xyz → VPS IP
Generate an auth key:
```
sudo headscale apikeys create
```

Register a device:

tailscale up --login-server=https://vpn.ashisgreat.xyz --authkey=<key>

Create a user:
```
sudo headscale users create ashie
```

Enabling OIDC (optional)

Uncomment the OIDC block in configuration.nix and add headscale_oidc_secret to your secrets.yaml.

Changes

modules/headscale.nix — new module (152 lines)
modules/default.nix — import
configuration.nix — enabled with vpn.ashisgreat.xyz, comments for OIDC setup

DNS record needed

vpn.ashisgreat.xyz pointing to your VPS IP (certbot will handle the rest via Nginx/ACME).

## Summary Adds Headscale — a self-hosted Tailscale control server. All your devices get secure WireGuard mesh VPN connectivity without trusting Tailscale's SaaS. ### What it does - Runs a Tailscale-compatible control server on `vpn.ashisgreat.xyz` - Devices authenticate via pre-shared API keys (OIDC optional, documented) - Uses Tailscale's public DERP relays for NAT traversal - MagicDNS for device hostname resolution - SQLite backend (fine for personal use) ### Module features - Nginx reverse proxy with WebSocket support - Optional OIDC authentication (Google, GitHub, etc.) - Auto-added to backup paths - `headscale` CLI in system packages ### After deploying 1. **Add DNS record:** `vpn.ashisgreat.xyz` → VPS IP 2. **Generate an auth key:** ```bash sudo headscale apikeys create ``` 3. **Register a device:** ```bash tailscale up --login-server=https://vpn.ashisgreat.xyz --authkey=<key> ``` 4. **Create a user:** ```bash sudo headscale users create ashie ``` ### Enabling OIDC (optional) Uncomment the OIDC block in `configuration.nix` and add `headscale_oidc_secret` to your `secrets.yaml`. ### Changes - `modules/headscale.nix` — new module (152 lines) - `modules/default.nix` — import - `configuration.nix` — enabled with `vpn.ashisgreat.xyz`, comments for OIDC setup ### DNS record needed `vpn.ashisgreat.xyz` pointing to your VPS IP (certbot will handle the rest via Nginx/ACME).

franz-kafka added 1 commit 2026-03-19 15:40:31 +00:00

feat(headscale): add self-hosted Tailscale control server 1c28db5f8e

New module: modules/headscale.nix
- Headscale service listening on localhost with Nginx reverse proxy
- SQLite database (appropriate for personal use)
- Tailscale public DERP relays for NAT traversal fallback
- MagicDNS enabled with Mullvad/Quad9 upstream resolvers
- Optional OIDC authentication (Google, GitHub, etc.)
- Default auth: pre-shared API keys (headscale apikeys create)
- Added to backup paths (SQLite DB)
- headscale CLI tool added to system packages

Configuration:
- Domain: vpn.ashisgreat.xyz
- OIDC disabled by default (documented how to enable in configuration.nix)

To register a device after deploying:
  sudo headscale apikeys create
  tailscale up --login-server=https://vpn.ashisgreat.xyz --authkey=<key>

DNS record needed: vpn.ashisgreat.xyz → VPS IP

ashie added 1 commit 2026-03-19 20:18:12 +00:00