# ScoDoc - Gestion de la scolarité - Version ScoDoc 9 (c) Emmanuel Viennet 1999 - 2021 (voir LICENCE.txt) VERSION EXPERIMENTALE - NE PAS DEPLOYER - TESTS EN COURS Installation: voir instructions à jour sur Documentation utilisateur: ## Branche ScoDoc 9 expérimentale N'utiliser que pour les développements et tests. La version ScoDoc 9 est basée sur Flask (au lieu de Zope) et sur **python 3.9+**. La version 9.0 s'efforce de reproduire presque à l'identique le fonctionnement de ScoDoc7, avec des composants logiciels différents (Debian 11, Python 3, Flask, SQLAlchemy, au lien de Python2/Zope dans les versions précédentes). **Version 9.0.0-alpha**: développement en cours, certaines pages fonctionnent, d'autres pas: merci de signaler les erreurs. ### État actuel (24 août 21) - Tests en cours, notamment système d'installation et de migration. **Non intégré** - feuille "placement" (en cours) - ancien module "Entreprises" (obsolete) ## Installation (sur Debian 11 / python 3.9.2) Expérimental: - installer Debian 11 - installer la clé: en root sur le serveur, lancer apt-get install gnupg wget -O - https://scodoc.org/misc/scodoc-repo.gpg.key | apt-key add - - apt-get update && apt-get install scodoc9 Voir https://scodoc.org/GuideInstallDebian11 ## Notes à reporter dans la doc: On peut installer à partir de zéro, ou sur une machine ayant déjà un ScoDoc 7 et migrer les données. ### Arrêter et renommer ScoDoc7 **Important**: si vous avez un ScoDoc7 installé sur ce serveur, le mettre à jour, l'arrêter et renommer son répertoire avant de commencer l'installation de ScoDoc 8: 1. S'assurer que l'installation ScoDoc 7 est à jour sudo su cd /opt/scodoc/Products/ScoDoc/config ./upgrade.sh 2. Arrêter le service ScoDoc 7 systemctl stop scodoc S'assurer qu'il est bien stoppé (`ps auxw`, ...), sans quoi la migration va échouer. 3. Renommer le répertoire de ScoDoc 7: sudo su mv /opt/scodoc /opt/scodoc7 Les données pourront être migrées après installation la nouvelle version, voir plus loin. **XXX TODO: script de migration "en place"** (actuellement, seule la migration depuis une _autre_ machine scodoc7 est prévue.) ### Initialisation de la base utilisateur par Flask En tant qu'utilisateur `scodoc`: su scodoc # si besoin cd /opt/scodoc source venv/bin/activate Puis initialisation de l'appli: flask db-init Et saisie du mot de passe `admin`: flask user-password admin On peut ensuite créer des utilisateurs tests avec: flask user-create toto Ens RT flask user-create tata Ens Info Pour créer un utilisateur "super admin", c'est à dire admin dans tous les départements: flask user-create admin1 SuperAdmin @all ## Migration d'une installation ScoDoc 7 sur un nouveau serveur C'est le cas recommandé car il minimise la coupure Dans ce cas, la migration va se faire en suivant les étapes: 1. installer le nouveau serveur Linux et ScoDoc 9; 2. sauvegarder les données de ScoDoc7 depuis le serveur de production et l'arrêter; 3. y charger les données ScoDoc 7; 4. importer ces données dans ScoDoc 9. ### Étape 1 Installer le nouveau serveur avec Debian 11 et ScoDoc 9. Voir https://scodoc.org/GuideInstallDebian11 ### Étape 2: sauvegarde des données du serveur ScoDoc 7 Se connecter en tant que `root`sur le serveur ScoDoc 7. cd /opt/scodoc/Products/ScoDoc/config # Mise à jour indispensable pour avoir le script de migration ./upgrade.sh # Arrêt du service en production systemctl stop scodoc # Export des données ./save_scodoc7_data.sh /tmp/sauvegarde-scodoc7 Attention à l'espace disque: au besoin, faire le ménage ou montez un disque supplémentaire. Le script indique le nom du fichier à transférer, qui sera dans cet exemple `/tmp/sauvegarde-scodoc7.tgz` Copier ce fichier sur le nouveau serveur. ### Étape 3 Charger les données ScoDoc 7: en tant qu'utilisateur "`scodoc`" cd /opt/scodoc ./tools/restore_scodoc7_data.sh /tmp/sauvegarde-scodoc7.tgz (adaptez l'argument si les données ont été copiées ailleurs) Note: les messages d'erreur comme pg_restore: warning: restoring tables WITH OIDS is not supported anymore pg_restore: error: could not execute query: ERROR: schema "public" already exists pg_restore: error: could not execute query: ERROR: must be owner of extension plpgsql sont normaux et a priori anodins. A ce stade, vous avez rechargé les bases ScoDoc 7 mais il faut encore les convertir vers la nouvelle structure ScoDoc 9. ### Étape 4 Importer les données dasn ScoDoc 9: les formats des bases ayant changé l'opération est complexe et peut durer plusieurs minutes (ou dizaines de minutes). Il faut lancer le script en tant que `root`, par exemple ainsi: sudo migrate_from_scodoc7.sh /tmp/sauvegarde-scodoc7 (le script de l'étape 3 a décompressé l'archive, d'où ici l'absence de l'extension `tgz`). ## Création d'un nouveau département su scodoc # si besoin cd /opt/scodoc source venv/bin/activate flask create-dept DEPT où `DEPT` est le nom du département (un acronyme en majuscule, comme "RT", "GEA", ...). ### Suppression d'un département su scodoc # si besoin cd /opt/scodoc source venv/bin/activate flask delete-dept DEPT ## Lancement serveur (développement, sur VM Linux) En tant qu'utilisateur `scodoc` (pour avoir accès aux bases départements de ScoDoc7): Dans un terminal, lancer le serveur: export FLASK_APP=scodoc.py export FLASK_ENV=development flask run --host=0.0.0.0 Test avec gunicorn: gunicorn -b 0.0.0.0:8000 -w 4 scodoc:app ## Organisation des fichiers L'installation comporte les fichiers de l'application, sous `/opt/scodoc/`, et les fichiers locaux (archives, photos, configurations, logs) sous `/opt/scodoc-data`. Par ailleurs, il y a évidemment les bases de données postgresql et la configuration du système. ### Fichiers locaux Sous `/opt/scodoc-data`, fichiers et répertoires appartienant à l'utilisateur `scodoc`. Ils ne doivent pas être modifiés à la main, sauf certains fichiers de configuration sous `/opt/scodoc-data/config`. Le répertoire `/opt/scodoc-data` doit être régulièrement sauvegardé. Principaux contenus: /opt/scodoc-data /opt/scodoc-data/log # Fichiers de log ScoDoc /opt/scodoc-data/config # Fichiers de configuration .../config/logos # Logos de l'établissement .../config/depts # un fichier par département /opt/scodoc-data/photos # Photos des étudiants /opt/scodoc-data/archives # Archives: PV de jury, maquettes Apogée, fichiers étudiants ## Pour les développeurs ### Installation du code Procéder comme indiquer au début, mais au lieu de técharger une *release*, partir d'un clone git et se placer sur la branche *ScoDoc8*: sudo su cd /opt git clone https://scodoc.org/git/viennet/ScoDoc.git # (ou bien utiliser votre clone gitea so vous l'avez déjà créé !) mv ScoDoc scodoc # important ! cd /opt/scodoc git checkout ScoDoc8 ### Tests unitaires Certains tests ont besoin d'un département déjà créé, qui n'est pas créé par les scripts de tests: Lancer au préalable: flask sco-delete-dept TEST00 && flask sco-create-dept TEST00 Puis dérouler les tests unitaires: pytest tests/unit Ou avec couverture (`pip install pytest-cov`) pytest --cov=app --cov-report=term-missing --cov-branch tests/unit/* #### Utilisation des tests unitaires pour initialiser la base de dev On peut aussi utiliser les tests unitaires pour mettre la base de données de développement dans un état connu, par exemple pour éviter de recréer à la main étudianst et semestres quand on développe. Il suffit de positionner une variable d'environnement indiquant la BD utilisée par les tests: export SCODOC_TEST_DATABASE_URI=postgresql:///SCODOC_DEV" puis de les lancer normalement, par exemple: pytest tests/unit/test_sco_basic.py Il est en général nécessaire d'affecter ensuite un mot de passe à (au moins) un utilisateur: flask user-password admin **Attention:** les tests unitaires **effacent** complètement le contenu de la base de données (tous les départements, et les utilisateurs) avant de commencer ! # Paquet debian 11 Ce que le script d'installation du paquet ne fait pas: - démarrer redis `systemctl start redis` (mettre dans la doc) - démarrer le firewall (proposer script à part) ufw default deny incoming ufw default allow outgoing ufw allow ssh ufw allow https yes | ufw enable - générer les certificats auto-signés (proposer script à part) - démarrer nginx: `systemctl restart nginx` (mettre dans la doc) - mise à jour hebdomadaire (à faire) - migrations flask (à faire)