# Headscale Self-Hosted Tailscale

> Self-hosted Tailscale control server with Headscale, web UI, and DERP relay.

- Category: Security & Networking
- Difficulty: advanced
- Components: headscale, headscale-ui, derper, nginx
- Tags: vpn, headscale, tailscale, mesh-vpn, zero-trust
- Source: https://docker.recipes/security/headscale-tailscale-stack

## Overview

Headscale is an open-source, self-hosted implementation of the Tailscale control server that enables you to create your own mesh VPN network without relying on Tailscale's SaaS infrastructure. Originally developed as a reverse-engineered alternative to Tailscale's proprietary coordination server, Headscale provides the same zero-configuration mesh networking capabilities while maintaining full control over your network coordination and user data. The project implements the Tailscale protocol completely, allowing standard Tailscale clients to connect to your private control plane instead of Tailscale's commercial service.

This stack combines Headscale with essential supporting infrastructure to create a production-ready mesh VPN deployment. The Headscale-UI component provides a web-based management interface for monitoring connected devices, managing access controls, and visualizing your mesh network topology. The DERP relay server handles NAT traversal and encrypted relay traffic when direct peer-to-peer connections aren't possible, ensuring connectivity even in challenging network environments. NGINX serves as the reverse proxy, handling SSL termination, request routing, and providing a unified entry point for web-based management interfaces.

This configuration is ideal for organizations requiring complete control over their VPN infrastructure, privacy-conscious users who want to avoid third-party services, and enterprises with compliance requirements that prohibit external coordination servers. The combination delivers the convenience of Tailscale's mesh networking with the security and control of on-premises infrastructure, making it valuable for companies with sensitive data, regulated industries, and technical teams who need customizable VPN policies that aren't available in commercial offerings.

## Features

- Compatible with official Tailscale clients across all platforms without modification
- DERP relay server for encrypted traffic routing when direct connections fail
- Web-based UI for device management, network visualization, and access control policies
- Support for multiple namespaces to segregate different user groups or environments
- Pre-authentication key generation for streamlined device onboarding
- Machine expiry policies and automatic cleanup of stale connections
- DNS integration with MagicDNS for seamless hostname resolution across mesh nodes
- Exit node configuration for routing internet traffic through designated mesh peers

## Use cases

- Enterprise VPN replacement requiring on-premises control and compliance with data residency regulations
- Development teams needing secure access to staging environments and internal services across multiple locations
- Homelab enthusiasts creating private mesh networks for accessing self-hosted services remotely
- Organizations in regulated industries where third-party VPN coordination servers are prohibited
- Companies requiring custom access policies and network segmentation not available in commercial Tailscale
- Multi-cloud deployments needing secure inter-region connectivity without exposing services to public internet
- Remote workforce management with granular device access controls and audit trails

## Prerequisites

- Public domain name with DNS control for DERP server configuration and SSL certificate generation
- Valid SSL certificates for DERP server (port 443) and web interfaces
- Minimum 1GB RAM and 2 CPU cores for handling mesh coordination and DERP relay traffic
- Understanding of Tailscale networking concepts, ACL policies, and mesh VPN architecture
- Firewall configuration allowing inbound traffic on ports 80, 443, 3478/UDP, 8080, and 9090
- Basic knowledge of namespace management and pre-authentication key workflows

## docker-compose.yml

```yaml
services:
  headscale:
    image: headscale/headscale:latest
    command: serve
    volumes:
      - ./config:/etc/headscale
      - headscale_data:/var/lib/headscale
    ports:
      - "8080:8080"
      - "9090:9090"
    networks:
      - headscale-net
    restart: unless-stopped

  headscale-ui:
    image: ghcr.io/gurucomputing/headscale-ui:latest
    environment:
      HEADSCALE_URL: http://headscale:8080
    ports:
      - "8443:443"
    depends_on:
      - headscale
    networks:
      - headscale-net
    restart: unless-stopped

  derper:
    image: fredliang/derper:latest
    environment:
      DERP_DOMAIN: ${DERP_DOMAIN}
      DERP_CERT_MODE: manual
      DERP_VERIFY_CLIENTS: "true"
    ports:
      - "3478:3478/udp"
      - "443:443"
    volumes:
      - ./certs:/app/certs:ro
    networks:
      - headscale-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - headscale
    networks:
      - headscale-net
    restart: unless-stopped

volumes:
  headscale_data:

networks:
  headscale-net:
    driver: bridge
```

## .env

```bash
# Headscale Configuration
HEADSCALE_DOMAIN=headscale.example.com

# DERP Server
DERP_DOMAIN=derp.example.com

# Database URL (optional, defaults to SQLite)
# DATABASE_URL=postgres://user:pass@host/db
```

## Usage notes

- Create namespace: docker compose exec headscale headscale namespaces create default
- Create auth key: docker compose exec headscale headscale preauthkeys create --namespace default
- Web UI at https://localhost:8443
- Compatible with official Tailscale clients

## Troubleshooting

- Headscale API returns 'namespace not found': Create default namespace using 'headscale namespaces create default' command
- Tailscale client fails to connect with 'control server unreachable': Verify headscale container is accessible on port 8080 and DNS resolution is working
- DERP relay not functioning with connection timeouts: Check SSL certificates are properly mounted and DERP_DOMAIN environment variable matches your actual domain
- Web UI shows 'failed to fetch' errors: Confirm HEADSCALE_URL environment variable points to correct headscale service endpoint
- Devices can't establish direct connections: Ensure DERP server port 3478/UDP is open and reachable from client networks
- Machine registration fails with authentication errors: Generate new pre-auth key with proper namespace and expiry settings

