ScoDoc-Lille/README.md

160 lines
5.2 KiB
Markdown
Raw Normal View History

2020-09-25 23:03:44 +02:00
2021-08-17 11:13:05 +02:00
# ScoDoc - Gestion de la scolarité - Version ScoDoc 9
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
2021-08-25 22:56:36 +02:00
Installation: voir instructions à jour sur <https://scodoc.org/GuideInstallDebian11>
2020-09-25 23:03:44 +02:00
Documentation utilisateur: <https://scodoc.org>
2021-08-25 22:56:36 +02:00
## Version ScoDoc 9
2021-05-29 18:22:51 +02:00
2021-08-25 22:56:36 +02:00
La version ScoDoc 9 est basée sur Flask (au lieu de Zope) et sur
**python 3.9+**.
2021-06-21 14:54:40 +02:00
2021-08-17 11:13:05 +02:00
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).
2021-06-21 14:54:40 +02:00
2021-08-25 22:56:36 +02:00
### État actuel (26 sept 21)
2021-06-21 14:54:40 +02:00
- 9.0 reproduit l'ensemble des fonctions de ScoDoc 7 (donc pas de BUT), sauf:
2021-06-21 14:54:40 +02:00
2021-08-25 22:56:36 +02:00
**Fonctionnalités non intégrées:**
2021-06-21 14:54:40 +02:00
- génération LaTeX des avis de poursuite d'études
2021-08-24 17:35:39 +02:00
- ancien module "Entreprises" (obsolete)
2021-07-10 13:55:35 +02:00
2021-08-18 18:53:45 +02:00
2021-08-25 22:56:36 +02:00
### Lignes de commandes
2021-08-24 09:22:14 +02:00
2021-08-25 22:56:36 +02:00
Voir [https://scodoc.org/GuideConfig](le guide de configuration).
2021-08-24 09:22:14 +02:00
2021-08-15 10:42:08 +02:00
## Organisation des fichiers
2021-08-25 22:56:36 +02:00
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 Linux.
### 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
2021-08-25 22:56:36 +02:00
Installer ScoDoc 9 normalement ([voir la doc](https://scodoc.org/GuideInstallDebian11)).
2021-08-26 15:35:08 +02:00
Puis remplacer `/opt/scodoc` par un clone du git.
2021-07-30 17:46:18 +02:00
sudo su
2021-08-27 10:41:22 +02:00
mv /opt/scodoc /opt/off-scodoc # ou ce que vous voulez
2021-08-26 15:35:08 +02:00
apt-get install git # si besoin
2021-07-30 17:46:18 +02:00
cd /opt
git clone https://scodoc.org/git/viennet/ScoDoc.git
2021-08-26 15:35:08 +02:00
# (ou bien utiliser votre clone gitea si vous l'avez déjà créé !)
2021-07-30 17:46:18 +02:00
mv ScoDoc scodoc # important !
2021-08-27 10:41:22 +02:00
Il faut ensuite installer l'environnement et le fichier de configuration:
# Le plus simple est de piquer le virtualenv configuré par l'installeur:
mv /opt/off-scodoc/venv /opt/scodoc
Et la config:
ln -s /opt/scodoc-data/.env /opt/scodoc
Cette dernière commande utilise le `.env` crée lors de l'install, ce qui
n'est pas toujours le plus judicieux: vous pouvez modifier son contenu, par
exemple pour travailler en mode "développement" avec `FLASK_ENV=development`.
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:
2021-08-26 15:35:08 +02:00
export SCODOC_TEST_DATABASE_URI=postgresql:///SCODOC_DEV
2021-08-12 14:01:37 +02:00
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 !
#### Modification du schéma de la base
On utilise SQLAlchemy avec Alembic et Flask-Migrate.
flask db migrate -m "ScoDoc 9.0.x: ..." # ajuster le message !
flask db upgrade
Ne pas oublier de commiter les migrations (`git add migrations` ...).
Mémo pour développeurs: séquence re-création d'une base:
dropdb SCODOC_DEV
tools/create_database.sh SCODOC_DEV # créé base SQL
flask db upgrade # créé les tables à partir des migrations
flask sco-db-init # ajoute au besoin les constantes (fait en migration 0)
# puis imports:
flask import-scodoc7-users
flask import-scodoc7-dept STID SCOSTID
2021-09-11 15:59:06 +02:00
Si la base utilisée pour les dev n'est plus en phase avec les scripts de
migration, utiliser les commandes `flask db history`et `flask db stamp`pour se
positionner à la bonne étape.
2021-08-24 16:18:00 +02:00
# Paquet debian 11
2021-09-11 15:59:06 +02:00
Les scripts associés au paquet Debian (.deb) sont dans `tools/debian`. Le plus
important est `postinst`qui se charge de configurer le système (install ou
upgrade de scodoc9).
La préparation d'une release se fait à l'aide du script
`tools/build_release.sh`.
2021-08-24 16:18:00 +02:00