added headscale

headscale_dev/README.md

@@ -0,0 +1,105 @@
+# 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