Opérations - Kare API Documentation

Runbooks

Geste	Comment
Déployer sur staging	Automatique au merge sur `main` si `STAGING_AUTO_DEPLOY_ENABLED=true`. Manuel : `Deploy (manual)` → `target`
Revenir en arrière	`Rollback` → `target` + `image_tag` SHA7 existant
Ajouter un front à un stage	`deploy.yml` avec `seed-<app>`, puis `tofu apply` revu, puis `front-` / `pair-`
Changer l’infra ou la config d’un container	`make plan` → `make show-plan` → `make apply` dans `infrastructure/`
Ajouter un domaine	Le déclarer dans `envs/staging`, appliquer, puis mettre à jour le CNAME chez le propriétaire DNS
Migration DB	Écrire des migrations expand/contract ; elles s’appliquent au déploiement, avant le flip d’image
Seeder un compte de test	`Seed staging (manual)` — voir Seed staging
Créer le premier opérateur BO	`make bootstrap-bo-admin EMAIL=<operateur>@akord-securite.fr`
Sauvegarder la base	`make backup-postgres BACKUP_DIR=<chemin sûr>` — conserver dump + checksum hors repo
Restaurer	`make restore-postgres-drill DUMP=<fichier>` pour prouver le dump ; `make restore-postgres-live` écrase la base staging
Vérifier un stage	`make verify-stage` : readiness, isolation CORS par audience, frontière de stockage, spoofing de rate-limit
Vérifier les credentials	`make credential-status` (expirations, métadonnées non-secrètes)

make restore-postgres-live détruit tout ce qui a été écrit depuis le dump. Le drill (restore-postgres-drill) restaure dans une base scratch et la supprime ensuite — c’est celui à utiliser pour tester.

Jobs planifiés

Workflow	Cadence	Effet
`backup-drill`	mardis 02:15 UTC	dump de la base staging, puis restauration prouvée dans une base scratch de la même instance, supprimée ensuite. `pg_restore --list` ne lit que la table des matières : il ne prouve rien
`registry-gc`	lundis 03:30 UTC	nettoie le registry. Préserve les tags récents, les alias, les tags jeunes et tout tag actuellement configuré sur un container. Dispatch manuel : `keep` (10 par défaut) et `dry_run` (`true` par défaut)
`stale`	quotidien 01:30 UTC	hygiène des PR
`publish-docs`	push `main` sur `openapi/**`	pousse `api/` et `changelog/` vers ce repo de doc

backup-drill tourne sur le pool kare-api : son adresse est celle présente dans l’ACL de la base, un runner hébergé par GitHub n’atteindrait pas l’endpoint public.

Secrets et variables GitHub

Portés par l’Environment staging (un workflow qui vise staging ne peut pas lire les secrets d’un autre environment).

Secrets

Secret	Rôle
`SCW_CI_ACCESS_KEY` / `SCW_CI_SECRET_KEY`	clé CI du stage : push registry, update container, lecture des secrets
`SCW_PROJECT_ID` / `SCW_ORGANIZATION_ID`	identifiants Scaleway
`SCW_STATE_ACCESS_KEY` / `SCW_STATE_SECRET_KEY`	projet `kare-state`, backend S3 du state
`NEXT_SERVER_ACTIONS_ENCRYPTION_KEY`	consommé au build BuildKit d’`audit`, `kare` et `provider`
`HEROUI_AUTH_TOKEN`	dist HeroUI Pro sous licence, requis par `kare` et `provider`
`SENTRY_AUTH_TOKEN`	upload des sourcemaps
`E2E_EMAIL` / `E2E_PASSWORD`	compte dédié de la suite Playwright
`KARE_DOCS_APP_ID` / `KARE_DOCS_APP_PRIVATE_KEY`	GitHub App qui pousse sur `kare-docs`
`DEPLOY_WEBHOOK_URL`	notification de déploiement, optionnelle

Variables

Variable	Rôle
`STAGING_AUTO_DEPLOY_ENABLED`	interrupteur de l’auto-deploy ; doit valoir exactement `true`
`NEXT_PUBLIC_API_URL_{RS,BACKOFFICE,AUDIT,PROVIDER}`	URL API par front — chaque front parle à son audience
`NEXT_PUBLIC_URL_RS` / `NEXT_PUBLIC_WS_URL_RS`	URL publique et WebSocket du front `kare` (`wss://api.rs.staging.kare-app.fr/rs/ws`)
`NEXT_PUBLIC_API_GATEWAY_API_KEY_RS`	clé de gateway du front `kare`
`NEXT_PUBLIC_SENTRY_DSN_{RS,BACKOFFICE,AUDIT,PROVIDER}`	DSN Sentry par front
`SENTRY_ORG` / `SENTRY_PROJECT_{RS,BACKOFFICE,AUDIT,PROVIDER}`	un slug d’organisation partagé, un projet par front
`E2E_KARE` / `E2E_API_URL`	activation de la suite Playwright

Les secrets runtime de l’API (DATABASE_URL, clés S3, SMTP…) ne vivent pas dans GitHub : ils sont dans Scaleway Secret Manager, lus au démarrage du container. make sync-secrets ne pousse que la clé CI active vers l’Environment GitHub.

Les images de front cuisent les NEXT_PUBLIC_* au build : elles sont donc spécifiques à un stage et doivent être reconstruites par stage. Les sourcemaps et les releases Sentry utilisent le SHA complet correspondant au tag d’image immuable.

Gouvernance du repo

Garde-fou	Rôle
Protection de `main`	PR obligatoire, `CI Status` requis, pas de push direct
Protection des tags `v*`	restreint qui peut tagger une version
`CODEOWNERS`	review d’un owner sur `infrastructure/` et `.github/`
Git hooks	lint / format / types sur les fichiers stagés avant commit — jamais `--no-verify`
Environment `prod`	required reviewers : c’est l’approbation humaine de toute release