ScoDoc/README.md

254 lines
7.7 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
## TODO
2021-07-13 09:38:31 +02:00
- import/export Excel