Set-OPS-Public/QUICKSTART.md

# Démarrage rapide — de zéro à ton écosystème souverain

Tu débarques avec une **grappe Proxmox vierge** et tu veux monter ton écosystème
numérique. Voici le chemin, de bout en bout. Set-OPS est le **moteur** ; tu vas
créer **ton instance** à partir d'un modèle, puis déployer.

> Concepts en 10 s : tu **décris un plan** (quelles VM, quels services), le moteur
> **génère l'inventaire**, et Ansible **déploie**. Tu n'édites jamais l'inventaire
> à la main. Détails : `docs/plan-et-generation.md`.

## 0. Prérequis (à toi de fournir)
- une **grappe Proxmox** où tu es admin (API activée) ;
- une machine de pilotage Linux avec **Ansible**, **Python 3**, **make**, `git`
  (et `node` pour le garde-fou JS du GUI, optionnel) ;
- un **token API Proxmox** ;
- une **paire de clés SSH** (la publique ira dans les VM via cloud-init) ;
- un **mot de passe Ansible Vault** (pour chiffrer tes secrets).

## 1. Cloner le moteur
```bash
git clone <url-de-Set-OPS> Set-OPS && cd Set-OPS
```

## 2. Choisir un modèle et créer ton instance
Le dépôt public fournit **un modèle générique : `socle`** — le socle souverain minimal
(DNS interne, AC/PKI, edge TLS, relais courriel) sur lequel on ajoute des modules. Les
modèles **assemblés** par offre (`identite`, `observabilite`, `forge`, `collaboration`,
`presence-web`, `integral`) sont un actif à part, dans le dépôt privé `Set-OPS-modeles`
(cf. [`exemples/modeles/README.md`](exemples/modeles/README.md)).

```bash
cp -r exemples/modeles/socle ../mon-instance   # ton instance, ailleurs
ln -s ../mon-instance instance                 # le moteur la trouve via ce lien
```
*(Alternative au symlink : `export SETOPS_INSTANCE=../mon-instance`.)*

## 3. Renseigner ton instance (« tes couleurs »)
- `instance/inventories/production/group_vars/all/10-intrants.yml` → **`domaine_interne`** (ex. `monorg.internal`) ;
- `instance/plan/nomenclature.yml` → ton **supernet** (ex. `10.20.0.0/16`) ;
- `instance/plan/domaines.yml` → ton **domaine public** ;
- `instance/plan/serveurs.yml` → **placement Proxmox** (nœud, stockage, disque, mémoire, cœurs).

Tu peux aussi le faire dans le GUI plus tard (`make inventaire-ui`).

## 4. Configurer Proxmox et tes secrets
```bash
make config                 # renseigne API host/user/port, nœud, stockage, VMID du template...
```
Chaque paramètre demandé est expliqué dans [`docs/config-proxmox.md`](docs/config-proxmox.md).
Tous tes secrets (token API + `vault_*`) vont dans **une voûte unique** :
`instance/inventories/production/group_vars/all/vault.yml`, à partir du
gabarit [`exemples/vault.exemple.yml`](exemples/vault.exemple.yml), chiffrée avec
`ansible-vault`. Exporte ton mot de passe Vault, ex. :
```bash
export ANSIBLE_VAULT_PASSWORD_FILE=~/.config/setops-vault-pass
```

## 5. Construire le golden template Debian 13 (UNE seule fois)
Une grappe vierge n'a aucun template. Crée une VM **Debian 13 vanille**, rends-la
joignable par Ansible, puis :
```bash
make preparer-modele        # socle + durcissement + cloud-init + qemu-guest-agent...
make verifier-modele
make nettoyer-modele CONFIRMER=true
```
Convertis ensuite la VM en **template Proxmox** nommé `modele-debian13` (le nom de
clone source par défaut). Détails et procédure : `docs/vm-lifecycle.md` et
`docs/procedure-template-debian13-proxmox.md`.

## 6. Générer ton inventaire depuis le plan
```bash
make instancier             # montre ce que le plan produit (diff)
make instancier-appliquer FORCE=1   # 1re génération : écrit instance/inventories/production/hosts.yml
```
Tes hôtes sont là, en état `planifie`. `make serveurs` te montre leurs VMID/IP dérivés.

## 7. Créer les VM (clone du template + cloud-init)
Pour chaque hôte — `creer-vm` lit ses VMID/IP/VLAN/passerelle directement dans
l'inventaire généré (`make serveurs` te les montre) :
```bash
make creer-vm HOTE=infra-dns-01
```
*(Les valeurs de nœud/stockage/template viennent de `make config`. La création
suit désormais le plan de bout en bout : un seul argument, `HOTE`.)*

## 8. Activer puis déployer
Passe l'hôte en `etat: actif` dans `instance/plan/serveurs.yml`, régénère, déploie :
```bash
make instancier-appliquer
make deployer HOTE=infra-dns-01          # configure l'hôte selon ses groupes
# ou, par couche :
make deployer-groupe GROUPE=serveur_powerdns
```
Les déploiements de groupe ne ciblent **que** les hôtes actifs.

## 9. Ensuite : tu vis dans le plan
Édite le plan (GUI `make inventaire-ui`, ou les registres `instance/plan/`),
`make instancier-appliquer`, `make deployer`. Tu ne touches jamais `hosts.yml`.

## Valider à tout moment
```bash
make inventaire-verifier    # registres + inventaire + garde-fous
make verifier               # + ansible-lint + --syntax-check
```
> Ces cibles chargent l'inventaire complet : exporte d'abord ton mot de passe Vault
> (étape 4, `ANSIBLE_VAULT_PASSWORD_FILE`), sinon Ansible s'arrête sur
> « Attempting to decrypt but no vault secrets found ».

---

Ordre de mise en place des services : `docs/catalogue-services.md`. Modèle,
registres et règle d'or : `docs/plan-et-generation.md` et `AGENTS.md`.