diff --git a/README.md b/README.md index b17799fee..369f674ee 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ (c) Emmanuel Viennet 1999 - 2024 (voir LICENCE.txt). -Installation: voir instructions à jour sur +Installation: voir instructions à jour sur Documentation utilisateur: @@ -23,7 +23,7 @@ Flask, SQLAlchemy, au lien de Python2/Zope dans les versions précédentes). ### Lignes de commandes -Voir [https://scodoc.org/GuideConfig](le guide de configuration). +Voir [le guide de configuration](https://scodoc.org/GuideConfig). ## Organisation des fichiers @@ -41,45 +41,41 @@ Ils ne doivent pas être modifiés à la main, sauf certains fichiers de configu 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 - +``` +/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 -Installer ScoDoc 9 normalement ([voir la doc](https://scodoc.org/GuideInstallDebian11)). +Installer ScoDoc 9 normalement ([voir la doc](https://scodoc.org/GuideInstallDebian12)). Puis remplacer `/opt/scodoc` par un clone du git. +```bash +sudo su +mv /opt/scodoc /opt/off-scodoc # ou ce que vous voulez +apt-get install git # si besoin +git clone https://scodoc.org/git/ScoDoc/ScoDoc.git /opt/scodoc +# (ou bien utiliser votre clone gitea si vous l'avez déjà créé !) - sudo su - mv /opt/scodoc /opt/off-scodoc # ou ce que vous voulez - apt-get install git # si besoin - cd /opt - git clone https://scodoc.org/git/viennet/ScoDoc.git - # (ou bien utiliser votre clone gitea si vous l'avez déjà créé !) - - # Renommer le répertoire: - mv ScoDoc scodoc - - # Et donner ce répertoire à l'utilisateur scodoc: - chown -R scodoc.scodoc /opt/scodoc - +# Donner ce répertoire à l'utilisateur scodoc: +chown -R scodoc:scodoc /opt/scodoc +``` 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 - +```bash +# 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 - +```bash +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`. @@ -88,11 +84,11 @@ exemple pour travailler en mode "développement" avec `FLASK_ENV=development`. Les tests unitaires utilisent normalement la base postgresql `SCODOC_TEST`. Avant le premier lancement, créer cette base ainsi: - - ./tools/create_database.sh SCODOC_TEST - export FLASK_ENV=test - flask db upgrade - +```bash +./tools/create_database.sh SCODOC_TEST +export FLASK_ENV=test +flask db upgrade +``` Cette commande n'est nécessaire que la première fois (le contenu de la base est effacé au début de chaque test, mais son schéma reste) et aussi si des migrations (changements de schéma) ont eu lieu dans le code. @@ -100,17 +96,17 @@ migrations (changements de schéma) ont eu lieu dans le code. 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 delete-dept -fy TEST00 && flask create-dept TEST00 - +```bash +flask delete-dept -fy TEST00 && flask create-dept TEST00 +``` Puis dérouler les tests unitaires: - - pytest tests/unit - +```bash +pytest tests/unit +``` Ou avec couverture (`pip install pytest-cov`) - - pytest --cov=app --cov-report=term-missing --cov-branch tests/unit/* - +```bash +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 @@ -119,43 +115,43 @@ développement dans un état connu, par exemple pour éviter de recréer à la m Il suffit de positionner une variable d'environnement indiquant la BD utilisée par les tests: - - export SCODOC_TEST_DATABASE_URI=postgresql:///SCODOC_DEV - +```bash +export SCODOC_TEST_DATABASE_URI=postgresql:///SCODOC_DEV +``` (si elle n'existe pas, voir plus loin pour la créer) puis de les lancer normalement, par exemple: - - pytest tests/unit/test_sco_basic.py - +```bash +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 - +```bash +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 "message explicatif....." - flask db upgrade - +```bash +flask db migrate -m "message explicatif....." +flask db upgrade +``` Ne pas oublier de d'ajouter le script de migration à git (`git add migrations/...`). **Mémo**: séquence re-création d'une base (vérifiez votre `.env` ou variables d'environnement pour interroger la bonne base !). +```bash +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) - 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 - +# puis imports: +flask import-scodoc7-users +flask import-scodoc7-dept STID SCOSTID +``` 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. @@ -163,23 +159,23 @@ positionner à la bonne étape. ### Profiling Sur une machine de DEV, lancer - - flask profile --host 0.0.0.0 --length 32 --profile-dir /opt/scodoc-data - +```bash +flask profile --host 0.0.0.0 --length 32 --profile-dir /opt/scodoc-data +``` le fichier `.prof` sera alors écrit dans `/opt/scodoc-data` (on peut aussi utiliser `/tmp`). Pour la visualisation, [snakeviz](https://jiffyclub.github.io/snakeviz/) est bien: - - pip install snakeviz - +```bash +pip install snakeviz +``` puis - - snakeviz -s --hostname 0.0.0.0 -p 5555 /opt/scodoc-data/GET.ScoDoc......prof - +```bash +snakeviz -s --hostname 0.0.0.0 -p 5555 /opt/scodoc-data/GET.ScoDoc......prof +``` ## Paquet Debian 12 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 +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