DocScoDoc/README.md

271 lines
8.5 KiB
Markdown
Raw Normal View History

2020-09-25 23:03:44 +02:00
2021-06-21 14:54:40 +02:00
# ScoDoc - Gestion de la scolarité - Version ScoDoc 8
2020-09-25 23:03:44 +02:00
2021-01-01 18:40:47 +01:00
(c) Emmanuel Viennet 1999 - 2021 (voir LICENCE.txt)
2020-09-25 23:03:44 +02:00
Installation: voir instructions à jour sur <https://scodoc.org>
Documentation utilisateur: <https://scodoc.org>
2021-05-29 18:22:51 +02:00
## Branche ScoDoc 8 expérimentale
2021-07-23 14:46:12 +02:00
N'utiliser que pour les développements et tests.
2021-05-29 18:22:51 +02:00
2021-07-12 22:53:35 +02:00
La version ScoDoc8 est basée sur Flask (au lieu de Zope) et sur **python 3.7+**.
2021-06-21 14:54:40 +02:00
Elle ne sera pas mise en production, c'est une version de développement pour le passage à Python 3.
2021-08-09 23:44:34 +02:00
De très nombreux changements sont susceptibles d'affecter l'API, mais
on s'efforce à ce que rien ne soit visible des utilisateurs Web.
2021-06-21 14:54:40 +02:00
2021-07-23 14:46:12 +02:00
**Work in Progress (WIP)**: développement en cours, certaines pages fonctionnent, d'autres pas:
merci de signaler les erreurs.
2021-06-21 14:54:40 +02:00
2021-07-30 16:52:48 +02:00
### État actuel (30 juillet 21)
2021-06-21 14:54:40 +02:00
2021-07-23 13:45:56 +02:00
- serveur de développement fonctionnel (pas testé en mode "production" sous gunicorn+nginx).
2021-07-30 16:52:48 +02:00
- logs à revoir (tropverbeux), dans `/opt/scodoc-data/log`
2021-06-21 14:54:40 +02:00
- pas d'import/export excel.
2021-06-21 14:54:40 +02:00
2021-07-23 13:45:56 +02:00
2021-06-21 14:54:40 +02:00
**En cours:**
2021-07-30 16:52:48 +02:00
- nettoyage du code, finalisation tests et intégration.
2021-06-21 14:54:40 +02:00
2021-05-29 18:22:51 +02:00
2021-07-23 14:46:12 +02:00
## Installation (sur Debian 10 / python3.7)
On peut installer à partir de zéro, ou sur une machine ayant déjà un ScoDoc 7 et migrer les données.
2021-05-29 18:22:51 +02:00
2021-07-23 14:46:12 +02:00
### Installation
2021-06-21 14:54:40 +02:00
#### 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
2021-07-30 16:52:48 +02:00
sudo su
cd /opt/scodoc/Products/ScoDoc/config
./upgrade.sh
2. Arrêter le service ScoDoc 7
2021-07-30 16:52:48 +02:00
systemctl stop scodoc
S'assurer qu'il est bien stoppé (`ps auxw`, ...), sans qui la migration va échouer.
3. Renommer le répertoire de ScoDoc 7:
2021-07-30 16:52:48 +02:00
sudo su
mv /opt/scodoc /opt/scodoc7
Les données pourront être migrées après installation la nouvelle evrsion, voir plus loin.
#### Installer ScoDoc
2021-07-23 14:46:12 +02:00
Sur un système Linux Debian 10, en tant que `root`:
2021-06-21 14:54:40 +02:00
2021-07-23 14:46:12 +02:00
- Charger la dernière release depuis https://scodoc.org/git/viennet/ScoDoc/releases
2021-07-10 13:55:35 +02:00
2021-07-25 11:35:16 +02:00
- Déplacer ou copier le fichier `ScoDoc-x.y.z.tgz` dans `/opt` et le décomprimer:
2021-07-12 22:53:35 +02:00
2021-07-30 16:52:48 +02:00
sudo su
cd /opt; tar xf - ScoDoc-x.y.z.tgz # remplacer x.y.z par votre version
2021-07-12 22:53:35 +02:00
2021-07-23 14:46:12 +02:00
- Lancer le script d'installation:
2021-07-10 13:55:35 +02:00
2021-07-30 16:52:48 +02:00
cd /opt/scodoc/tools
./install_debian10.sh
2021-07-10 13:55:35 +02:00
2021-07-23 14:46:12 +02:00
ce script crée un compte utilisateur "scodoc".
2021-07-10 13:55:35 +02:00
2021-07-23 14:46:12 +02:00
Note: si vous installez sur une machine déjà configurée pour ScoDoc 7, il
est inutile de reconfigurer la messagerie et le firewall.
2021-05-29 18:22:51 +02:00
2021-07-23 14:46:12 +02:00
### Bases de données
2021-08-09 23:44:34 +02:00
ScoDoc 8.1 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).
2021-08-09 23:44:34 +02:00
### Création de la base de données
2021-07-23 14:46:12 +02:00
Lancer le script:
2021-08-09 23:44:34 +02:00
su scodoc # au besoin (pas root !)
cd /opt/scodoc
./tools/create_database.sh SCODOC_DEV # pour la base "developement"
./tools/create_database.sh SCODOC_TEST # pour les tests unitaires
2021-07-23 13:45:56 +02:00
2021-08-09 23:44:34 +02:00
Les bases créées appartiennent à l'utilisateur (role) postgres `scodoc`
(qui a été créé par le script d'installation précédent).
2021-07-30 19:52:49 +02:00
### 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
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
# comment out to use CDN:
BOOTSTRAP_SERVE_LOCAL=1
2021-07-23 13:45:56 +02:00
### Initialisation de la base utilisateur par Flask
2021-07-23 13:45:56 +02:00
En tant qu'utilisateur `scodoc`:
2021-07-23 14:46:12 +02:00
su scodoc # si besoin
2021-07-30 16:52:48 +02:00
cd /opt/scodoc
2021-07-30 17:46:18 +02:00
source venv/bin/activate
2021-08-10 00:23:30 +02:00
#flask db init
#flask db migrate -m "initial database"
#flask db upgrade
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
2021-07-05 00:14:30 +02:00
flask user-create tata Ens Info
2021-07-05 00:14:30 +02:00
ou mieux, importer les utilisateurs de ScoDoc7 avec:
flask user-db-import-scodoc7
2021-07-27 16:07:03 +02:00
(on peut le faire plus tard avec le script de migration décrit plus bas)
(Note: la base `SCOUSERS` de ScoDoc7 n'est pas affectée, ScoDoc8 utilise une base séparée, nommée `SCO8USERS`).
Pour créer un utilisateur "super admin", c'est à dire admin dans tous les départements:
flask user-create admin1 SuperAdmin @all
2021-07-23 14:46:12 +02:00
## Migration d'une installation ScoDoc 7
Le script `migrate_from_scodoc7.sh` va déplacer les donneés et reconfigurer les bases de données
de votre installation ScoDoc 7 pour passer à ScoDoc 8 (*ne pas utiliser en production !*).
**Les modifications effectuées sont sans retour: ScoDoc 7 ne fonctionnera plus !**
1. Lancer le script de migration
2021-07-23 14:46:12 +02:00
ScoDoc 8 doit avoir été installé comme expliqué plus haut.
2021-07-30 16:52:48 +02:00
sudo su
cd /opt/scodoc/tools
./migrate_from_scodoc7.sh
2021-07-23 14:46:12 +02:00
## Création d'un département
su scodoc # si besoin
cd /opt/scodoc
source venv/bin/activate
flask sco-create-dept DEPT
`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 sco-delete-dept DEPT
2021-07-05 00:14:30 +02:00
2021-05-29 18:22:51 +02:00
## Lancement serveur (développement, sur VM Linux)
2021-07-23 13:45:56 +02:00
En tant qu'utilisateur `scodoc` (pour avoir accès aux bases départements de ScoDoc7):
2021-07-21 15:53:15 +02:00
2021-07-27 14:33:11 +02:00
Dans un terminal, lancer le serveur:
2021-07-21 15:53:15 +02:00
2021-05-29 18:22:51 +02:00
export FLASK_APP=scodoc.py
export FLASK_ENV=development
flask run --host=0.0.0.0
## 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
2021-07-30 17:46:18 +02:00
## 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
2021-07-30 17:46:18 +02:00
### Tests unitaires
2021-05-29 18:22:51 +02:00
2021-07-30 16:52:48 +02:00
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:
2021-07-21 15:53:15 +02:00
pytest tests/unit
2020-09-25 23:03:44 +02:00
2021-07-31 18:01:10 +02:00
Ou avec couverture (`pip install pytest-cov`)
pytest --cov=app --cov-report=term-missing --cov-branch tests/unit/*
2021-07-30 16:52:48 +02:00
2021-08-12 14:01:37 +02:00
#### 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 !