# Runbook — exploitation Zammad (ADVMFR)

> Procédures d'exploitation et de récupération de la stack Zammad self-hosted.
> Stack Docker, conteneurs préfixés `zammad-zammad-*` (railsserver, postgresql, nginx, redis,
> elasticsearch, memcached, scheduler, websocket, backup). Config = **seeds idempotents** dans
> `config/routing/` et `config/zammad/`.

## Cycle de vie de la stack

Depuis `infra/zammad/` :
```bash
docker compose ps                                   # état des services
docker compose up -d                                # démarrer
docker compose down                                 # arrêter
docker compose logs -f zammad-railsserver           # logs app
docker compose logs -f zammad-scheduler             # logs jobs de fond
docker restart zammad-zammad-railsserver-1          # redémarrer l'app seule
```

## Vérifier la santé

- **Endpoint santé** (token'd) : `GET /api/v1/monitoring/health_check?token=...` → `{"healthy":true}`.
  Token : Zammad UI › Settings › System › Monitoring (secret, **jamais dans le repo**).
- Script prêt à l'emploi : `infra/zammad/healthcheck.sh` (cf. Monitoring ci-dessous).
- Console Rails ad hoc :
  ```bash
  docker exec -u zammad zammad-zammad-railsserver-1 bin/rails r /tmp/script.rb
  ```

## Monitoring / alerting

- Brancher un **poller externe** (cron / UptimeRobot / healthchecks.io) sur
  `infra/zammad/healthcheck.sh` (toutes les ~5 min), qui sort non-zero si non sain →
  **alerte vers un canal surveillé**.
- L'endpoint remonte surtout : **boîtes IMAP/SMTP cassées** et **jobs de fond en échec** (le risque
  silencieux #1 : un mail de devis qui ne rentre plus).
- **Doit être live au plus tard à la bascule `advmfr.com`** (Phase 6).
- Décision en attente (poller + destination d'alerte) : cf. `docs/decisions-advmfr.md`.

## Incident : une boîte IMAP ne polle plus  *(le plus probable)*

Symptômes : plus de nouveaux tickets sur une adresse ; health-check `healthy:false` ;
Channels en erreur dans l'UI.
1. UI › Channels › Email : repérer le compte en rouge, lire le message d'erreur.
2. Cause fréquente : mot de passe boîte changé/expiré côté hébergeur → mettre à jour le mot de
   passe du compte dans l'UI (ou rejouer `config/routing/seed_email_channels.rb` avec le bon
   secret en env, jamais en clair dans le repo).
3. Vérifier la connexion (le compte repasse vert) et qu'un mail de test crée bien un ticket.

## Sauvegarde / restauration

- **Backups prod** : conteneur `zammad-backup` (planifiés) + copie offsite chiffrée + **test de
  restauration** régulier (cf. `docs/prod-readiness.md` Phase 0).
- **Save point rapide (dev/itération)** : `infra/zammad/snapshot.sh {snapshot|list|restore <file>}`
  (pg_dump, dumps gitignorés). Après un `restore` : relancer
  `docker exec -u zammad zammad-zammad-railsserver-1 bin/rails searchindex:rebuild`.

## Réappliquer la config (seeds)

Tous les réglages sont versionnés et **idempotents**. Pour (re)poser la config :
```bash
docker cp config/zammad/<seed>.rb zammad-zammad-railsserver-1:/tmp/seed.rb
docker exec -u zammad zammad-zammad-railsserver-1 bin/rails r /tmp/seed.rb
```
Seeds : `config/routing/` (channels, triggers, roles) · `config/zammad/` (calendar+SLA, signatures+
text modules, branding, macros, writing assistant). Les secrets (mots de passe IMAP, clé Anthropic)
se saisissent dans l'UI / via env, **jamais commités**.

## Upgrade Zammad — procédure

1. **Épingler `VERSION`** dans `infra/zammad/.env` (ne jamais flotter sur `latest`).
2. **Backup d'abord** (et vérifier qu'une restauration fonctionne).
3. Lire les **release notes** Zammad : breaking changes, reindex Elasticsearch requis ?
4. Monter **un palier mineur à la fois**.
5. Activer le **mode maintenance** pendant la fenêtre (Settings › System › Maintenance) puis le
   désactiver.
6. `docker compose pull && docker compose up -d` ; suivre les logs `zammad-railsserver`.
7. **Smoke test** : login ; envoi/réception sur les 7 canaux ; un brouillon IA (Writing Assistant) ;
   un trigger de routage qui se déclenche ; un SLA visible.
8. **Réappliquer les seeds** pour réasserter la config si besoin.
9. **Rollback** = restaurer le backup + ré-épingler la version précédente.
10. Cadence : revue des correctifs ~mensuelle.

## Contacts / escalade

- À compléter : admin Zammad, contact hébergeur (mailboxes/DNS), responsable IT ADVMFR.