> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cel-eleague.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runbook exploitation

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

```bash theme={null}
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 :

```bash theme={null}
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 :

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

```bash theme={null}
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 :

```bash theme={null}
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 :

```bash theme={null}
cd web
npm run lint
npm run format:check
npm run test -- --run
npm run test:coverage
```

Backend :

```bash theme={null}
npm run test:convex
npm run test:convex:coverage
```

## Sauvegardes et restauration (vérifiées)

### Sauvegarde Convex

```bash theme={null}
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

```bash theme={null}
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 theme={null}
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)

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é)
* 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).