budget-tracker/headscale-anytype-body.md

Headscale / Headscale UI sur QNAP — finalisation

Ce qui a déjà été déployé

Stack Portainer : headscale-test

Services :

• headscale
• headscale-ui
• headscale-init

Chemins NAS :

• /share/ZFS24_DATA/docker/headscale-test/config
• /share/ZFS24_DATA/docker/headscale-test/data

Ports de test actuels :

• API Headscale : 192.168.1.150:8086
• Metrics : 192.168.1.150:9096
• UI HTTP : 192.168.1.150:18087
• UI HTTPS auto-signé : 192.168.1.150:18447
• gRPC : 192.168.1.150:50443

Domaine cible configuré dans config.yaml :

• https://hs.nucleon.fr

Base domain MagicDNS de test :

• internal.hs.nucleon.fr

Important

headscale-ui doit idéalement être servi sur le même sous-domaine que Headscale, typiquement :

• https://hs.nucleon.fr/ → Headscale
• https://hs.nucleon.fr/web → Headscale UI

Sinon il faudra gérer CORS proprement au reverse proxy.

---

Étapes restantes pour finaliser l'installation

1) Créer le sous-domaine DNS

Créer un enregistrement DNS pour :

• hs.nucleon.fr

Il doit pointer vers l'IP publique qui arrive sur ton reverse proxy.

---

2) Mettre en place le reverse proxy HTTPS

Objectif : exposer le même host pour Headscale et l'UI.

Routing recommandé :

• /web → http://headscale-ui:8080
• / → http://headscale:8080

Si tu le fais via SWAG/Nginx Proxy Manager/Caddy, garde bien cette logique de même sous-domaine.

Exemple logique de proxy

• https://hs.nucleon.fr/web → UI
• https://hs.nucleon.fr → API Headscale

Sans ça, l'UI peut afficher des erreurs de preflight / CORS.

---

3) Vérifier la conf Headscale

Fichier actuel :

• /share/ZFS24_DATA/docker/headscale-test/config/config.yaml

Points déjà posés :

• server_url: https://hs.nucleon.fr
• SQLite locale
• MagicDNS activé
• ACL de test très ouverte
• DERP public Tailscale utilisé pour commencer

À ajuster plus tard si besoin :

• DNS interne personnalisé
• OIDC / SSO
• DERP perso
• ACL plus stricte

---

4) Créer le premier user / namespace

Dans le conteneur headscale, créer ton premier user.

Exemple logique :

• user principal : christophe

Commande type à exécuter dans le conteneur :

headscale users create christophe
headscale users list

---

5) Générer une API key pour l'UI

Headscale UI a besoin d'une API key Headscale.

Commande type :

headscale apikeys create

Ensuite, dans Headscale UI :

• renseigner l'URL du serveur : https://hs.nucleon.fr
• coller l'API key générée

Tant que le reverse proxy n'est pas proprement en place, l'UI peut être capricieuse.

---

6) Générer des preauth keys pour connecter les machines

Pour enregistrer une machine dans Headscale :

headscale preauthkeys create --user christophe --reusable --expiration 24h

Selon le besoin, tu peux faire :

• des clés temporaires
• des clés réutilisables
• des clés taggées

---

7) Reconfigurer les clients Tailscale vers Headscale

Sur chaque machine, il faudra connecter le client Tailscale à ton serveur Headscale.

Principe :

• se déconnecter proprement si besoin
• se reconnecter avec ton login server Headscale
• utiliser une preauth key quand nécessaire

Le point clé côté client sera ton serveur :

• https://hs.nucleon.fr

---

8) Vérifier la remontée des nodes

Après connexion des clients :

headscale nodes list

Vérifier :

• IPs attribuées
• nom des machines
• routes annoncées
• statut en ligne

---

9) Durcir les ACL

La policy actuelle est volontairement permissive pour les tests :

• tout le monde peut parler à tout le monde

Fichier :

• /share/ZFS24_DATA/docker/headscale-test/config/acl.hujson

Avant passage en production, définir :

• users
• tags
• groupes
• accès par rôle
• restrictions SSH
• accès subnet routers / exit nodes

---

10) Préparer la migration depuis Tailscale

Avant remplacement complet, valider :

• connexion d'au moins 2-3 machines
• DNS interne
• accès entre machines
• subnet router si besoin
• exit node si besoin
• stabilité mobile
• performance générale

Migration prudente recommandée :

1. Monter Headscale en parallèle
2. Tester avec quelques machines
3. Reproduire les usages critiques
4. Basculer progressivement
5. Couper Tailscale quand tout est validé

---

Remarques d'architecture

Pour les tests, le choix Docker/QNAP est bon.

Mon avis :

• pour tester → stack Docker dédiée sur le QNAP, très bien
• plus tard → on pourra décider si ça reste autonome ou si on le rattache à une stack plus globale

Je penche plutôt pour le laisser séparé d'OpenClaw :

• responsabilités plus claires
• moins de couplage
• maintenance plus simple
• migration / rollback plus propres

---

Checklist courte

• DNS hs.nucleon.fr
• Reverse proxy HTTPS même host pour / et /web
• Création user christophe
• Génération API key UI
• Connexion UI
• Génération preauth keys
• Connexion des premières machines
• Validation réseau
• Durcissement ACL
• Migration progressive hors Tailscale