forked from ScoDoc/ScoDoc
322 lines
10 KiB
Markdown
322 lines
10 KiB
Markdown
|
|
# 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:
|
|
|
|
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.)
|
|
|
|
### 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.
|
|
|
|
1. Charger la dernière release depuis https://scodoc.org/git/viennet/ScoDoc/releases
|
|
|
|
2. 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
|
|
|
|
|
|
3. 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:
|
|
|
|
1. sauvegarder les données de ScoDoc7 (depuis le serveur de production);
|
|
|
|
2. installer le nouveau serveur Linux et ScoDoc 9;
|
|
|
|
3. y charger les données ScoDoc 7;
|
|
|
|
4. 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: 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 !
|
|
|
|
|
|
|