mirror of
https://github.com/nickyeoman/docker-compose-cookbooks.git
synced 2026-09-04 02:46:23 +00:00
106 lines
3.0 KiB
Markdown
106 lines
3.0 KiB
Markdown
# 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
|