Déployer Headscale sur VPS avec Caddy et HTTPS : tutoriel complet 2026

📍 Article principal du cluster : Headscale 2026 : guide complet. Lisez le pilier pour la vue d’ensemble.

Trente minutes pour passer d’un VPS vide à un Headscale de production avec HTTPS valide, prêt à accepter vos premiers clients Tailscale. Ce tutoriel détaille la procédure exacte sur Hetzner CX22 (4,51 €/mois) avec Caddy comme reverse proxy. Méthode validée chez plusieurs PME à Dakar, Abidjan, Lomé, et Ouagadougou.

Prérequis

• VPS Hetzner CX22 ou OVH VPS-1 (Debian 12 ou Ubuntu 22.04 LTS).
• Un nom de domaine avec enregistrement DNS A : headscale.votre-entreprise.com → IP du VPS.
• Accès SSH root.
• Niveau : intermédiaire (Linux, systemd, fichiers YAML).
• Temps estimé : 30 à 45 minutes.

Étape 1 — Préparer le VPS

Mises à jour système et firewall :

apt update && apt upgrade -y
apt install -y ufw fail2ban
ufw allow 22 80 443
ufw allow 41641/udp  # DERP / WireGuard
ufw enable

Étape 2 — Installer Headscale via dépôt officiel

curl -fsSL https://github.com/juanfont/headscale/releases/download/v0.23.0/headscale_0.23.0_linux_amd64.deb -o /tmp/headscale.deb
dpkg -i /tmp/headscale.deb
systemctl enable headscale
mkdir -p /etc/headscale /var/lib/headscale

Étape 3 — Configuration de base

Éditer /etc/headscale/config.yaml :

server_url: https://headscale.votre-entreprise.com
listen_addr: 127.0.0.1:8080
metrics_listen_addr: 127.0.0.1:9090
private_key_path: /var/lib/headscale/private.key
noise:
  private_key_path: /var/lib/headscale/noise_private.key

prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48

derp:
  server:
    enabled: false
  urls:
    - https://controlplane.tailscale.com/derpmap/default

database:
  type: sqlite
  sqlite:
    path: /var/lib/headscale/db.sqlite

log:
  level: info

dns:
  magic_dns: true
  base_domain: tailnet.votre-entreprise.com
  nameservers:
    global:
      - 1.1.1.1
      - 9.9.9.9

Étape 4 — Configurer Caddy pour HTTPS

apt install -y caddy

Éditer /etc/caddy/Caddyfile :

headscale.votre-entreprise.com {
  reverse_proxy 127.0.0.1:8080
  encode gzip
  
  log {
    output file /var/log/caddy/headscale.log {
      roll_size 100MB
      roll_keep 7
    }
  }
}

Recharger Caddy : systemctl reload caddy. Test : curl -I https://headscale.votre-entreprise.com/health. Doit retourner 200 OK.

Étape 5 — Démarrer Headscale

systemctl start headscale
systemctl status headscale

Logs : journalctl -u headscale -f.

Étape 6 — Créer le premier utilisateur et la première preauth key

headscale users create amadou
headscale preauthkeys create --user amadou --expiration 24h --reusable

La sortie contient une clé du type 1234567890abcdef.... Notez-la, elle expire dans 24h.

Étape 7 — Connecter le premier appareil

Sur un poste Linux :

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --login-server=https://headscale.votre-entreprise.com --auth-key=PREAUTH_KEY

Sur Mac : ouvrir Terminal, brew install --cask tailscale, puis lancer l’app, faire option-clic sur l’icône en haut à droite, choisir « Use Custom Coordination Server », saisir l’URL, puis Login.

Sur iOS / Android : ouvrir Settings dans l’app Tailscale officielle, faire 5 taps sur la version pour activer le mode debug, modifier l’URL du coordination server.

Étape 8 — Vérification

headscale nodes list

Vous voyez votre premier appareil enregistré, avec son IP attribuée (typiquement 100.64.0.1). Test de ping entre deux appareils :

tailscale ping autre-appareil
# Pong from autre-appareil via direct connection

Étape 9 — Configuration OIDC (optionnel mais recommandé)

Pour brancher Authelia ou Authentik comme fournisseur d’identité, ajouter dans config.yaml :

oidc:
  issuer: https://auth.votre-entreprise.com
  client_id: headscale
  client_secret: votre-secret
  scope: ["openid", "profile", "email"]
  extra_params:
    domain_hint: votre-entreprise.com
  allowed_users:
    - amadou@votre-entreprise.com

Erreurs fréquentes

Adaptation au contexte ouest-africain

Trois ajustements pour une PME africaine. Choix du DERP relay : par défaut Headscale utilise les DERP de Tailscale (US et Europe). Pour optimiser la latence depuis l’Afrique de l’Ouest, vous pouvez auto-héberger un DERP sur un VPS Africa Data Centres (Lagos ou Le Cap) — option avancée. Pour la majorité, les DERP Frankfurt/Paris suffisent. Coût total annuel : 54 €/an de VPS + 12 €/an de domaine = 66 € pour une équipe illimitée. Gestion des employés temporaires : freelances et stagiaires sont fréquents en Afrique de l’Ouest. Headscale + preauth keys à durée limitée (24h, 7j, 30j) gèrent élégamment l’onboarding-offboarding.

Tutoriels frères du cluster

• ACL Headscale pour équipe distribuée
• Migrer de Tailscale Cloud à Headscale

FAQ

Quelle différence entre Tailscale et Headscale au quotidien ? Aucune côté utilisateur. Les clients officiels Tailscale fonctionnent identiquement avec Headscale, l’interface graphique et les commandes CLI sont les mêmes.

Combien de temps prend la migration de Tailscale Cloud ? Pour 30 appareils, comptez une demi-journée pour scripts, une demi-journée pour la bascule. Voir tutoriel dédié.

Headscale supporte-t-il l’IPv6 ? Oui, dual-stack par défaut. Les peers obtiennent une IPv4 dans 100.64.0.0/10 et une IPv6 dans la plage configurée.

Comment monitorer Headscale ? Endpoint /metrics Prometheus, ingestion Grafana. Alertes sur nombre de nodes hors ligne, sur taille SQLite, sur erreurs API.

SQLite suffit pour combien d’appareils ? Jusqu’à 500 appareils confortablement. Au-delà, basculer sur PostgreSQL via database.type: postgres.

Pour aller plus loin

• 🔝 Retour au pilier : Guide complet Headscale 2026
• Documentation Headscale : headscale.net
• Tutoriel suivant : ACL pour équipe distribuée