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

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 — quatre VM, le minimum souverain : PKI (step-ca), DNS interne (PowerDNS), edge TLS (nginx) et magasin courriel (Dovecot). C'est un magasin de boîtes, pas un relais : le MTA (serveur_postfix) s'ajoute ensuite, comme les autres 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).

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 »)

Les chemins ci-dessous disent production/ parce que c'est le nom que porte le modèle que tu viens de copier. Ce n'est pas un nom imposé : le moteur cherche principal d'abord, production ensuite. Si tu lis ailleurs <inventaire>, c'est cette place-là.

• 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

make config                 # renseigne API host/user/port, nœud, stockage, VMID du template...

Chaque paramètre demandé est expliqué dans docs/config-proxmox.md. Tous tes secrets (token API + vault_*) vont dans une voûte unique par instance : instance/inventories/production/group_vars/all/vault.yml, à partir du gabarit exemples/vault.exemple.yml, chiffrée avec ansible-vault.

Une voûte, une clé (depuis le 2026-08-28). Le mot de passe de ta voûte se dépose dans un fichier dont le nom est dérivé du dossier de ton instance, en minuscules :

# instance dans ../mon-instance  ->  clé dans ~/.config/setops-vault-mon-instance
install -m 600 /dev/null ~/.config/setops-vault-mon-instance
$EDITOR ~/.config/setops-vault-mon-instance     # ta phrase de passe, une seule ligne
python3 scripts/voutes.py etat                  # vérifie que le moteur la trouve

Il n'y a rien à exporter : le Makefile construit ANSIBLE_VAULT_IDENTITY_LIST en appelant scripts/voutes.py. Un seul ANSIBLE_VAULT_PASSWORD_FILE ne suffirait plus de toute façon — créer une VM ouvre deux voûtes dans la même exécution : la tienne, et celle de l'hébergeur qui détient le jeton Proxmox.

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 :

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. Son nom doit être celui que make config a enregistré comme nom logique du modèle — modeleSetOPS par défaut (proxmox_clone_source_nom). Un nom qui ne correspond pas se solde par un clonage qui ne trouve pas sa source. 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

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) :

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 :

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

make inventaire-verifier    # registres + inventaire + garde-fous
make verifier               # + ansible-lint + --syntax-check

Ces cibles chargent l'inventaire complet : pose d'abord la clé de ta voûte (étape 4), 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.