Runbook d’exploitation CEL

Ce runbook regroupe les procédures opérationnelles en cohérence avec le code actuel (Workflows + scripts + compose).

Références (lecture)

DEPLOYMENT.md
.github/workflows/*
docker-compose.prod.yml
convex/README.md
convex/admin/crons.ts
README.md
scripts/*.sh

Chaîne CI/CD de production (réelle)

Workflow	Déclencheur	Périmètre
`pipeline.yml`	`pull_request`	Lint web + lint Convex + tests + build web.
`deploy.yml`	`workflow_dispatch`	Déploiement production manuel (self-hosted macOS).
`release.yml`	`push` (`master`, `main`)	Versioning auto via semantic-release, sans déploiement.
`docs.yml`	PR sur `docs/**`, package json	Validation Mintlify + liens docs.
`dependency-health.yml`	`workflow_dispatch`, cron	Audit de dépendances web.
`codeql.yml`	cron hebdo	Analyse sécurité TypeScript en lot.

Séparation claire

La CI (pipeline) valide la qualité.
Le versioning (release.yml) met à jour package.json/web/package.json et crée tag + release.
Le déploiement production est uniquement manuel (deploy.yml).
Les docs ont leur propre validation (docs.yml) et ne poussent pas l’infra.

Infrastructure production réelle

Services définis dans docker-compose.prod.yml :

postgres
pgbouncer
postgres-backup
convex-backend
convex-dashboard
web
cloudflared
portainer

Notes d’exploitation :

deploy.yml exécute docker compose -f docker-compose.prod.yml pull puis up -d de services de base.
Health checks intégrés après déploiement : Convex backend, web, auth HTTP, tunnel cloudflared.
rollback automatique du web en cas d’échec de déploiement ; rollback Convex via npx convex deploy sur commit précédent quand l’admin key est disponible.

Crons et jobs opérationnels

Crons Convex actifs (gestion runtime)

convex/admin/crons.ts définit les identifiants et horaires par défaut suivants :

Cron ID	Côté scheduler	Calendrier par défaut
`match-auto-validation`	`@convex-dev/crons`	`0 0 * * *`
`match-ea-score-sync`	`@convex-dev/crons`	`/30 20-23 * 1-5`
`person-sanction-lifecycle-maintenance`	`@convex-dev/crons`	`/15 * * *`
`transfer-lifecycle-maintenance`	`@convex-dev/crons`	`/15 * * *`
`stripe-premium-entitlements-reconcile`	`@convex-dev/crons`	`0 2 * * *`

Gestion manuelle / audit

Liste des configs crons : listCronConfigs
Historique exécutions : listCronExecutions
MAJ config : upsertCronConfig
Déclenchement manuel : triggerCron

initCrons supprime aussi user-ban-expiration-cleanup et totw-weekly si présents.

Commandes opératoires (backend)

cp .env.convex.example .env.convex
npm install
npm run convex:selfhosted:up
npm run convex:selfhosted:admin-key
npm run convex:env:sync
npm run convex:dev:once

Commandes utiles :

npm run convex:selfhosted:down
npm run convex:selfhosted:logs
npm run convex:selfhosted:health
npm run convex:dev
npm run convex:codegen
npm run convex:env:sync

Déploiement (manuel)

Procédure supportée par le workflow :

Déclencher deploy.yml manuellement sur main/master.
Vérifier secrets Infisical (prod) chargés en workflow.
Vérifier santé stack via docker compose -f docker-compose.prod.yml ps.
Sur succès, confirmer la disponibilité frontend, Convex backend et tunnel.

Frontend local

cd web
npm install
cp .env.example .env.local
npm run dev

URLs locales :

frontend : http://localhost:3000
auth HTTP Convex : http://127.0.0.1:3211/api

URLs auth (distinction navigateur / backend)

Browser-facing (hébergé) : CONVEX_CLOUD_ORIGIN, CONVEX_SITE_ORIGIN, NEXT_PUBLIC_DEPLOYMENT_URL, CUSTOM_AUTH_SITE_URL
Interne backend : SITE_URL, CONVEX_SITE_URL, CONVEX_AUTH_PROVIDER_DOMAIN

Si ports host remappés, seuls les premiers basculent vers les ports exposés ; les seconds restent sur les ports internes attendus par Convex Auth.

Secrets et Infisical

Commandes :

npm run secrets:upload
npm run secrets:upload:dev
npm run secrets:upload:prod
npm run secrets:download
npm run secrets:download:dev
npm run secrets:download:prod

Ne jamais versionner de fichiers .env*.

Tests de maintenance

Frontend :

cd web
npm run lint
npm run format:check
npm run test -- --run
npm run test:coverage

Backend :

npm run test:convex
npm run test:convex:coverage

Sauvegardes et restauration (vérifiées)

Sauvegarde Convex

npm run convex:backup
npm run convex:backup:storage
npm run convex:backup:pg
npm run convex:backup:cron:install

convex:backup crée backups/convex/<timestamp>/convex-export.zip
backups/convex/latest pointe vers la dernière exécution
nettoyage géré par --retention-days

Restauration Convex

npm run convex:restore -- --latest --yes
npm run convex:restore -- --latest --append --yes

⚠️ --append = import incrémental, réservé aux cas de lineage compatible.

Sauvegarde PostgreSQL du compose (service `postgres-backup`)

Scripts opérables :

bash scripts/backup-list.sh
bash scripts/restore-backup.sh <backup-file-from-/backups>

Le workflow de restauration PG arrête le service web pendant la restauration, puis le relance.

Checklist opérationnelle (CI + prod + ops)

Vérifier branches et déclencheur de workflow.
Vérifier variables/runtime via secrets / env (selon contexte).
Lancer/valider tests.
Vérifier backup récent (si changement DB).
Déployer par deploy.yml (manuel) si nécessaire.
Confirmer health checks et logs.
Vérifier statut crons applicatifs si incident métier.

Post-déploiement

frontend accessible
auth OK (login/refresh)
Convex backend HTTP OK
webhook/feedback (si configuré)
alerting de base actif
vérification des crons principaux
backup Cron planifié actif

Écarts doc↔code à signaler (sans correction ici)

Certains documents plus anciens attribuent à pipeline.yml un déclencheur push (par ex. .github/workflows/README.md et sections héritées).
Des références à preprod, monitoring stack étendu et QUICK_START.md sont documentées dans d’autres fichiers mais non présentes dans le code / fichiers réels.
scripts/monitor-prod.sh cible des noms/ports de services différents de docker-compose.prod.yml (ex. cel-backend-1, 4211) — à auditer avant usage.

Hors vérification (non vérifié dans cette passe) :

Les adresses de tunnel Cloudflare publiques exactes (cel-eleague.com, api.cel-eleague.com) en prod.
La présence effective d’alerting externe (Grafana/Telegram/Slack) côté infra opérationnelle.
Le statut d’activation quotidien des sauvegardes via crontab machine (le script d’installation convex-backup-cron-install est présent).

​Runbook d’exploitation CEL

​Références (lecture)

​Chaîne CI/CD de production (réelle)

​Séparation claire

​Infrastructure production réelle

​Crons et jobs opérationnels

​Crons Convex actifs (gestion runtime)

​Gestion manuelle / audit

​Commandes opératoires (backend)

​Déploiement (manuel)

​Frontend local

​URLs auth (distinction navigateur / backend)

​Secrets et Infisical

​Tests de maintenance

​Sauvegardes et restauration (vérifiées)

​Sauvegarde Convex

​Restauration Convex

​Sauvegarde PostgreSQL du compose (service postgres-backup)

​Checklist opérationnelle (CI + prod + ops)

​Post-déploiement

​Écarts doc↔code à signaler (sans correction ici)