app | ||
logos | ||
misc | ||
scotests | ||
tests | ||
tools | ||
.env-exemple | ||
.gitignore | ||
.pylintrc | ||
config.py | ||
LICENSE | ||
README.md | ||
requirements-3.7.txt | ||
requirements-3.9.txt | ||
scodoc.py | ||
VERSION |
ScoDoc - Gestion de la scolarité - Version ScoDoc 9
(c) Emmanuel Viennet 1999 - 2021 (voir LICENCE.txt)
Installation: voir instructions à jour sur https://scodoc.org
Documentation utilisateur: https://scodoc.org
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 (15 août 21)
-
serveur de développement fonctionnel (tests en mode "production" sous gunicorn+nginx en cours).
-
logs à revoir (trop verbeux), dans
/opt/scodoc-data/log
En cours:
- nettoyage du code, finalisation tests et intégration.
Installation (sur Debian 11 / python 3.9.2)
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:
-
S'assurer que l'installation ScoDoc 7 est à jour
sudo su cd /opt/scodoc/Products/ScoDoc/config ./upgrade.sh
-
Arrêter le service ScoDoc 7
systemctl stop scodoc
S'assurer qu'il est bien stoppé (
ps auxw
, ...), sans quoi la migration va échouer. -
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.)
Installer ScoDoc
Sur un système Linux Debian 11, en tant que root
:
Si vous êtes développeur/testeur, partir du code git, avec git clone https://scodoc.org/git/viennet/ScoDoc.git, le renommer en
/opt/scodoc`et aller directement à l'étape 3.
-
Charger la dernière release depuis https://scodoc.org/git/viennet/ScoDoc/releases
-
Déplacer ou copier le fichier
scodoc-x.y.z.tgz
dans/opt
et le décomprimer:sudo su cd /opt; tar xf - ScoDoc-x.y.z.tgz # remplacer x.y.z par votre version mv nom_du_rep_créé /opt/scodoc
-
Lancer le script d'installation:
cd /opt/scodoc/ ./tools/install_debian11.sh
ce script crée un compte utilisateur "scodoc" s'il n'existe pas déjà.
Note: si vous installez sur une machine déjà configurée pour ScoDoc 7, il est inutile de reconfigurer la messagerie et le firewall.
Bases de données
ScoDoc 9 utilise une nouvelle base de données unique, regroupant tous les
départements et les utilisateurs. Elle est nommée SCODOC
(et SCODOC_DEV
en mode développement, ou SCODOC_TEST
pour les tests unitaires).
Cette base est créée via sqlalchemy
(l'ORM habituel de Flask).
Pour créer la base de données, lancer le script:
su scodoc # au besoin (pas root !)
cd /opt/scodoc
./tools/create_database.sh SCODOC
./tools/create_database.sh SCODOC_DEV # pour la base "developement"
./tools/create_database.sh SCODOC_TEST # pour les tests unitaires
Les bases créées appartiennent à l'utilisateur (rôle) postgres scodoc
(qui a été créé par le script d'installation précédent).
Variables d'environnement
Le serveur utilise des variables d'environnement donnant la configuration de base.
Le plus simple est de les grouper dans un fichier .env
(dans /opt/scodoc/.env
)
qui est lu automatiquement au démarrage:
# .env for ScoDoc _development_
FLASK_APP=scodoc.py
FLASK_ENV=development # ou production
MAIL_SERVER=votre.serveur.de.mail.net # ou vide si pas de mail
MAIL_PORT=25
SCODOC_ADMIN_MAIL="adresse.admin@toto.fr" # important: le mail de admin
SECRET_KEY="CGGAJAKlh6789JJK?KNAb=" # une chaine aléatoire
Le fichier /opt/scodoc/.env-exemple
est donné à titre... d'exemple. Vous pouvez faire:
# en tant qu'utilisateur scodoc
cd /opt/scodoc/
cp .env-exemple .env
nano .env # édition
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
La migration va se faire en suivant les étapes:
-
sauvegarder les données de ScoDoc7 (depuis le serveur de production);
-
installer le nouveau serveur Linux et ScoDoc 9;
-
y charger les données ScoDoc 7;
-
importer ces données dans ScoDoc 9.
Étape 1: 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
# 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 2
Installer le nouveau serveur avec Debian 11 et ScoDoc 9.
É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: le message
pg_restore: warning: restoring tables WITH OIDS is not supported anymore
est normal et anodin.
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 !