college-infos/docs/exploitation.md

# Exploitation de `pronote-sync`

Ce guide décrit l'installation et l'exploitation des artefacts de déploiement
fournis par le projet. Les paramètres de l'unité systemd fournie sont des
exemples d'installation : adaptez-les à l'hôte cible avant son installation.
Ne placez jamais de secret dans une unité systemd, une commande shell, un
journal ou ce document.

## Préparer l'hôte

Installez le projet et ses dépendances dans le répertoire choisi, puis créez le
fichier d'environnement référencé par l'unité à partir de `.env.example`. Il
doit rester local et lisible uniquement par le compte de service :

```bash
sudo install -d -m 0700 -o <utilisateur-service> -g <groupe-service> <repertoire-configuration>
sudo install -m 0600 -o <utilisateur-service> -g <groupe-service> .env <fichier-environnement>
```

Les unités fournies nécessitent l'interface CLI livrée au jalon M12. Avant de
les installer, vérifiez que la version installée contient bien ce point
d'entrée :

```bash
.venv/bin/pronote-sync --help
```

Avant toute activation ou mise à jour, exécutez les contrôles depuis la racine
du projet :

```bash
.venv/bin/python scripts/check_secrets.py
.venv/bin/python -m pip check
.venv/bin/pronote-sync --dry-run
```

Le contrôle des secrets doit réussir avant le déploiement. Il inspecte les
fichiers textuels de l'artefact, en excluant volontairement `.env`, les
environnements virtuels, les répertoires générés, `tests/` et
`GUIDE_DEV_PYTHON.md` ; les sentinelles et exemples de ces deux derniers ne
bloquent donc pas le déploiement. Il ne valide ni les valeurs ni les permissions
du fichier d'environnement. Pour analyser seulement le contenu indexé avant un
commit, utilisez `scripts/check_secrets.py --staged`.

Le dry-run vérifie le pipeline sans appliquer les écritures de synchronisation ;
il ne remplace pas une vérification des paramètres réellement chargés.

## Installation systemd

Les fichiers versionnés sont :

- `deploy/systemd/pronote-sync.service` ;
- `deploy/systemd/pronote-sync.timer`.

Copiez-les dans le répertoire d'unités systemd de l'hôte. Avant de les activer,
adaptez `User`, `Group`, `WorkingDirectory`, `EnvironmentFile`, les chemins des
exécutables dans `ExecStartPre` et `ExecStart`, ainsi que les chemins de
`StateDirectory`, `LogsDirectory` et `ReadWritePaths`. L'artefact fourni prend
pour exemple le compte `pronote-sync`, le code dans `/opt/pronote-sync`, l'état
dans `/var/lib/pronote-sync`, les logs dans `/var/log/pronote-sync` et le fichier
d'environnement `/etc/pronote-sync/pronote-sync.env`. Ne copiez pas de valeur
secrète dans l'unité.

```bash
sudo install -m 0644 deploy/systemd/pronote-sync.service /etc/systemd/system/
sudo install -m 0644 deploy/systemd/pronote-sync.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now pronote-sync.timer
systemctl list-timers pronote-sync.timer
```

Pour tester une exécution sans attendre la prochaine échéance :

```bash
sudo systemctl start pronote-sync.service
sudo systemctl status pronote-sync.service
```

Une exécution en échec laisse l'unité `pronote-sync.service` en état `failed`.
La supervision de l'hôte doit donc déclencher une alerte sur cet état ou sur un
échec du timer/service ; le transport de cette alerte (courriel, XMPP ou système
de supervision) relève de l'exploitation locale.

## Journaux et alertes

La configuration systemd redirige la sortie standard et la sortie d'erreur vers
`/var/log/pronote-sync/pronote-sync.log`. Consultez ce fichier ou, selon la
configuration de l'hôte, le journal de l'unité :

```bash
sudo tail -f /var/log/pronote-sync/pronote-sync.log
sudo journalctl -u pronote-sync.service --since today
sudo journalctl -u pronote-sync.service -f
systemctl status pronote-sync.timer
```

Traitez un statut non nul ou une unité `failed` comme un échec à investiguer.
Les logs applicatifs masquent les secrets configurés, mais évitez tout de même
de partager sans relecture un export de journal : une donnée sensible issue de
l'environnement ou d'un outil tiers ne doit pas être supposée sûre par défaut.

## Rotation des journaux

L'artefact `deploy/logrotate/pronote_sync` cible le fichier
`/var/log/pronote-sync/pronote-sync.log` utilisé par l'unité fournie. Installez-
le puis validez sa syntaxe avant activation :

```bash
sudo install -m 0644 deploy/logrotate/pronote_sync /etc/logrotate.d/pronote_sync
sudo logrotate --debug /etc/logrotate.d/pronote_sync
```

La rotation configurée est quotidienne, conserve sept archives et utilise
`compress` avec `delaycompress`. Elle recrée le fichier avec les droits `0640`
pour le compte de service. Si vous modifiez le chemin de journal dans l'unité,
mettez aussi à jour la règle logrotate correspondante.

## Mise à jour et retour au service

Avant de remplacer les dépendances ou le code, conservez une copie protégée du
fichier d'environnement local, sans l'ajouter au dépôt. Après la mise à jour,
réexécutez, dans cet ordre, les contrôles de secrets, de cohérence des paquets
et le dry-run :

```bash
.venv/bin/python scripts/check_secrets.py
.venv/bin/python -m pip check
.venv/bin/pronote-sync --dry-run
```

Rechargez ensuite les unités si leurs fichiers ont changé, puis vérifiez une
exécution et son journal :

```bash
sudo systemctl daemon-reload
sudo systemctl restart pronote-sync.timer
sudo systemctl start pronote-sync.service
journalctl -u pronote-sync.service -n 100 --no-pager
```

En cas d'échec, ne relancez pas automatiquement après avoir modifié des
identifiants : corrigez la configuration locale, repassez le contrôle des
secrets et le dry-run, puis consultez le journal expurgé.