SPB Git

Repository Public

README.md 23.7 KB

# 🧭 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.

type licence règle site

Markdown Bash Python JavaScript WireGuard Caddy Ubuntu macOS Playwright Pandoc

commits dernier commit activité langage langages taille branches tags clones

documents pdf wrappers scripts tunnel ovh

Macs cœurs RAM passerelle tunnel


# Sommaire


# 📌 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, mlt et mlmobile, 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.md pour la règle du jeu, INVENTAIRE-MACLUSTR.md pour connaître les machines, MACLUSTR-TUNNEL.md pour 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
bash
# 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

text
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

bash
# 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 status

Pré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

bash
# 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.pdf

Mettre à 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 / .pdf et MACLUSTR-DOSSIER.pdf sont 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.sh n'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, scripts ovh-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.

Files main
Menu

Theme