# Heascale

## Overview

Headscale is a self-hosted control server for Tailscale clients. It allows you to run your own private coordination plane for a WireGuard-based mesh network without relying on external SaaS services.

This deployment is designed to run fully self-hosted behind a reverse proxy.

Requires a valid config.yaml before first startup.

## Project Details

* Project Repository: https://github.com/juanfont/headscale
* Container Image: https://hub.docker.com/r/headscale/headscale
* Admin UI Image: https://hub.docker.com/r/goodieshq/headscale-admin
* Documentation: https://headscale.net/
* Reverse Proxy Domain: headscale.example.com
* Internal Service Port: 8080 (not exposed publicly)
* Environment Variable Notes

## Core Settings

These variables are used in the Docker Compose file (.env):

```
HEADSCALE_IMAGE – Docker image for Headscale server (default: headscale/headscale:latest)
HEADSCALE_UI_IMAGE – Docker image for admin UI
HEADSCALE_RESTART – Restart policy (default: unless-stopped)
HEADSCALE_UI_RESTART – Restart policy for UI container

# Paths
CONFIG_PATH – Location of configuration files (config.yaml)
DATA_PATH – Persistent database storage (SQLite)
LOG_PATH – Application logs

# System
TZ – Timezone (e.g. America/Vancouver)
HEADSCALE_LOG_LEVEL – Logging verbosity (info, debug, etc.)
Domain Configuration
HEADSCALE_DOMAIN – Public-facing domain used via reverse proxy
Example: headscale.4lt.ca

HEADSCALE_URL – Full URL used by Headscale clients
Must match your reverse proxy domain:
```

## Volume Notes

All data is stored locally on the host for full self-sovereignty:

```
./config/headscale/config → Contains config.yaml (required configuration file)
./data/headscale → SQLite database and persistent Headscale state
./logs/headscale → Optional logs for debugging and monitoring
```

Back up data/ and config/ regularly for recovery.

## Network Notes

Uses a private Docker bridge network: internal
No public ports exposed directly
All access is routed through reverse proxy (NPM)
Reverse Proxy Requirements (Nginx Proxy Manager)

For headscale.example:

Forward hostname: headscale
Forward port: 8080
Scheme: http
Enable:
Websockets Support ✔
Block Common Exploits ✔
SSL (Let’s Encrypt) ✔
Disable caching ✔
Additional Notes / Gotchas
Headscale will not function without a valid config.yaml

server_url inside config.yaml MUST match your domain.

Clients must explicitly point to your server:

tailscale up --login-server=https://headscale.4lt.ca
Do NOT expose port 8080 publicly — only via reverse proxy
SQLite is used by default (no external DB required)
Dockhand Stack, Deploy from Git

Cookbooks Repository
stackname: headscale

Compose file path:

headscale/compose.yaml

Additional env file (optional):

headscale/sample.env
Deployment Steps
Load sample.env into Dockhand environment variables

Ensure config.yaml exists in:

./config/headscale/config/config.yaml
Deploy stack
Configure reverse proxy in Nginx Proxy Manager