How to Self-Host Headscale on a VPS (Complete Guide)

Headscale is an open-source implementation of the Tailscale coordination server, allowing you to manage your own Tailscale network. This guide will walk you through the process of self-hosting Headscale on a VPS, making it easier for developers and homelabbers to take control of their networks while leveraging the flexibility of a Virtual Private Server (VPS).

Choosing Your VPS Provider

Before diving into the installation, you need to select a suitable VPS provider. Below is a comparison of some of the best options for hosting Headscale:

For this guide, we recommend using Hetzner Cloud for its excellent value and performance, but feel free to choose any provider based on your preference.

Setting Up Your VPS

Step 1: Create a VPS Instance

1. Sign up for your selected VPS provider (e.g., Hetzner).
2. Create a new VPS instance with at least 2 GB of RAM for Headscale. Select Ubuntu 20.04 or later as your operating system.
3. Access your VPS using SSH:

   ssh root@your_vps_ip

Step 2: Update the System

Update the system packages to ensure you’re running the latest software.

apt update && apt upgrade -y

Step 3: Install Docker

Headscale can be efficiently run in a Docker container. Here are the steps to install Docker:

1. Install prerequisites:

   apt install apt-transport-https ca-certificates curl software-properties-common -y

2. Add Docker’s official GPG key:

   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -

3. Set up the stable repository:

   add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

4. Install Docker:

   apt update && apt install docker-ce -y

Step 4: Install Docker Compose

Next, install Docker Compose to manage your Headscale container.

curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

Step 5: Set Up Headscale

1. Create a directory for Headscale:

   mkdir ~/headscale
   cd ~/headscale

2. Create a Docker Compose file:

   version: '3.8'
   
   services:
     headscale:
       image: headscale/headscale:latest
       ports:
         - "8180:8080"
       volumes:
         - headscale-data:/var/lib/headscale
       environment:
         - HEADSCALE_SERVER_HOST=my-headscale-server
         - HEADSCALE_SERVER_PORT=http://localhost:8080
   
   volumes:
     headscale-data:

3. Edit the environment variables in the Docker Compose file to suit your configuration.

Step 6: Start Headscale

Start the Headscale service by executing:

docker-compose up -d

Step 7: Set Up DNS and Client Configuration

You need to configure your DNS settings to allow clients to connect to your Self-Hosted Headscale.

1. Set up a DNS A record for your VPS IP to allow Tailscale clients to access your Headscale server.
2. Client Configuration: Install Tailscale on your devices and connect them to the Headscale server using the configured DNS.

Conclusion

You have successfully self-hosted Headscale on a VPS. This setup provides full control over your Tailscale network and ensures all connections are private and secure. For advanced configurations, refer to the awesome-selfhosted repository.

FAQs

How does Headscale improve Tailscale functionality?

Headscale allows you to self-host your Tailscale coordination server, giving you greater control over your network configurations, authentication, and user management. Unlike Tailscale’s primary service, which routes traffic through their servers, Headscale keeps your data local and private. This is especially beneficial for enterprises or developers seeking to enforce strict data privacy.

What are the security implications of self-hosting Headscale?

Self-hosting Headscale gives you exclusive access and control over the sensitive data handled by your Tailscale network. By managing your server, you can enforce custom security policies, regularly update your software, and prevent unauthorized access. However, it’s critical to maintain security practices like regular backups, firewall configurations, and monitoring logs to safeguard your self-hosted service.

Can I run Headscale on a low-spec VPS?

Yes, Headscale can run on low-spec VPS, but performance may vary. Typically, a VPS with at least 2 GB of RAM provides satisfactory performance for a small to medium network. If you expect high traffic or have numerous clients connected, consider opting for a more robust VPS to prevent outages and ensure a smooth experience. Check the full VPS comparison for more options.