Deploying Headscale on a VPS

— A fresh Ubuntu 24.04 VPS

— A domain or subdomain (e.g. <headscale-domain>) with an A record already pointing at the VPS's public IP. DNS must resolve before you start Traefik, or Let's Encrypt's HTTP-01 challenge will fail.

— A sudo-capable non-root user to SSH in as

Step 1 · Update the system Run on: Headscale VPS

sudo apt update && sudo apt full-upgrade -y

Step 2 · Install Docker Engine + Compose plugin Run on: Headscale VPS

sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Step 3 · Let your user run Docker without sudo Run on: Headscale VPS

sudo usermod -aG docker <admin-user>
newgrp docker

Step 4 · Firewall Run on: Headscale VPS

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw --force enable

Step 5 · Set variables and create directories Run on: Headscale VPS

Run this whole block as one paste — the variables must stay set in-session for Steps 6–7.

mkdir -p ~/headscale/{config,lib,letsencrypt}
cd ~/headscale
DOMAIN="<headscale-domain>"
MAGICDNS_DOMAIN="<magicdns-domain>"
EMAIL="<admin-email>"
TZ="<timezone>"
PUBLIC_IP=$(curl -4 -s ifconfig.me)
echo "Public IP: $PUBLIC_IP"

Step 6 · Write docker-compose.yml Run on: Headscale VPS

cat > docker-compose.yml <
      

Step 7 · Write config/config.yaml Run on: Headscale VPS

cat > config/config.yaml <
      

Step 8 · Start the stack Run on: Headscale VPS

docker compose up -d

Step 9 · Verify the certificate issued and services are healthy Run on: Headscale VPS

docker compose ps
docker compose logs --tail 50 traefik

Look for successful certificate acquisition in the Traefik logs, and confirm headscale shows Up ... (healthy).

Quick end-to-end check:

curl -vk https://<headscale-domain>
curl -vk https://<headscale-domain>/web

Both should return HTTP/2 200.

Step 10 · Generate an API key and create your user Run on: Headscale VPS

docker exec headscale headscale apikeys create
docker exec headscale headscale users create <admin-user>

Step 11 · Log into the web UI Run on: your browser

— Go to https://<headscale-domain>/web

— Settings → set Headscale URL to https://<headscale-domain>

— Paste the API key from Step 10 and save

Step 12 · Register a device Run on: client device

Install Tailscale on the client, then:

tailscale up --login-server=https://<headscale-domain>

It prints a registration URL containing an auth-id (hskey-authreq-...). Approve it — Run on: Headscale VPS

docker exec headscale headscale nodes register --user <admin-user> --key hskey-authreq-XXXXXXXXXXXX

Confirm:

docker exec headscale headscale nodes list

1 · Join the VPS to its own tailnet Run on: Headscale VPS

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --login-server=https://<headscale-domain>

Approve the resulting auth-id the same way as Step 12 above.

2 · Add a second Traefik entrypoint for the UI Run on: Headscale VPS

In docker-compose.yml:

— Under the traefik service command: list, add:

- "--entrypoints.tailnet.address=:8443"

— Under traefik's ports:, add:

- "8443:8443"

— On the headscale-ui labels, change entrypoints=websecure to entrypoints=tailnet, and remove the tls / tls.certresolver lines for that router — no cert is needed, since WireGuard already encrypts the traffic.

3 · Firewall: allow port 8443 only via the tailscale interface Run on: Headscale VPS

sudo ufw allow in on tailscale0 to any port 8443 proto tcp
sudo ufw deny in on eth0 to any port 8443 proto tcp

4 · Recreate containers Run on: Headscale VPS

docker compose up -d

Reach the admin UI afterward at http://<vps-tailscale-ip>:8443/web — get that IP with:

tailscale ip -4