archicratie-edition/docs/OPS-RUNBOOK-ARCHICRATIE-WEB.md

OPS Runbook — Archicratie Web (NAS Synology DS220 + Gitea)

🟦 ALIAS (résumé) — Runbook 1-page pour opérer vite sans se tromper.

La procédure détaillée canonique est : docs/DEPLOY_PROD_SYNOLOGY_DS220.md.

Source Git : Gitea/main ; déploiement = rebuild depuis main ; pas de hotfix non versionné.

Déploiement : build sur slot inactif → smoke → bascule DSM → rollback si besoin.

Incidents connus : voir docs/TROUBLESHOOTING.md.

0. Objectif

Ce document décrit la procédure exacte pour :

• maintenir un état cohérent entre Local (Mac Studio), Gitea, NAS (prod) ;
• déployer proprement une release Docker (build, smoke, bascule) ;
• éviter les régressions (branches protégées, CI bloquante, rollback).

1. Invariants (à ne jamais violer)

1. La branche main sur Gitea = vérité canonique.
2. La prod NAS doit être rebuild depuis main (pas de modifications “à la main” non versionnées).
3. Les variables PUBLIC_GITEA_* doivent pointer vers le bon owner/repo (sinon 404 / login loop).
4. En solo : PR requise OK, mais 0 approval (sinon blocage). CI doit rester bloquante.
5. Interdiction : token/secret commité dans le repo.

2. Topologie (NAS)

• Arborescence :
  • /volume2/docker/archicratie-web/releases/<timestamp>/app
  • /volume2/docker/archicratie-web/current (symlink vers release active)
• Services :
  • web_green → port local typique 127.0.0.1:8082 (smoke)
  • (optionnel) web_blue → 127.0.0.1:8081 (ancienne)
• Script :
  • /volume2/docker/archicratie-web/ops/smoke.sh <port>

3. Standard Git (Gitea)

3.1 Branches

• main : branche de travail et de déploiement (par défaut)
• master : branche legacy (archivée / conservée pour compat si nécessaire)
• Stratégie : master est soit supprimée, soit alignée sur main, mais pas utilisée comme axe actif.

3.2 Protection branches (solo recommandé)

• main :
  • ✅ Exiger PR (Require pull request)
  • ✅ 0 approval (solo)
  • ✅ Bloquer merge si CI KO (Prevent merge if checks fail)
  • ✅ Désactiver force-push
  • (optionnel) désactiver push direct (selon UI Gitea)
• master :
  • ✅ Interdire push direct
  • ✅ Désactiver force-push
  • ✅ Mention “legacy” (si UI le permet)

4. Variables d’environnement (cause n°1 des 404)

4.1 Variables publiques injectées au build

• PUBLIC_GITEA_BASE=https://gitea.archicratie.trans-hands.synology.me
• PUBLIC_GITEA_OWNER=Archicratia
• PUBLIC_GITEA_REPO=archicratie-edition

4.2 Règle d’or

• Le site génère des liens .../<OWNER>/<REPO>/issues/new?...
• Si OWNER/REPO est faux (ex: archicratia/archicratie-web) :
  • /issues peut marcher
  • MAIS /issues/new finit en 404 / redirect login / droits
  • => corriger .env et rebuild

5. Déploiement NAS (procédure protocolaire)

5.1 Pré-check

Sur NAS :

• Vérifier qu’on est bien dans /volume2/docker/archicratie-web/current
• Charger .env (pour build args)

Commandes :

cd /volume2/docker/archicratie-web/current || exit 1
set -a
. ./.env
set +a
grep -nE '^PUBLIC_GITEA_(BASE|OWNER|REPO)=' .env