Set-OPS-Public/docs/setup.md

# Installation et configuration

> **Pour qui :** l'exploitant qui monte son premier écosystème sur une grappe Proxmox. Le
> résumé est dans le [README](../README.md) ; ce document donne chaque étape, ses fichiers
> et ses pièges. Préparer le matériel d'un hébergeur est un autre parcours :
> [`hebergement/preparer-un-site-hebergeur.md`](hebergement/preparer-un-site-hebergeur.md).

## Prérequis

| Quoi | Détail |
|---|---|
| Grappe Proxmox | droits d'administration, API joignable depuis le poste |
| Jeton d'API Proxmox | utilisateur `ansible@pve` ou équivalent |
| Poste de pilotage | Linux, Python 3, Ansible, `make`, `git` ; `node` optionnel (garde JS du GUI) |
| Paire de clés SSH | la publique est injectée dans les VM par cloud-init |
| Phrase de passe de voûte | une par écosystème |

## 1. Cloner le moteur

```bash
git clone <url-de-Set-OPS> Set-OPS && cd Set-OPS
```

## 2. Créer l'instance

Une instance est un dépôt frère du moteur, créé depuis un modèle. Le dépôt public fournit
`socle` : PKI (step-ca), DNS interne (PowerDNS), edge TLS (nginx), magasin de courriel
(Dovecot). Les modèles assemblés par offre sont dans le dépôt privé `Set-OPS-modeles`
(`SETOPS_MODELES` les rend visibles).

```bash
make instance-modeles                          # modèles disponibles
make instance-creer NOM=OPS-MonOrg MODELE=socle   # crée ../OPS-MonOrg ; INDEX=<n> fixe le seed
ln -s ../OPS-MonOrg instance                   # l'instance active (ou : make instance-utiliser NOM=OPS-MonOrg)
make instances                                 # écosystèmes découverts, collisions d'index
```

`instance-creer` refuse un `index` déjà pris par un écosystème voisin : tout l'adressage en
dérive. Il ne bascule pas le lien `instance/` et ne fait pas `git init`.

## 3. Renseigner l'instance

`<inventaire>` est `principal` ou, à défaut, `production` (le nom que porte le modèle).

| Fichier | Valeur |
|---|---|
| `instance/inventories/<inventaire>/group_vars/all/10-intrants.yml` | `domaine_interne` (ex. `monorg.internal`) |
| `instance/plan/nomenclature.yml` | `index` (seed) et supernet |
| `instance/plan/domaines.yml` | domaine public, `autorite`, `edge` |
| `instance/plan/serveurs.yml` | placement Proxmox : nœud, stockage, disque, mémoire, cœurs |

Le GUI (`make inventaire-ui`) édite les mêmes registres. Valeurs communes :
[`conception/intrants-communs.md`](conception/intrants-communs.md).

## 4. Proxmox

```bash
make config      # API, nœud, stockage, VMID et nom du gabarit
```

Chaque paramètre : [`exploitation/config-proxmox.md`](exploitation/config-proxmox.md).
Les identifiants Proxmox appartiennent à l'hébergeur : ils vivent dans **sa** voûte (celle
de l'underlay), pas dans celle du locataire.

## 5. Voûtes et clés

Une voûte par dépôt, chiffrée par `ansible-vault`, depuis le gabarit
[`exemples/vault.exemple.yml`](../exemples/vault.exemple.yml) :
`instance/inventories/<inventaire>/group_vars/all/vault.yml`.

Une clé par voûte, dans un fichier nommé d'après le dossier de l'écosystème, en minuscules :

```bash
install -m 600 /dev/null ~/.config/setops-vault-ops-monorg
$EDITOR ~/.config/setops-vault-ops-monorg      # la phrase de passe, une ligne
python3 scripts/voutes.py etat                  # le moteur trouve-t-il chaque clé ?
```

Rien à exporter : le `Makefile` construit `ANSIBLE_VAULT_IDENTITY_LIST` avec
`scripts/voutes.py`. Créer une VM ouvre deux voûtes dans la même exécution (locataire et
hébergeur) : un seul `ANSIBLE_VAULT_PASSWORD_FILE` ne suffit pas.

Les clés n'existent que sur le poste. Les sortir sur un support chiffré :
[`exploitation/sortir-les-cles-du-poste.md`](exploitation/sortir-les-cles-du-poste.md).

## 6. Gabarit Debian 13 (une fois par grappe)

Créer une VM Debian 13 minimale, joignable par SSH avec clé, puis :

```bash
make preparer-modele
make verifier-modele
make nettoyer-modele CONFIRMER=true
```

Convertir la VM en gabarit Proxmox sous le nom enregistré par `make config`
(`proxmox_clone_source_nom`, `modeleSetOPS` par défaut). Un autre nom fait échouer le
clonage. Machine **q35/OVMF** : ne jamais convertir depuis i440fx.

Procédure : [`exploitation/procedure-template-debian13-proxmox.md`](exploitation/procedure-template-debian13-proxmox.md) ;
contenu justifié : [`exploitation/gabarit-debian13-justification.md`](exploitation/gabarit-debian13-justification.md).

## 7. Générer l'inventaire

```bash
make instancier                    # ce que le plan produit, en diff
make instancier-appliquer FORCE=1  # première génération seulement
make serveurs                      # VMID / IP dérivés
```

Les hôtes naissent en `etat: planifie`.

## 8. Créer et déployer

```bash
make creer-vm HOTE=infra-dns-01          # clone + cloud-init, attend que la VM réponde
# passer l'hôte en etat: actif dans instance/plan/serveurs.yml, puis :
make instancier-appliquer
make deployer HOTE=infra-dns-01          # couche par couche, dans l'ordre du graphe
```

Toute la flotte : `make flotte-creer CONFIRMER=true` puis `make deployer-tout CONFIRMER=true`,
ou `make reconstruire CONFIRMER=true` (créer puis déployer). Les déploiements ne visent que
les hôtes actifs.

## 9. Vérifier

```bash
make inventaire-verifier   # registres, inventaire, gardes
make verifier              # lint, tests, inventaire, ordre, flux, syntaxe, puis les preuves
make valider               # recette sur la flotte déployée
```

## Configuration de référence

| Élément | Rôle | Défaut |
|---|---|---|
| `instance/` | lien vers le dépôt du locataire actif | — |
| `underlay.yml` | lien vers l'underlay du site actif | `underlay.yml` à la racine |
| `ansible.cfg` | configuration Ansible du moteur | dans le dépôt |
| `.ansible/` | répertoires temporaires d'Ansible | créé par `make` |

Variables d'environnement et de `make` : [`usage.md`](usage.md).

## Pannes connues au premier montage

| Symptôme | Cause | Remède |
|---|---|---|
| `Attempting to decrypt but no vault secrets found` | clé de voûte absente ou mal nommée | étape 5, `python3 scripts/voutes.py etat` |
| `make instancier-appliquer` refuse d'écrire | diff non vide, première génération | `FORCE=1` la première fois seulement |
| le clonage ne trouve pas sa source | nom du gabarit ≠ `proxmox_clone_source_nom` | renommer le gabarit ou refaire `make config` |
| une sortie d'Ansible vide, sans erreur | Ansible exige un tube sur sa sortie | `set -o pipefail; make … < /dev/null 2>&1 \| cat` |