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 :

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 :

.venv/bin/pronote-sync --help

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

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

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 :

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é :

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 :

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 :

.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 :

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