docs: README complet + RUNBOOK + CHANGELOG + export openapi.json

2026-06-20 13:06:59 +02:00
parent af00ab36cc
commit 66436629af
4 changed files with 184 additions and 23 deletions
@@ -0,0 +1,80 @@
+# RUNBOOK — Data Sentinel (déploiement & exploitation)
+
+Hébergement sur le homelab `nfteam.ovh`. Stack d'exécution :
+`~/Documents/homelab/dev/datasentinel/` (API + Front) et `~/Documents/homelab/dev/mssql/`
+(SQL Server partagé `dev-mssql`, réseau externe `dev-shared`).
+
+## Architecture
+
+| Composant | URL publique | Port interne | Conteneur |
+|-----------|--------------|--------------|-----------|
+| Front (React) | https://datasentinel.nfteam.ovh | 8086 | `datasentinel-front` |
+| API (FastAPI) | https://datasentinel-api.nfteam.ovh | 8001 | `datasentinel-api` |
+| Base | — (réseau `dev-shared`) | 1433 | `dev-mssql` (partagé) |
+
+Reverse proxy : Nginx Proxy Manager (HTTPS Let's Encrypt). CI : Gitea Actions →
+images poussées au registre `git.nfteam.ovh`, déployées par `docker compose` / Watchtower.
+
+## Déploiement / mise à jour
+
+Un push sur `main` (API ou Front) déclenche la CI (build → tests → push image).
+Récupérer la dernière image et redéployer :
+```bash
+cd ~/Documents/homelab/dev/datasentinel
+docker compose pull && docker compose up -d
+```
+Watchtower met aussi à jour automatiquement (~5 min).
+
+## Diagnostic incidents
+
+| Symptôme | Diagnostic | Résolution |
+|----------|-----------|------------|
+| Front KO | `curl -I https://datasentinel.nfteam.ovh` ; `docker logs datasentinel-front` | `docker compose restart datasentinel-front` |
+| API 5xx | `curl https://datasentinel-api.nfteam.ovh/health` → champ `database` | si `error` → voir BDD ci-dessous ; `docker logs datasentinel-api` |
+| BDD injoignable | `docker ps | grep dev-mssql` ; tester la connexion (cf. ci-dessous) | `docker compose -f ~/Documents/homelab/dev/mssql/docker-compose.yml up -d` |
+| Token invalide / 401 partout | vérifier `JWT_SECRET` dans `api.env` (ne pas le changer à chaud : invalide les sessions) | re-login |
+| Login 429 | rate-limit 5/min atteint | attendre 1 min |
+
+Connexion BDD (admin) :
+```bash
+SA=$(grep ^SA_PASSWORD= ~/Documents/homelab/dev/mssql/.env | cut -d= -f2-)
+docker run --rm --network dev-shared mcr.microsoft.com/mssql-tools \
+  /opt/mssql-tools/bin/sqlcmd -S dev-mssql -U sa -P "$SA" -d DataSentinel -Q "SELECT COUNT(*) FROM [USER];"
+```
+
+## (Re)chargement du schéma
+
+```bash
+SA=$(grep ^SA_PASSWORD= ~/Documents/homelab/dev/mssql/.env | cut -d= -f2-)
+for f in data_sentinel_init.sql data_sentinel_auth.sql; do
+  docker run --rm --network dev-shared \
+    -v ~/Documents/homelab/dev/datasentinel/sql:/sql:ro mcr.microsoft.com/mssql-tools \
+    /opt/mssql-tools/bin/sqlcmd -S dev-mssql -U sa -P "$SA" -i /sql/$f
+done
+```
+
+## Sauvegarde / restauration
+
+> ⚠️ Stratégie à finaliser avec le disque de sauvegarde dédié du homelab.
+
+Sauvegarde logique recommandée (quotidienne) :
+```bash
+SA=$(grep ^SA_PASSWORD= ~/Documents/homelab/dev/mssql/.env | cut -d= -f2-)
+docker exec dev-mssql /opt/mssql-tools*/bin/sqlcmd -S localhost -U sa -P "$SA" \
+  -Q "BACKUP DATABASE DataSentinel TO DISK='/var/opt/mssql/backup/DataSentinel.bak' WITH FORMAT, INIT, COMPRESSION"
+```
+(monter un volume `/var/opt/mssql/backup` vers le disque de sauvegarde). Le volume
+Docker `mssql_data` contient les fichiers de la base. RTO visé < 4h, RPO < 24h.
+
+## Rollback
+
+Redéployer une image précise par son tag SHA (au lieu de `latest`) :
+```bash
+# dans dev/datasentinel/docker-compose.yml : image: .../datasentinel-api:<sha>
+docker compose up -d datasentinel-api
+```
+
+## Contacts
+
+- Hébergement / infra : administrateur homelab (neckfire).
+- Application / code : A. Coyaud (auteur, dépôts GitHub).