6.6 KiB
RUNBOOK — Déploiement Blue/Green (NAS DS220+)
Objectif : déployer une release sans casser, avec rollback immédiat.
0) Portée
Ce runbook décrit le déploiement de l’édition web Archicratie sur NAS (Synology), en mode blue/green :
web_blue: upstream staging →127.0.0.1:8081web_green: upstream live →127.0.0.1:8082- Edge Traefik publie :
staging.archicratie.trans-hands.synology.me→ 8081archicratie.trans-hands.synology.me→ 8082
1) Pré-requis
- Accès shell NAS (user
archicratia) +sudo - Docker Compose Synology nécessite souvent :
sudo env DOCKER_API_VERSION=1.43 docker compose ...
- Les fichiers edge Traefik sont dans :
/volume2/docker/edge/config/dynamic/
2) Répertoires canon (NAS)
On considère ces chemins (adapter si besoin, mais rester cohérent) :
- Base :
/volume2/docker/archicratie-web - Releases :
/volume2/docker/archicratie-web/releases/YYYYMMDD-HHMMSS/app - Symlink actif :
/volume2/docker/archicratie-web/current→ pointe vers le.../appactif
3) Garde-fous (AVANT toute action)
3.1 Snapshot de l’état actuel
en bash :
cd /volume2/docker/archicratie-web ls -la current || true readlink current || true
3.2 Vérifier l’état live/staging upstream direct
curl -sSI http://127.0.0.1:8081/ | head -n 12 curl -sSI http://127.0.0.1:8082/ | head -n 12
3.3 Vérifier l’état edge (host routing)
curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/
| grep -iE 'HTTP/|location:|x-archi-router' | head -n 30
curl -sSI -H 'Host: archicratie.trans-hands.synology.me' http://127.0.0.1:18080/
| grep -iE 'HTTP/|location:|x-archi-router' | head -n 30
Si tu n’es pas authentifié, tu verras un 302 vers auth... : c’est normal.
4) Procédure de déploiement (release pack → nouvelle release)
4.1 Déposer le pack
Hypothèse : tu as un .tgz “release pack” (issu de release-pack.sh) dans incoming/ :
cd /volume2/docker/archicratie-web ls -la incoming | tail -n 20
4.2 Créer un répertoire release
TS="$(date +%Y%m%d-%H%M%S)" REL="/volume2/docker/archicratie-web/releases/$TS" APP="$REL/app" sudo mkdir -p "$APP"
4.3 Extraire le pack
PKG="/volume2/docker/archicratie-web/incoming/archicratie-web.tar.gz" # adapter au nom réel sudo tar -xzf "$PKG" -C "$APP"
4.4 Sanity check (fichiers attendus)
sudo test -f "$APP/Dockerfile" && echo "OK Dockerfile" sudo test -f "$APP/docker-compose.yml" && echo "OK compose" sudo test -f "$APP/astro.config.mjs" && echo "OK astro config" sudo test -f "$APP/src/layouts/EditionLayout.astro" && echo "OK layout" sudo test -f "$APP/src/pages/archicrat-ia/index.astro" && echo "OK archicrat-ia index" sudo test -f "$APP/docs/diagrams/archicratie-web-edition-global-verbatim-v2.svg" && echo "OK diagrams"
4.5 Permissions (crucial sur Synology)
But : archicratia:users doit pouvoir traverser le parent + lire le contenu.
sudo chown -R archicratia:users "$REL" sudo chmod -R u+rwX,g+rX,o-rwx "$REL" sudo chmod 750 "$REL" "$APP"
Vérifier :
ls -ld "$REL" "$APP" ls -la "$APP" | head
5) Activation : basculer current vers la nouvelle release
5.1 Backup du current existant
cd /volume2/docker/archicratie-web TS2="$(date +%F-%H%M%S)"
on backup "current" (symlink ou dossier)
if [ -e current ] || [ -L current ]; then sudo mv -f current "current.BAK.$TS2" echo "✅ backup: current.BAK.$TS2" fi
5.2 Recréer current (symlink propre)
sudo ln -s "$APP" current
ls -la current readlink current sudo test -f current/docker-compose.yml && echo "✅ OK: current/docker-compose.yml"
Si cd current échoue, c’est que current n’est pas un symlink correct OU que le parent n’est pas traversable (permissions).
6) Build & run : (re)construire web_blue/web_green
6.1 Vérifier la config compose
cd /volume2/docker/archicratie-web/current
sudo env DOCKER_API_VERSION=1.43 docker compose -f docker-compose.yml config
| grep -nE 'services:|web_blue:|web_green:|context:|dockerfile:|PUBLIC_SITE|REQUIRE_PUBLIC_SITE'
| sed -n '1,220p'
6.2 Build propre (recommandé si changement de code/config)
sudo env DOCKER_API_VERSION=1.43 docker compose build --no-cache web_blue web_green
6.3 Up (force recreate)
sudo env DOCKER_API_VERSION=1.43 docker compose up -d --force-recreate web_blue web_green
6.4 Vérifier upstream direct (8081/8082)
curl -sSI http://127.0.0.1:8081/ | head -n 12 curl -sSI http://127.0.0.1:8082/ | head -n 12
7) Tests de non-régression (MINIMAL CHECKLIST)
À exécuter systématiquement après up.
7.1 Upstreams directs
curl -sSI http://127.0.0.1:8081/ | head -n 12 curl -sSI http://127.0.0.1:8082/ | head -n 12
7.2 Canonical (anti “localhost en prod”)
curl -sS http://127.0.0.1:8081/ | grep -oE 'rel="canonical" href="[^"]+"' | head -n 1 curl -sS http://127.0.0.1:8082/ | grep -oE 'rel="canonical" href="[^"]+"' | head -n 1
Attendu :
blue (8081) → https://staging.archicratie.../
green (8082) → https://archicratie.../
7.3 Edge routing (Host header + diag)
curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/
| grep -iE 'HTTP/|location:|x-archi-router' | head -n 30
curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/_auth/whoami
| grep -iE 'HTTP/|location:|x-archi-router' | head -n 30
7.4 Smoke UI (manuel)
Home : lien “Essai-thèse — ArchiCraT-IA” → /archicrat-ia/
TOC global : liens /archicrat-ia/* (pas de préfixe /archicratie/archicrat-ia/*)
Reading-follow/TOC local : scroll ok
8) Rollback (si un seul test est mauvais)
Objectif : revenir immédiatement à l’état précédent.
8.1 Repointer current sur l’ancien backup
cd /volume2/docker/archicratie-web ls -la current.BAK.* | tail -n 5
choisir le plus récent
OLD="current.BAK.YYYY-MM-DD-HHMMSS" sudo rm -f current sudo ln -s "$(readlink -f "$OLD")" current 2>/dev/null || sudo ln -s "$(readlink "$OLD")" current
ls -la current readlink current
8.2 Rebuild + recreate
cd /volume2/docker/archicratie-web/current sudo env DOCKER_API_VERSION=1.43 docker compose build --no-cache web_blue web_green sudo env DOCKER_API_VERSION=1.43 docker compose up -d --force-recreate web_blue web_green
8.3 Re-tester la checklist (section 7)
Si rollback OK : investiguer en environnement isolé (staging upstream uniquement, ou release dans un autre current).
9) Notes opérationnelles
Ne jamais modifier dist/ “à la main” sur NAS.
Si un hotfix prod est indispensable : documenter et backporter via PR Gitea.
Le canonical dépend du build : PUBLIC_SITE doit être injecté (voir runbook ENV-PUBLIC_SITE).