archicratie-edition/docs/OPS-SYNC-TRIPLE-SOURCE.md

OPS-SYNC-TRIPLE-SOURCE — Mac Studio / Gitea / NAS (prod)

Dernière mise à jour : 2026-02-01

Ce document décrit la synchronisation sans ambiguïté entre :

• Local (Mac Studio) : édition / écriture / préparation PR
• Gitea : vérité canonique (branche main)
• NAS Synology DS220+ : déploiement (blue/green) à partir de main

---

0) Invariants (à ne jamais violer)

1. Gitea main = source de vérité.
2. Le NAS ne doit pas “inventer” du code : pas d’édition manuelle non versionnée en prod (sauf hotfix temporaire immédiatement reporté dans une PR).
3. Le bouton “Proposer” dépend de PUBLIC_GITEA_* : une valeur fausse → 404 / redirect login / mauvais repo.
4. Les secrets (tokens) ne doivent jamais entrer dans le repo : .env* ignorés, token injecté uniquement via variable d’environnement locale/CI.

---

1) Topologie réelle (ce que nous avons)

1.1 Local (Mac Studio)

• Dev et documentation.
• Git complet.
• On fait : branches, commits, push, PR, merge.

1.2 Gitea

• Repo canonique : Archicratia/archicratie-edition.
• main = défaut + protégée.
• Toute modif arrive via PR.

1.3 NAS (prod)

• Chemin canonique :
  • /volume2/docker/archicratie-web/releases/<timestamp>/app
  • /volume2/docker/archicratie-web/current → symlink vers la release active
• Blue/Green :
  • web_blue sur 127.0.0.1:8081
  • web_green sur 127.0.0.1:8082
• Reverse proxy DSM : bascule 8081 ↔ 8082.

---

2) Règle d’or : qui écrit quoi, où ?

2.1 Toute écriture “source” se fait sur Mac Studio

• Code Astro
• Scripts
• Docs docs/*.md
• .gitignore

2.2 Gitea ne reçoit que via PR

• Push sur branche feature/docs
• PR → CI → merge

2.3 NAS ne fait que :

• git reset --hard origin/main (alignement)
• build image + restart slot blue/green
• smoke test
• bascule reverse proxy DSM

---

3) Procédure standard (la seule à utiliser)

Étape A — Mac Studio → Gitea (PR)

1. git checkout -b feat/... ou docs/...
2. commits propres et atomiques
3. git push -u origin <branch>
4. PR dans Gitea → CI OK → merge dans main

Étape B — NAS : aligner current sur origin/main

Sur NAS, git n’est pas forcément installé : on utilise un conteneur git. en sh :

APP="/volume2/docker/archicratie-web/current" U_ID="$(id -u)"; G_ID="$(id -g)"

sudo docker run --rm --network host
-u "$U_ID:$G_ID" -e HOME=/tmp
-v "$APP":/repo -w /repo
--entrypoint sh alpine/git -lc ' set -eu git config --global --add safe.directory /repo git config http.sslVerify false

git fetch origin --prune git checkout -B main git reset --hard origin/main git status -sb '

Étape C — NAS : rebuild du slot inactif + smoke + bascule

Rebuild de l’image (slot inactif recommandé).

docker compose up -d --force-recreate --no-build web_green (ou blue)

smoke test via script ou curl

bascule DSM vers le port du slot actif

4) Checkpoints rapides (sanity)

4.1 Vérifier que NAS = origin/main

git rev-parse --short HEAD sur NAS (via alpine/git)

doit égaler origin/main.

4.2 Vérifier “Proposer” (points minimum)

PUBLIC_GITEA_OWNER=Archicratia (casse sensible)

PUBLIC_GITEA_REPO=archicratie-edition

Flow : Proposer → choix 1 → choix 2 → onglet Gitea /issues/new?... OK

5) Rollback

DSM reverse proxy : repasser sur l’autre port (8081/8082).

En cas de code cassé : réaligner NAS sur origin/main précédent (tag/release) ou repointer /current vers une release précédente.