Daniel Allaire
aab1bcc83a
README reduit au role du projet et au demarrage rapide. docs/architecture.md (schemas Mermaid), docs/setup.md, docs/usage.md (154 cibles en 13 familles), docs/README.md (index). Documents ranges en conception/, exploitation/, hebergement/, projet/ ; 598 chemins suivis. QUICKSTART.md, SOLUTION.md, architecture-set-ops.md et la carte fondus puis retires. Preuves : P48 lit l'index et conception/mecanismes.md ; les gardes parcourent docs/ sous- dossiers compris (_documents) ; usage.md suit le Makefile dans les deux sens. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
121 lines
6.8 KiB
Markdown
121 lines
6.8 KiB
Markdown
# Documentation de Set-OPS
|
|
|
|
> **Pour qui :** tout lecteur qui cherche une page. On entre par sa **situation** ou par son
|
|
> **rôle** ; chaque document dit en tête à qui il s'adresse.
|
|
|
|
## Portes d'entrée
|
|
|
|
| Document | Contenu |
|
|
|---|---|
|
|
| [`architecture.md`](architecture.md) | composants, moteur / site / locataire, plan → déploiement, réseau, sécurité (schémas) |
|
|
| [`setup.md`](setup.md) | prérequis, instance, voûtes, Proxmox, gabarit, premier déploiement |
|
|
| [`usage.md`](usage.md) | conventions, variables, toutes les commandes `make` par famille |
|
|
|
|
## Par situation
|
|
|
|
| Ta situation | Ta porte |
|
|
|---|---|
|
|
| « Je veux **monter** mon écosystème sur ma grappe Proxmox » | [`setup.md`](setup.md) |
|
|
| « Je **prête mon matériel** à quelqu'un qui déploiera dessus » | [`hebergement/preparer-un-site-hebergeur.md`](hebergement/preparer-un-site-hebergeur.md) |
|
|
| « Je vais **implanter un locataire existant sur un site neuf** » | [`hebergement/implanter-un-tenant-sur-un-site.md`](hebergement/implanter-un-tenant-sur-un-site.md) |
|
|
| « Je viens d'**hériter** d'un écosystème déployé, je dois l'exploiter » | [`../wiki/Reprendre-l-écosystème.md`](../wiki/Reprendre-l-%C3%A9cosyst%C3%A8me.md) |
|
|
| « Je fais face à une **situation d'exploitation** » | [`exploitation/runbooks-exploitation.md`](exploitation/runbooks-exploitation.md) |
|
|
| « Je dois **modifier** le moteur » | [`conception/mecanismes.md`](conception/mecanismes.md), puis `AGENTS.md` |
|
|
| « J'**apprends** le métier » | [`../wiki/Home.md`](../wiki/Home.md) |
|
|
| « J'**évalue** Set-OPS » | [`projet/pouvoirs-set-ops.md`](projet/pouvoirs-set-ops.md), [`projet/ecosysteme-chezlepro.md`](projet/ecosysteme-chezlepro.md) |
|
|
|
|
## Par lecteur
|
|
|
|
### `conception/` — le mainteneur : comment le moteur est fait
|
|
|
|
| Document | Sujet |
|
|
|---|---|
|
|
| `mecanismes.md` | les mécanismes transverses et où ils vivent ; maturité, dette, discipline |
|
|
| `plan-et-generation.md` | le plan, ses registres, la génération de l'inventaire |
|
|
| `meta-classe.md` | pourquoi on écrit *un* plan et pas *un* inventaire |
|
|
| `conception-contextes.md` | site et locataire : deux classes, un contrat |
|
|
| `multi-instances.md` | le moteur et ses écosystèmes, le seed `index` |
|
|
| `filiation-emancipation.md` | ce que le site prête au locataire, et comment il s'en détache |
|
|
| `depots-prives-conception.md` | chaque runner ne lit que ses dépôts |
|
|
| `nomenclature-vm.md` | noms de VM et VMID |
|
|
| `dimensionnement-ressources.md` | RAM, CPU, disque dérivés des empreintes |
|
|
| `intrants-communs.md` | valeurs partagées par tout l'écosystème |
|
|
| `intrants-base-gui-conception.md` | le panneau « Intrants de base » du GUI |
|
|
| `bindings-conception.md` | relations service → service et service → base |
|
|
| `integrations-vm.md` | les intégrations `client_*` posées sur toutes les VM |
|
|
| `flux-conception.md` | déclarer un flux réseau dans `meta/flux.yml` |
|
|
| `registre-flux.md` | la matrice d'audit des flux (**générée** par `make flux`) |
|
|
| `schemas-flux.md` | la liste des pages publiées et ce qu'elles montrent |
|
|
| `sdn-evpn.md` | le réseau overlay : zones EVPN, VNets |
|
|
| `frontiere-opnsense.md` | la bordure nord/sud |
|
|
| `frontiere-physique-virtuel.md` | physique et virtuel : qui possède quoi, et où ça vit |
|
|
| `dns-interne.md` | DNS interne et public, deux sites (schémas) |
|
|
| `identite-sso.md` | les deux couches de l'identité |
|
|
| `authentification.md` | la doctrine d'authentification, rôle par rôle |
|
|
| `courriel-conception.md` | le service de courriel |
|
|
| `supervision-conception.md` | les verdicts, vers Icinga |
|
|
| `metriques-conception.md` | les séries, vers Prometheus et Grafana |
|
|
|
|
### `exploitation/` — l'exploitant : faire tourner un écosystème
|
|
|
|
| Document | Sujet |
|
|
|---|---|
|
|
| `runbooks-exploitation.md` | que faire, situation par situation |
|
|
| `devis-services.md` | ce qui tourne correspond-il à ce qui est déclaré ? |
|
|
| `vm-lifecycle.md` | ce qu'une VM traverse, de la création à la destruction |
|
|
| `procedure-template-debian13-proxmox.md` | fabriquer le gabarit d'or |
|
|
| `gabarit-debian13-justification.md` | ce que le gabarit contient, et pourquoi |
|
|
| `config-proxmox.md` | raccorder le moteur à la grappe |
|
|
| `acces-administration.md` | le tunnel nominatif des administrateurs : par où, avec quelle clé |
|
|
| `autorisation.md` | habilitations ; §6 : le runbook de reprise |
|
|
| `sortir-les-cles-du-poste.md` | les clés et les voûtes hors du poste |
|
|
| `theme-forgejo-hors-flotte.md` | le thème Alliance Boréale sur une forge hors flotte |
|
|
|
|
### `hebergement/` — l'hébergeur et le locataire
|
|
|
|
| Document | Sujet |
|
|
|---|---|
|
|
| `preparer-un-site-hebergeur.md` | mettre son matériel à disposition |
|
|
| `implanter-un-tenant-sur-un-site.md` | le jour de l'intervention sur un site neuf |
|
|
| `hebergeur-exploitation.md` | les services que l'hébergeur se doit à lui-même |
|
|
| `migration-tenant.md` | déplacer un locataire d'un hébergeur à un autre |
|
|
| `remise-au-client.md` | remettre un écosystème à qui en est responsable |
|
|
| `responsabilites-locataire-hebergeur.md` | qui répond de quoi |
|
|
|
|
### `projet/` — décisions, maturité, positionnement
|
|
|
|
| Document | Sujet |
|
|
|---|---|
|
|
| `decisions-architecture.md` | les décisions en vigueur et renversées, et ce qui les garde |
|
|
| `catalogue-services.md` | ce que le moteur sait déployer, et sa maturité |
|
|
| `positionnement.md` | ce qui reste maison, ce qui s'adopte, et à quels seuils ; la licence |
|
|
| `pouvoirs-set-ops.md` | ce que le moteur sait faire, et ce qu'il ne sait pas |
|
|
| `ecosysteme-chezlepro.md` | un écosystème réel, pour le lecteur externe |
|
|
| `MISE-A-JOUR-CODEX-CLAUDE.md` | pour l'agent IA qui reprend le dépôt |
|
|
|
|
## Registres et preuves
|
|
|
|
| Fichier | Rôle |
|
|
|---|---|
|
|
| `couches-deploiement.yml` | les couches de déploiement — lu par `scripts/orchestrer.py` |
|
|
| `dependances-groupes.yml` | le graphe des dépendances entre groupes — lu par l'orchestrateur et les preuves |
|
|
| `runbooks-construction.yml` | les runbooks de construction — lu par `scripts/runbooks.py` |
|
|
| `audit/affirmations.md` | le registre des affirmations que `make prouver` rejoue |
|
|
| `audit/preuve-<date>.md` | les rapports de preuve datés |
|
|
|
|
Le wiki (`wiki/`) est publié depuis ce dépôt vers la forge (`make wiki-publier`) : on y lit,
|
|
on écrit ici. L'autorité est `AGENTS.md` ; l'histoire, `CHANGELOG.md`.
|
|
|
|
## Le dépôt en chiffres
|
|
|
|
> Ces valeurs sont **mesurées** : **P48** les recompte et refuse tout écart.
|
|
|
|
| Ce qu'on compte | Combien | Comment on le mesure |
|
|
|---|---|---|
|
|
| rôles | 70 | `roles/*/` |
|
|
| README de rôles | 70 | `roles/*/README.md` — l'écart avec la ligne au-dessus est la dette |
|
|
| documents | 51 | `docs/**/*.md`, hors `audit/` |
|
|
| pièces d'audit | 53 | `docs/audit/*` |
|
|
| unités de wiki | 27 | `wiki/*.md` |
|
|
| décisions en vigueur | 85 | lignes `\| **D-nn** \|` de `decisions-architecture.md` |
|
|
| décisions renversées | 3 | lignes `\| **D-nn** —` du même document |
|