Skip to main content

Self-Hosted Tailscale Control Plane

Run your own Headscale server with Docker Compose. Complete control over your mesh VPN network with web UI, automated SSL, and production-ready architecture.

Get StartedGUI Quick Start

Quick start

Get your Headscale server running in minutes

1

Clone and configure

Clone the repository and copy the environment file:
git clone https://github.com/organicnz/headscale-tailscale-docker.git
cd headscale-tailscale-docker
cp .env.example .env
2

Start the stack

Launch all services with Docker Compose:
docker compose up -d
Services include Headscale, PostgreSQL, nginx reverse proxy, Headplane web GUI, and certbot for SSL.
3

Create a user and pre-auth key

Generate credentials for connecting devices:
docker exec headscale headscale users create myuser
docker exec headscale headscale preauthkeys create --user myuser --reusable --expiration 24h
Save the generated key for device registration.
4

Connect your first device

On any device with Tailscale installed:
sudo tailscale up --login-server http://localhost:8000 --authkey YOUR_KEY
Your device is now connected to your private mesh network!

Features

Everything you need for a production mesh VPN

Web GUI

Headplane web interface for managing users, nodes, and keys without CLI

Production Ready

nginx reverse proxy with SSL/TLS, health checks, and automated certificate renewal

PostgreSQL Backend

Reliable database with health monitoring and backup support

ACL Policies

Tag-based access control for granular network security

Helper Scripts

Management scripts for common operations and automation

MagicDNS

Automatic DNS resolution for devices in your network

Architecture

Production-grade infrastructure stack

Internet
   |
   v
nginx Reverse Proxy (HTTP/HTTPS)
   |
   +-- Headscale Server (with PostgreSQL)
   |
   +-- Headplane Web GUI (:3001/admin/)
   |
   +-- Certbot (SSL/TLS certificates)

All services communicate via the headscale-network bridge network. PostgreSQL provides persistent storage, nginx handles SSL termination and routing, and Headplane offers a web-based management interface.

Explore documentation

Dive deeper into deployment, configuration, and operations

Deployment guides

Learn how to deploy for local development or production environments

Configuration

Configure Headscale, nginx, database, and ACL policies

User guides

Manage users, nodes, routes, and DNS settings

Operations

Backup, monitoring, security, and troubleshooting

Ready to get started?

Deploy your own Headscale server in minutes with our quick start guide

View quick start guide