Headplane

Headplane est une interface web complète pour Headscale, l’implémentation open source et auto-hébergée du serveur de contrôle Tailscale. Elle permet de gérer les nœuds, les clés de pré-authentification, les ACL et le DNS depuis un navigateur plutôt que via la CLI Headscale. Headplane ne remplace pas Headscale. Elle gère un serveur Headscale en cours d’exécution, c’est pourquoi cette image fournit les deux ensemble.

Logiciels inclus

Composant	Version
Headplane	0.7.0
Headscale	0.29.2
Docker	Dernière stable
Ubuntu	24.04 LTS

Headplane ne peut pas fonctionner seule, car chacune de ses actions est un appel à l’API Headscale. Cette image exécute le serveur de contrôle Headscale et l’interface Headplane ensemble, sous forme de pile Docker Compose.

Prérequis

Ressource	Minimum	Recommandé
vCPU	1	2
RAM	1 Go	2 Go
Stockage	10 Go	20 Go

Variables d’environnement

Vous pouvez définir ces variables au moment du déploiement depuis la marketplace. Laissez-les vides pour utiliser l’adresse de la machine virtuelle.

Variable	Description
`HEADSCALE_SERVER_URL`	URL publique par laquelle vos appareils joignent Headscale, un domaine HTTPS
`HEADPLANE_BASE_URL`	URL publique depuis laquelle l’interface Headplane est servie

Définissez-les lorsque vous placez la machine virtuelle derrière un nom DNS ou un reverse proxy TLS. HEADSCALE_SERVER_URL doit être une adresse que vos appareils peuvent réellement joindre, sinon l’enregistrement des nœuds échoue.

Démarrage

1. Connectez-vous à votre VM

ssh ubuntu@<your-vm-ip>

2. Attendez la configuration au premier démarrage

Au premier démarrage, un script écrit l’adresse de la VM dans les configurations Headscale et Headplane, génère un secret de session, démarre les deux services, crée un utilisateur Headscale nommé default et génère une clé d’API. Comptez 1 à 2 minutes. Suivez la progression:

journalctl -u headplane-first-boot.service -f

Le message de connexion (MOTD) confirme que Headplane est prête et affiche la clé d’API.

3. Récupérez la clé d’API

La clé est aussi écrite dans un fichier réservé à root:

sudo cat /etc/headplane/credentials.txt

4. Connectez-vous à Headplane

Ouvrez un navigateur à l’adresse:

http://<your-vm-ip>:3000/admin

Headplane s’authentifie auprès de Headscale avec une clé d’API. Collez la clé de l’étape précédente dans le formulaire de connexion. La clé expire après 90 jours. Vous pouvez en générer une nouvelle à tout moment:

docker exec headscale headscale apikeys create --expiration 90d

5. Rattachez un appareil

Pointez n’importe quel client Tailscale vers votre serveur Headscale:

tailscale up --login-server http://<your-vm-ip>:8080

Approuvez le nœud depuis l’interface Headplane, ou listez les nœuds en ligne de commande:

docker exec headscale headscale nodes list

Gérer Headplane

Headscale et Headplane s’exécutent sous forme de pile Docker Compose dans /opt/headplane.

# Vérifier l'état
cd /opt/headplane && docker compose ps

# Redémarrer
cd /opt/headplane && docker compose restart

# Consulter les journaux
cd /opt/headplane && docker compose logs -f headscale

La configuration de Headscale se trouve dans /opt/headplane/headscale/config/config.yaml et sa base de données sous /opt/headplane/headscale/data. Les politiques ACL sont stockées en base de données, vous pouvez donc les modifier directement depuis l’interface Headplane.

Sécurité

Les ports 3000 (interface Headplane) et 8080 (Headscale) sont ouverts sur l’interface réseau de la VM. UFW est activé et autorise ces ports ainsi que SSH (port 22).

Vos appareils doivent joindre Headscale sur le port 8080, mais l’interface Headplane n’a pas besoin d’être publique.

Pour restreindre l’interface à une adresse IP précise:

sudo ufw delete allow 3000/tcp
sudo ufw allow from <trusted-ip> to any port 3000

En production, pointez un enregistrement DNS vers la VM et terminez le TLS avec un reverse proxy (Caddy, nginx ou Traefik). Définissez HEADSCALE_SERVER_URL et HEADPLANE_BASE_URL sur les URL HTTPS, et passez cookie_secure: true dans /opt/headplane/headplane/config.yaml.