​

Runbook d’exploitation CEL

​

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)

​

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

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

• 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)

​

Gestion manuelle / audit

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

​

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

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)

1. Déclencher deploy.yml manuellement sur main/master.
2. Vérifier secrets Infisical (prod) chargés en workflow.
3. Vérifier santé stack via docker compose -f docker-compose.prod.yml ps.
4. 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

• frontend via Portless : http://cel.localhost
• fallback direct : npm run dev:port puis http://localhost:3000
• auth HTTP Convex : http://127.0.0.1:3211/api

​

URLs auth (issuer unique)

• CONVEX_SITE_ORIGIN, CONVEX_SITE_URL et CONVEX_AUTH_PROVIDER_DOMAIN doivent contenir exactement la même origine : elle sert d’issuer aux JWT Convex Auth.
• Cette origine doit être joignable depuis l’hôte et le conteneur backend. Avec un port host remappé, utiliser http://host.docker.internal:<port-auth-host> ; Compose résout ce nom vers host-gateway dans Docker.
• SITE_URL désigne le frontend. CUSTOM_AUTH_SITE_URL désigne l’origine de callback OAuth côté navigateur.

​

Secrets et Infisical

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

​

Tests de maintenance

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

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

​

Sauvegarde PostgreSQL du compose (service postgres-backup)

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

​

Checklist opérationnelle (CI + prod + ops)

1. Vérifier branches et déclencheur de workflow.
2. Vérifier variables/runtime via secrets / env (selon contexte).
3. Lancer/valider tests.
4. Vérifier backup récent (si changement DB).
5. Déployer par deploy.yml (manuel) si nécessaire.
6. Confirmer health checks et logs.
7. 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é)
• événements et erreurs PostHog reçus si l’intégration est configurée
• vérification des crons principaux
• backup Cron planifié actif

​

Écarts opératoires restant à traiter

• scripts/healthcheck.sh, scripts/monitor-prod.sh et scripts/monitor-prod-rich.sh référencent encore des services de monitoring absents de docker-compose.prod.yml.
• Certains scripts de restauration/monitoring utilisent des noms de conteneurs ou ports historiques ; vérifier chaque cible contre le compose avant usage.

• Les adresses de tunnel Cloudflare publiques exactes (cel-eleague.com, api.cel-eleague.com) en prod.
• La présence effective d’un alerting externe 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).