Comment créer ton propre réseau privé avec Headscale

Tu veux relier ton serveur, ton PC et ton téléphone dans un réseau privé chiffré, sans ouvrir de port sur ton routeur ni dépendre d'un service cloud ? C'est exactement ce que fait Tailscale. Et si tu veux garder le contrôle total, tu peux remplacer son serveur central par Headscale, une version open source que tu héberges toi-même, comme on le faisait pour notre gestionnaire de mots de passe Vaultwarden. Voici comment le mettre en place en une vingtaine de minutes.

De quoi tu as besoin

• Un petit serveur ou un VPS sous Linux, avec Docker installé (même une machine à 5 euros par mois suffit).
• Un nom de domaine (ou un sous-domaine) qui pointe vers ce serveur, avec un certificat HTTPS.
• Le client Tailscale installé sur les appareils que tu veux connecter (Linux, Windows, macOS, Android, iOS).
• Un peu de patience : Headscale change de configuration entre les versions, on y revient dans les pièges.

Étape 1 : comprendre le principe

Headscale est un serveur de coordination. Concrètement, c'est lui qui dit à tes machines comment se trouver et s'échanger des clés de chiffrement. Une fois la liaison faite, tes appareils communiquent directement entre eux, sans passer par ton serveur. Le trafic reste chiffré de bout en bout, et tu ne dépends plus du service cloud de Tailscale.

Étape 2 : créer les dossiers et la configuration

Crée un dossier de travail et les sous-dossiers qui accueilleront la configuration et les données :

mkdir -p ~/headscale/config
mkdir -p ~/headscale/data
cd ~/headscale

Télécharge ensuite le fichier d'exemple de configuration officiel et place-le dans le dossier config :

curl -o config/config.yaml \
  https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml

Ouvre ce fichier et modifie au minimum la ligne server_url pour y mettre l'adresse publique de ton serveur, par exemple https://headscale.tondomaine.fr. C'est l'adresse que tes clients utiliseront pour se connecter.

Étape 3 : lancer Headscale avec Docker Compose

Crée un fichier docker-compose.yml dans le dossier headscale avec ce contenu :

services:
  headscale:
    image: headscale/headscale:0.29.3
    container_name: headscale
    restart: unless-stopped
    read_only: true
    tmpfs:
      - /var/run/headscale
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./config:/etc/headscale:ro
      - ./data:/var/lib/headscale
    command: serve

Puis démarre le conteneur :

docker compose up -d

Vérifie qu'il tourne et que l'endpoint de santé répond :

docker ps
curl http://127.0.0.1:8080/health

Étape 4 : exposer Headscale en HTTPS

Tes clients doivent joindre Headscale en HTTPS. Le plus simple est de placer un reverse proxy (Caddy, Nginx, Traefik) devant le port 8080, qui gère le certificat automatiquement. Si tu utilises Caddy, une ligne suffit :

headscale.tondomaine.fr {
    reverse_proxy 127.0.0.1:8080
}

Une fois le proxy en place, vérifie que l'URL publique répond :

curl https://headscale.tondomaine.fr/health

Étape 5 : créer un utilisateur et une clé d'autorisation

Headscale organise les machines par utilisateur. Crée le tien, puis génère une clé d'autorisation (preauthkey) valable 24 heures :

docker exec headscale headscale users create moi
docker exec headscale headscale preauthkeys create --user moi -e 24h

Étape 6 : connecter tes appareils

Sur chaque machine, installe le client Tailscale puis connecte-le à ton serveur avec la clé d'autorisation :

sudo tailscale up \
  --login-server=https://headscale.tondomaine.fr \
  --authkey TA_CLE

Répète l'opération sur ton téléphone et ton autre ordinateur. Au bout de quelques secondes, chaque appareil reçoit une adresse IP privée dans le réseau 100.64.0.0/10, et ils peuvent se joindre directement.

Vérifier que ça fonctionne

Depuis l'un de tes appareils connectés, liste les machines du réseau et teste la liaison vers une autre :

tailscale status
ping 100.64.0.2

Si le ping passe, ton réseau privé est opérationnel. Tu peux maintenant accéder à ton serveur, tes fichiers ou ton interface d'administration depuis n'importe où, comme si tu étais chez toi.

Limites et pièges

Headscale change de configuration entre les versions mineures. Ne saute jamais une version lors d'une mise à jour : passe par chaque version intermédiaire, sinon tu risques de casser ta base de données. Sauvegarde toujours les dossiers config et data avant de mettre à jour.

Le trafic entre deux machines passe par un relais (DERP) quand une connexion directe est impossible, par exemple derrière un réseau très restrictif. Par défaut, Headscale utilise les relais publics de Tailscale ; tu peux en héberger un toi-même pour rester 100 % autonome.

Si un appareil ne se connecte pas, vérifie que le port 8080 est bien accessible depuis l'extérieur et que ton reverse proxy renvoie bien vers 127.0.0.1:8080. Une erreur fréquente est d'oublier de mettre à jour server_url après un changement de domaine.

Conclusion

Avec Headscale, tu récupères le confort de Tailscale sans en confier la coordination à un tiers. C'est un excellent premier pas vers un réseau privé que tu maîtrises de bout en bout, et ça se met en place en une soirée.

Logo officiel du projet Headscale, issu du dépôt GitHub du projet.

Sources

La documentation officielle de Headscale — la page d'installation en conteneur et le guide de démarrage, à jour.

Le dépôt GitHub du projet — le code source, les versions et le fichier d'exemple de configuration.

Le guide Docker Compose de Techdox — un pas-à-pas complet avec les pièges de mise à jour.

—

Recherche, relecture et illustration assistées par IA. Le contenu reflète le travail éditorial de la rédaction.