🧭 cluster-skill
La boîte à outils et la documentation d'exploitation du cluster MacLustr : inventaires, procédures, wrappers de ligne de commande et références du tunnel public.
Sommaire
- Présentation
- Le cluster en un coup d'œil
- Index des documents
- Index des outils
- Arborescence
- Utilisation
- Règle remote-first
- Régénérer les PDF
- Variables d'environnement
- Sécurité et confidentialité
- État du dépôt
- Auteur et licence
📌 Présentation
cluster-skill rassemble tout ce qu'un opérateur doit lire ou lancer pour exploiter MacLustr, un cluster de Mac Apple Silicon installé sur un même réseau local :
- les documents de référence — inventaire des machines, procédure standard, fonctionnement du tunnel public, transfert d'un poste d'opérateur ;
- les wrappers
mld,mltetmlmobile, qui relaient depuis le poste de l'opérateur les commandes vers la passerelle, le tunnel ou le coordinateur mobile ; - les copies de référence de la configuration de la passerelle publique (Caddy, WireGuard,
tunnelctl) ; - des outils ponctuels — installation d'un serveur dédié, génération du dossier technique en PDF, release de l'app macOS.
Le dépôt ne contient ni application ni service : rien n'y tourne. Le dépôt de travail est celui de la passerelle M1M32 (~/cluster-skill) ; les copies sur les postes d'opérateur sont des miroirs en lecture.
🖥 Le cluster en un coup d'œil
flowchart LR
OP["Poste de l'opérateur<br/>wrappers mld · mlt · mlmobile"]
subgraph LAN["Réseau local MacLustr — 29 Mac, 401 cœurs, 1 068 Go"]
GW["M1M32 — passerelle<br/>spbgit + mld + cluster-skill"]
W["Nœuds worker<br/>Mac Studio · Mac mini · MacBook"]
AG["M4M64a<br/>agentd + coordinateur mobile"]
end
PH["iPhone<br/>nœuds mobiles"]
T["BHS64 — MacLustr Tunnel<br/>hub WireGuard + Caddy"]
NET(("Internet"))
OP -- "mld (ssh)" --> GW
OP -- "mlt (ssh)" --> T
OP -- mlmobile --> AG
GW -- "rsync / PM2 / heal" --> W
GW -- tunnelctl --> T
W -- "wg1 (WireGuard)" --> T
PH -. "tirent des jobs" .-> AG
NET -- "https://domaine" --> T
| Rôle | Machine | Ce qu'elle porte |
|---|---|---|
| Passerelle du cluster | M1M32 | forge git spbgit, orchestrateur mld, staging, registre, ce dépôt |
| Nœuds worker | Mac Studio, Mac mini, MacBook Pro / Air | les applications, placées par mld selon un score de ressources |
| Télémétrie | M4M64a | maclustr-agentd (API pour les apps macOS / iOS) et le coordinateur des nœuds mobiles |
| Passerelle publique | BHS64 | hub WireGuard + Caddy : chaque site public est une route https://<domaine> → <nœud>:<port> |
Totaux tirés de NODES.md : 29 Mac, 401 cœurs, 1 068 Go de RAM, et un serveur Linux dédié pour le tunnel.
📚 Index des documents
| Document | Lignes | À quoi il sert | Statut |
|---|---|---|---|
MACLUSTR-PROCEDURE.md |
54 | Procédure standard remote-first : qui possède quel composant, sur quel nœud le modifier, séquence de modification, rôle de mld adopt et de la garde de mld deploy, vérifications après toute opération |
en vigueur — à lire en premier |
NODES.md · NODES.pdf |
130 · 3 p. | Inventaire de travail complet : nœuds du LAN, numéros de nœud et étiquettes QR, Macs loués retirés, nœuds mobiles, serveurs dédiés, accès et outils. À mettre à jour à chaque ajout ou retrait de machine | en vigueur — document interne (voir Sécurité) |
INVENTAIRE-MACLUSTR.md · .pdf |
177 · 10 p. | Inventaire présentable, sans identifiants : matériel et système mesurés, rôle / runtimes / applications par nœud, serveurs dédiés, topologie publique, répartitions par emplacement, modèle et puce, capacité libre, sources et méthode | en vigueur |
MACLUSTR-TUNNEL.md |
68 | MacLustr Tunnel : principe (remplace ngrok), composants, commandes mlt / tunnelctl, état de la migration, procédure de migration d'un site, points d'attention |
en vigueur |
TRANSFERT-OPERATEUR.md |
56 | Transférer l'accès au cluster et les connaissances Claude Code sur un autre ordinateur : ce qui constitue la connaissance, prérequis réseau, procédure, cohérence entre deux opérateurs | en vigueur |
KA-REMOTE-DEV.md |
66 | Développement direct sur les nœuds pour les projets Groupe Ka : table des projets, serveur git central, flux de travail, statut des copies locales | référence — emplacements à confirmer par mld status |
GATEWAY.md |
61 | Diffusion d'un projet de calcul distribué : un envoi vers le nœud de staging, puis diffusion parallèle sur le LAN (cluster-gateway.sh) ; convention d'usage pour les jobs |
utilisable pour le calcul, pas pour les apps |
INVENTAIRE-MACS.md · .pdf |
118 · 5 p. | Inventaire des Macs par emplacement, incluant les Macs loués hors site | historique — les Macs loués ont été retirés le 2026-09-25 |
MACLUSTR-DOSSIER.pdf |
14 p. | Dossier technique A4 paysage : couverture, matériel, rôles, serveurs, tunnel, cartes | généré par dossier/ |
dossier/README.md |
16 | Comment régénérer le dossier technique | — |
ovh-manager/README.md |
24 | Comment installer un serveur dédié en pilotant le manager du fournisseur dans Safari | — |
Par où commencer ?
MACLUSTR-PROCEDURE.mdpour la règle du jeu,INVENTAIRE-MACLUSTR.mdpour connaître les machines,MACLUSTR-TUNNEL.mdpour publier un site.
🧰 Index des outils
Wrappers de ligne de commande
Trois scripts courts à la racine, à lancer depuis le poste de l'opérateur.
| Outil | Lignes | Rôle |
|---|---|---|
mld |
21 | Relaie toute commande mld à la passerelle M1M32 par SSH, puis rapatrie une copie du registre (cluster-registry.json, ignorée par git). Fournit en plus mld stage <dossier-local> <app> : rsync d'un dossier local vers le staging de la passerelle, avec exclusions par défaut (.git, node_modules, .next, .venv) et prise en charge d'un fichier .mldignore |
mlt |
43 | MacLustr Tunnel depuis le poste : état des pairs et des routes, raccordement d'un Mac au hub, ajout / redirection / retrait d'une route publique |
mlmobile |
5 | Client du coordinateur des nœuds mobiles (iPhone) : délègue au CLI du dépôt maclustr-mobile |
Commandes principales
# mld — orchestrateur (détail : README du dépôt maclustr-dispatch)
mld scan | mld nodes # ressources + runtimes de chaque nœud
mld apps | mld status --live # manifestes + état réel des apps
mld plan [apps…] # plan de placement global
mld stage <dossier-local> <app> # créer une app : poste → staging de la passerelle
mld deploy <app> [--node X] # staging → nœud choisi, santé, registre
mld move <app> [--to X] # migration avec rollback automatique
# mlt — tunnel public
mlt status # pairs WireGuard + routes publiques
mlt peer <alias> [<alias>…] # raccorde un Mac au hub
mlt add <domaine> <alias>:<port> # expose https://<domaine> → nœud (TLS automatique)
mlt redirect <domaine> <cible> # redirection (apex → www)
mlt rm <domaine> | mlt ls | mlt ssh
# mlmobile — nœuds mobiles
mlmobile nodes | ping | info | fetch URL | run script.js
mlmobile map script.js items.json | fetch-list urls.txt | jobs | job ID maclustr-tunnel/ — références de la passerelle publique
Copies de référence de ce qui tourne sur la passerelle du tunnel. La source de vérité est la passerelle elle-même : ces fichiers sont à resynchroniser après toute modification là-bas.
| Fichier | À quoi il sert |
|---|---|
tunnelctl |
Outil de la passerelle (123 lignes) : peer add / rm / ls, add <domaine> <alias>:<port>… [--no-tls] [--websocket] (répartition de charge et contrôle de santé s'il y a plusieurs upstreams), redirect, rm, ls, status, json |
Caddyfile |
Configuration globale de Caddy 2 ; chaque site est un fichier importé, écrit par tunnelctl |
errors/down.html · errors/unknown.html |
Pages d'erreur MacLustr : nœud injoignable, domaine inconnu |
gateway-setup.sh |
Transforme un Ubuntu 24.04 fraîchement installé en passerelle : hub WireGuard, Caddy, ufw, tunnelctl, pages d'erreur |
wg-node-setup.sh |
Installe WireGuard sur un Mac et le raccorde au hub (LaunchDaemon) ; affiche la clé publique à enregistrer |
wg-forward-setup.sh |
Expose sur l'interface WireGuard d'un Mac des services qui n'écoutent qu'en local : un relais socat par port, en LaunchDaemon |
ipmap |
Carte alias → adresse fixe dans le réseau du tunnel |
hub-BHS64.pub · hub-R9128.pub |
Clés publiques WireGuard des hubs (le second hub a été retiré le 2026-10-02) |
migrate-watch.sh |
Surveille une liste de domaines et crée la route dès que le DNS pointe vers la passerelle, puis vérifie en HTTPS |
ngrok-retire.sh · ngrok-map.txt · sites-ngrok.txt |
Outils et listes de la migration ngrok → tunnel (historique, migration terminée le 2026-09-10) |
operateur/ — transfert d'un poste d'opérateur
| Script | À quoi il sert |
|---|---|
export-connaissances.sh |
Exporte dans une archive protégée la connaissance Claude Code et l'accès au cluster du poste courant. --mcp inclut la configuration des serveurs MCP (qui contient des jetons) ; --vers-cluster-skill copie les instructions, la mémoire et les commandes dans operateur/connaissances/ — jamais les jetons |
installer-operateur.sh |
Installe sur un nouveau Mac l'accès et les connaissances depuis l'archive (ou depuis le clone avec --depuis-cluster-skill) ; idempotent, sauvegarde l'existant |
autoriser-operateur.sh |
Autorise — ou retire avec --retirer — la clé publique d'un opérateur sur tous les nœuds et sur la passerelle du tunnel |
Mode d'emploi complet : TRANSFERT-OPERATEUR.md.
ovh-manager/ — installation d'un serveur dédié
Automatisation du manager web du fournisseur par JavaScript injecté dans Safari (JXA). Prérequis : Safari connecté au manager et « Autoriser JavaScript des événements Apple » activé.
| Fichier | À quoi il sert |
|---|---|
runjs.sh |
Exécute un fichier JS dans l'onglet Safari au premier plan et affiche le résultat |
inspect.js · net.js |
Lecture de la fiche du serveur et de sa configuration réseau |
install.js · modal.js · os.js · next.js · step.js |
Parcours de l'assistant d'installation (bouton, liste des systèmes, choix d'Ubuntu Server 24.04, étapes) |
fill-bhs128.js · fill-bhs128b.js · verify.js · valider.js |
Remplissage du formulaire (nom d'hôte, clé publique, script de post-installation), vérification, lancement |
prog.js · wait-bhs128.sh · wait-bhs128b.sh |
Suivi de la progression, puis attente du marqueur de fin de post-installation |
postinstall.sh |
Post-installation commune : clés publiques du cluster, paquets de base, fuseau horaire, marqueur |
dossier/ — dossier technique PDF
| Fichier | À quoi il sert |
|---|---|
build.py |
Génère cover.html et body.html à partir de INVENTAIRE-MACLUSTR.md, data.json et live.json |
print.mjs |
Rendu PDF par Playwright / Chromium (couverture pleine page + corps paginé) |
cover.html · body.html · dossier.css |
Gabarits générés et feuille de style |
data.json · live.json |
Export de l'inventaire du site vitrine et instantané de son API live |
map.png · map-eu.png |
Cartes (1540 × 1242) intégrées au dossier |
Autres fichiers
| Fichier | À quoi il sert |
|---|---|
cluster-gateway.sh |
Staging et diffusion d'un projet de calcul : push, stage, fanout, list, where, clean (documenté dans GATEWAY.md) |
release-maclustr-macos.sh |
Chaîne de release de l'app macOS MacLustr : build, signature, DMG, notarisation sur un nœud, rapatriement (--install, --skip-build) |
inventaire-maclustr.css · inventaire.css |
Feuilles de style d'impression des inventaires (A4 paysage) |
cluster-deployments.json |
Ancien registre des déploiements (historique, apps retirées) — remplacé par le registre de mld ; ne plus l'alimenter |
.gitignore |
Exclut la copie locale du registre, les sauvegardes *.bak, les journaux de migration et les PDF intermédiaires |
🗂 Arborescence
cluster-skill/
├── MACLUSTR-PROCEDURE.md # procédure standard remote-first
├── NODES.md / NODES.pdf # inventaire de travail
├── INVENTAIRE-MACLUSTR.md/.pdf # inventaire présentable
├── INVENTAIRE-MACS.md/.pdf # inventaire par emplacement (historique)
├── MACLUSTR-TUNNEL.md # tunnel public
├── TRANSFERT-OPERATEUR.md # transfert d'un poste d'opérateur
├── KA-REMOTE-DEV.md # développement sur les nœuds (Groupe Ka)
├── GATEWAY.md # diffusion de projets de calcul
├── MACLUSTR-DOSSIER.pdf # dossier technique (14 p.)
├── mld · mlt · mlmobile # wrappers CLI
├── cluster-gateway.sh # staging / diffusion de calcul
├── release-maclustr-macos.sh # release de l'app macOS
├── inventaire*.css # styles d'impression
├── cluster-deployments.json # ancien registre (historique)
├── maclustr-tunnel/ # 14 fichiers : tunnelctl, Caddyfile, scripts WireGuard, pages d'erreur
├── operateur/ # 3 scripts : export, installation, autorisation
├── ovh-manager/ # 17 fichiers : pilotage du manager en JXA
└── dossier/ # 10 fichiers : générateur du dossier technique🚀 Utilisation
# miroir en lecture sur le poste de l'opérateur
git clone gitsrv:srv/git/cluster-skill.git ~/Desktop/Cluster/cluster-skill
git -C ~/Desktop/Cluster/cluster-skill pull # avant chaque session
# les wrappers supposent des alias SSH déjà configurés (passerelle, nœuds, tunnel)
~/Desktop/Cluster/cluster-skill/mld status --live
~/Desktop/Cluster/cluster-skill/mlt statusPrérequis du poste : ssh, rsync, python3, une clé SSH autorisée sur le cluster (voir operateur/), et le dépôt maclustr-mobile pour mlmobile. Plusieurs documents citent d'anciens chemins (~/Desktop/cluster-skill) : le chemin courant du miroir est ~/Desktop/Cluster/cluster-skill.
🧭 Règle remote-first
Depuis le 2026-10-02, tout composant MacLustr se modifie sur son nœud propriétaire, jamais sur le poste de l'opérateur. Résumé du tableau de MACLUSTR-PROCEDURE.md :
| Composant | Nœud propriétaire | Mise en service |
|---|---|---|
Orchestrateur mld |
M1M32 ~/maclustr-dispatch |
immédiate |
agentd |
M4M64a ~/maclustr-agentd |
relance du service launchd |
| cluster-skill (ce dépôt) | M1M32 ~/cluster-skill |
git pull sur les postes |
| MacLustr Tunnel | BHS64 | copie de référence maclustr-tunnel/ à resynchroniser |
Manifestes et registre mld |
M1M32 ~/dispatch/ |
hors git |
| Applications déployées | le nœud indiqué par mld status |
build + redémarrage sur le nœud, puis git push depuis le nœud |
| Applications Apple (Xcode) | exception : poste de l'opérateur | scripts de release |
La seule écriture autorisée depuis un poste est l'export operateur/export-connaissances.sh --vers-cluster-skill.
🖨 Régénérer les PDF
# inventaire présentable (pandoc + WeasyPrint)
pandoc INVENTAIRE-MACLUSTR.md -s --css inventaire-maclustr.css -o /tmp/i.html \
&& cp inventaire-maclustr.css /tmp/ \
&& weasyprint /tmp/i.html INVENTAIRE-MACLUSTR.pdf
# dossier technique : voir dossier/README.md
# build.py → cover.html + body.html → print.mjs (Playwright) → fusion (PyMuPDF) → MACLUSTR-DOSSIER.pdfMettre à jour INVENTAIRE-MACLUSTR.md avant toute régénération qui suit un ajout ou un retrait de machine.
⚙️ Variables d'environnement
| Variable | Outil | Rôle | Défaut |
|---|---|---|---|
MLT_GW |
mlt |
passerelle visée (équivalent de -g) |
BHS64 |
MLT_PUB_BHS64 |
mlt |
clé publique WireGuard du hub | contenu de maclustr-tunnel/hub-BHS64.pub |
MLMOBILE_URL |
mlmobile |
URL du coordinateur des nœuds mobiles | coordinateur sur M4M64a |
PUBLIC_IP |
tunnelctl |
adresse publique de la passerelle | lue dans /etc/maclustr-tunnel/public_ip |
🔒 Sécurité et confidentialité
- Ce README ne contient volontairement aucun identifiant ni aucune adresse : les machines y sont désignées par alias et par rôle.
- Le dépôt, lui, est un dépôt d'exploitation interne : plusieurs documents et scripts décrivent le réseau en détail (adressage, numéros de série, identifiants de contrat). Ils sont à traiter comme confidentiels.
INVENTAIRE-MACLUSTR.md/.pdfetMACLUSTR-DOSSIER.pdfsont les versions présentables, rédigées sans identifiants de connexion.- Les manifestes d'applications et le registre
mld(qui portent les variables d'environnement des apps) vivent hors git, sur la passerelle. - Les seules clés présentes dans le dépôt sont des clés publiques (SSH, WireGuard). Les clés privées WireGuard sont générées sur chaque machine.
operateur/export-connaissances.shn'exporte jamais les jetons des serveurs MCP vers le dépôt.- Aucun secret ne doit être ajouté à ce dépôt : un mot de passe se lit à l'exécution depuis un fichier protégé de la passerelle, jamais depuis un fichier suivi.
🗺 État du dépôt
- Dépôt créé sur spbgit le 2026-10-02 ; dépôt de travail sur M1M32.
- Infrastructure au dernier inventaire : 29 Mac sur le LAN, plus aucun Mac loué (retirés le 2026-09-25), une seule passerelle publique (BHS64) depuis le 2026-10-02.
- Parties historiques conservées pour mémoire : migration ngrok (
maclustr-tunnel/ngrok-*,sites-ngrok.txt), second hub (hub-R9128.pub),INVENTAIRE-MACS.*,cluster-deployments.json, scriptsovh-manager/propres à des serveurs retirés. - Dépôt lié : maclustr-dispatch (code de
mld).
👤 Auteur et licence
Simon-Pierre Boucher — contact@spboucher.ai · forge : git.spboucher.ai
Le dépôt ne contient pas de fichier de licence : tous droits réservés.