# 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 :
```sh
cd /volume2/docker/archicratie-web/current || exit 1
set -a
. ./.env
set +a
grep -nE '^PUBLIC_GITEA_(BASE|OWNER|REPO)=' .env