176 lines
5.4 KiB
Markdown
176 lines
5.4 KiB
Markdown
# START-HERE — Archicratie / Édition Web (v2)
|
||
> Onboarding + exploitation “nickel chrome” (DEV → Gitea → CI → Release → Blue/Green → Edge/SSO)
|
||
|
||
## 0) TL;DR (la règle d’or)
|
||
- **Gitea = source canonique**.
|
||
- **main est protégé** : toute modification passe par **branche → PR → CI → merge**.
|
||
- **Le NAS n’est pas la source** : si un hotfix est fait sur NAS, on **backporte** via PR immédiatement.
|
||
- **Le site est statique Astro** : la prod sert du HTML (nginx), l’accès est contrôlé au niveau reverse-proxy (Traefik + Authelia).
|
||
|
||
## 1) Architecture mentale (ultra simple)
|
||
- **DEV (Mac Studio)** : édition + tests + commit + push
|
||
- **Gitea** : dépôt canon + PR + CI (CI.yaml)
|
||
- **NAS (DS220+)** : déploiement “blue/green”
|
||
- `web_blue` (staging upstream) → `127.0.0.1:8081`
|
||
- `web_green` (live upstream) → `127.0.0.1:8082`
|
||
- **Edge (Traefik)** : route les hosts
|
||
- `staging.archicratie...` → 8081
|
||
- `archicratie...` → 8082
|
||
- **Authelia** devant, via middleware `chain-auth@file`
|
||
|
||
## 2) Répertoires & conventions (repo)
|
||
### 2.1 Contenu canon (édition)
|
||
- `src/content/**` : contenu MD / MDX canon (Astro content collections)
|
||
- `src/pages/**` : routes Astro (index, [...slug], etc.)
|
||
- `src/components/**` : composants UI (SiteNav, TOC, SidePanel, etc.)
|
||
- `src/layouts/**` : layouts (EditionLayout, SiteLayout)
|
||
- `src/styles/**` : CSS global
|
||
|
||
### 2.2 Annotations (pré-Édition “tickets”)
|
||
- `src/annotations/<workKey>/<slug>.yml`
|
||
- Exemple : `src/annotations/archicrat-ia/prologue.yml`
|
||
- Objectif : stocker “Références / Médias / Commentaires” par page et par paragraphe (`p-...`).
|
||
|
||
### 2.3 Scripts (tooling / build)
|
||
- `scripts/inject-anchor-aliases.mjs` : injection aliases dans dist
|
||
- `scripts/dedupe-ids-dist.mjs` : retire IDs dupliqués dans dist
|
||
- `scripts/build-para-index.mjs` : index paragraphes (postbuild / predev)
|
||
- `scripts/build-annotations-index.mjs` : index annotations (postbuild / predev)
|
||
- `scripts/check-anchors.mjs` : contrat stabilité d’ancres (CI)
|
||
- `scripts/check-annotations*.mjs` : sanity YAML + médias
|
||
|
||
> Important : les scripts sont **partie intégrante** de la stabilité (IDs/ancres/indexation).
|
||
> On évite “la magie” : tout est scripté + vérifié.
|
||
|
||
## 3) Workflow Git “pro” (main protégé)
|
||
### 3.1 Cycle standard (toute modif)
|
||
en bash :
|
||
|
||
git checkout main
|
||
git pull --ff-only
|
||
|
||
BR="chore/xxx-$(date +%Y%m%d)"
|
||
git checkout -b "$BR"
|
||
|
||
# dev…
|
||
npm i
|
||
npm run build
|
||
npm run test:anchors
|
||
|
||
git add -A
|
||
git commit -m "xxx: description claire"
|
||
git push -u origin "$BR"
|
||
|
||
### 3.2 PR vers main
|
||
|
||
Ouvrir PR dans Gitea
|
||
|
||
CI doit être verte
|
||
|
||
Merge PR → main
|
||
|
||
### 3.3 Cas spécial : hotfix prod (NAS)
|
||
|
||
On peut faire un hotfix “urgence” en prod/staging si nécessaire…
|
||
|
||
MAIS : l’état final doit revenir dans Gitea : branche → PR → CI → merge.
|
||
|
||
## 4) Déploiement (NAS) — principe
|
||
### 4.1 Release pack
|
||
|
||
On génère un pack “reproductible” (source + config + scripts) puis on déploie.
|
||
|
||
### 4.2 Blue/Green
|
||
|
||
web_blue = staging upstream (8081)
|
||
|
||
web_green = live upstream (8082)
|
||
|
||
Edge Traefik sélectionne quel host pointe vers quel upstream.
|
||
|
||
## 5) Check-list “≤ 10 commandes” (happy path complet)
|
||
### 5.1 DEV (Mac)
|
||
|
||
git checkout main && git pull --ff-only
|
||
git checkout -b chore/my-change-$(date +%Y%m%d)
|
||
|
||
npm i
|
||
rm -rf .astro node_modules/.vite dist
|
||
npm run build
|
||
npm run test:anchors
|
||
npm run dev
|
||
|
||
### 5.2 Push + PR
|
||
|
||
git add -A
|
||
git commit -m "chore: my change"
|
||
git push -u origin chore/my-change-YYYYMMDD
|
||
# ouvrir PR dans Gitea
|
||
|
||
### 5.3 Déploiement NAS (résumé)
|
||
|
||
Voir docs/runbooks/DEPLOY-BLUE-GREEN.md.
|
||
|
||
## 6) Problèmes “classiques” + diagnostic rapide
|
||
### 6.1 “Le staging ne ressemble pas au local”
|
||
|
||
# Comparer upstream direct 8081 vs 8082 :
|
||
|
||
curl -sS http://127.0.0.1:8081/ | head -n 2
|
||
curl -sS http://127.0.0.1:8082/ | head -n 2
|
||
|
||
# Vérifier quel routeur edge répond (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'
|
||
|
||
# Lire docs/runbooks/EDGE-TRAEFIK.md.
|
||
|
||
### 6.2 Canonical incorrect (localhost en prod)
|
||
|
||
Cause racine : site dans Astro = PUBLIC_SITE non injecté au build.
|
||
|
||
Fix canonique : voir docs/runbooks/ENV-PUBLIC_SITE.md.
|
||
|
||
Test :
|
||
|
||
curl -sS http://127.0.0.1:8082/ | grep -oE 'rel="canonical" href="[^"]+"' | head -1
|
||
|
||
### 6.3 Contrat “anchors” en échec après migration d’URL
|
||
|
||
Quand on déplace des routes (ex: /archicratie/archicrat-ia/* → /archicrat-ia/*), le test d’ancres peut échouer même si les IDs n’ont pas changé, car les pages ont changé de chemin.
|
||
|
||
# Procédure safe :
|
||
|
||
Backup baseline :
|
||
|
||
cp -a tests/anchors-baseline.json /tmp/anchors-baseline.json.bak.$(date +%F-%H%M%S)
|
||
|
||
Mettre à jour les clés (chemins) sans toucher aux IDs :
|
||
|
||
node - <<'NODE'
|
||
import fs from 'fs';
|
||
const p='tests/anchors-baseline.json';
|
||
const j=JSON.parse(fs.readFileSync(p,'utf8'));
|
||
const out={};
|
||
for (const [k,v] of Object.entries(j)) {
|
||
const nk = k.replace(/^archicratie\/archicrat-ia\//, 'archicrat-ia/');
|
||
out[nk]=v;
|
||
}
|
||
fs.writeFileSync(p, JSON.stringify(out,null,2)+'\n');
|
||
console.log('updated keys:', Object.keys(j).length, '->', Object.keys(out).length);
|
||
NODE
|
||
|
||
Re-run :
|
||
|
||
npm run test:anchors
|
||
|
||
## 7) Ce que l’étape 9 doit faire (orientation)
|
||
|
||
Stabiliser le pipeline “tickets → YAML annotations”
|
||
|
||
Formaliser la spec YAML + merge + anti-doublon (voir docs/EDITORIAL-ANNOTATIONS-SPEC.md)
|
||
|
||
Durcir l’onboarding (ce START-HERE + runbooks)
|
||
|
||
Éviter les régressions par tests (anchors / annotations / smoke) |