# Headscale with DERP

> Self-hosted Tailscale control server with DERP relay for NAT traversal.

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

## Overview

Headscale is an open-source, self-hosted implementation of the Tailscale coordination server that enables you to run your own mesh VPN infrastructure without relying on Tailscale's SaaS platform. Originally created by Juan Font, headscale provides full control over your WireGuard-based mesh network, allowing organizations to maintain complete sovereignty over their networking infrastructure while benefiting from Tailscale's elegant architecture. The project implements the Tailscale protocol to coordinate peer-to-peer connections between devices running standard Tailscale clients.

This configuration combines headscale with a custom DERP (Designated Encrypted Relay for Packets) server and headscale-ui management interface to create a comprehensive self-hosted mesh VPN solution. The DERP component serves as a relay server that facilitates connections between clients behind restrictive NATs or firewalls that prevent direct peer-to-peer communication. When direct connections fail, traffic is encrypted and relayed through your DERP server, ensuring reliable connectivity across diverse network environments. The headscale-ui component provides a web-based management interface for monitoring connected devices, managing users, and viewing network topology.

This stack is ideal for privacy-conscious organizations, security teams managing distributed infrastructure, and homelab enthusiasts who want enterprise-grade mesh networking without cloud dependencies. By running your own coordination and relay infrastructure, you eliminate external dependencies, reduce latency through strategically placed DERP relays, and maintain complete audit trails of network activity. This approach is particularly valuable for organizations with strict data residency requirements or those operating in air-gapped environments.

## Features

- Self-hosted Tailscale coordination server with full protocol compatibility
- Integrated DERP relay server for reliable NAT traversal and connection fallback
- Web-based management interface for device enrollment and network visualization
- WireGuard-based mesh networking with automatic key rotation and peer discovery
- Multi-user namespace support with granular access control policies
- Built-in STUN server functionality for peer-to-peer connection establishment
- API-driven device management with support for programmatic client provisioning
- Custom DNS resolution with MagicDNS functionality for internal service discovery

## Use cases

- Enterprise organizations requiring complete control over mesh VPN infrastructure
- Development teams connecting distributed build servers and staging environments
- Security-conscious businesses avoiding third-party coordination servers
- Remote work setups needing secure access to on-premises resources
- Homelab enthusiasts building personal mesh networks across multiple locations
- Organizations with strict data residency requirements for networking metadata
- Air-gapped environments requiring isolated mesh networking capabilities

## Prerequisites

- Domain name with DNS control for DERP server configuration
- SSL/TLS certificates for DERP server placed in ./certs directory
- Minimum 1GB RAM for stable operation of all three components
- Ports 80, 443, 3478/UDP, 8080, 8443, and 9090 available on host system
- Understanding of WireGuard concepts and mesh networking principles
- Basic knowledge of Tailscale client configuration and authentication flows

## docker-compose.yml

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

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

  derper:
    image: ghcr.io/tailscale/derper:latest
    container_name: derper
    environment:
      - DERP_DOMAIN=${DERP_DOMAIN}
      - DERP_CERT_MODE=manual
      - DERP_ADDR=:443
      - DERP_HTTP_PORT=80
      - DERP_STUN_PORT=3478
      - DERP_VERIFY_CLIENTS=false
    volumes:
      - ./certs:/app/certs:ro
    ports:
      - "443:443"
      - "80:80"
      - "3478:3478/udp"
    networks:
      - headscale-network
    restart: unless-stopped

volumes:
  headscale-data:

networks:
  headscale-network:
    driver: bridge
```

## .env

```bash
# Headscale with DERP
DERP_DOMAIN=derp.example.com

# Create config/config.yaml with headscale configuration
# See: https://github.com/juanfont/headscale/blob/main/config-example.yaml
```

## Usage notes

- Headscale API at http://localhost:8080
- Web UI at https://localhost:8443
- DERP relay for NAT traversal
- Create users: headscale users create <name>
- Generate auth keys for clients

## Troubleshooting

- DERP server fails to start: Verify SSL certificates exist in ./certs directory with correct permissions and valid domain names
- Clients cannot connect through DERP relay: Check DERP_DOMAIN environment variable matches certificate common name and DNS resolution
- headscale-ui shows connection refused: Ensure headscale service is fully started before UI attempts connection, check network connectivity between containers
- Device registration fails with authentication errors: Verify pre-auth keys are generated correctly using headscale CLI and haven't expired
- Peer-to-peer connections not establishing: Confirm STUN server is accessible on port 3478/UDP and firewall allows WireGuard traffic
- API requests timing out: Increase headscale container memory allocation and check for resource constraints in container logs

