feat: add headscale test deployment artifacts

2026-03-12 17:58:34 +00:00
parent 55cfa43a0c
commit 0c75377943
2 changed files with 378 additions and 0 deletions
@@ -0,0 +1,233 @@
+# 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 :
+
+```bash
+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 :
+
+```bash
+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 :
+
+```bash
+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 :
+
+```bash
+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