ScoDoc/README.md

#            ScoDoc - Gestion de la scolarité - Version ScoDoc 8

(c) Emmanuel Viennet 1999 - 2021 (voir LICENCE.txt)


Installation: voir instructions à jour sur <https://scodoc.org>

Documentation utilisateur: <https://scodoc.org>

## Branche ScoDoc 8 expérimentale

N'utiliser que pour les développements et tests.

La version ScoDoc8 est basée sur Flask (au lieu de Zope) et sur **python 3.7+**.
Elle ne sera pas mise en production, c'est une version de développement pour le passage à Python 3.

De très nombreux changements sont susceptibles d'affecter l'API, mais 
on s'efforce à ce que rien ne soit visible des utilisateurs Web.

**Work in Progress (WIP)**: développement en cours, certaines pages fonctionnent, d'autres pas: 
merci de signaler les erreurs.

### État actuel (30 juillet 21)

 - serveur de développement fonctionnel (pas testé en mode "production" sous gunicorn+nginx).

 - logs à revoir (tropverbeux), dans `/opt/scodoc-data/log`

 - pas d'import/export excel.


**En cours:**
 
 - nettoyage du code, finalisation tests et intégration.
 

## 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.

### Installation

#### 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 qui 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 evrsion, voir plus loin.

#### Installer ScoDoc
Sur un système Linux Debian 10, en tant que `root`:

 - Charger la dernière release depuis https://scodoc.org/git/viennet/ScoDoc/releases

 - 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

 - Lancer le script d'installation: 

        cd /opt/scodoc/tools
        ./install_debian10.sh

ce script crée un compte utilisateur "scodoc".

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 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).

### Création de la base de données

Lancer le script:

    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

Les bases créées appartiennent à l'utilisateur (role) 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

    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

### Initialisation de la base utilisateur par Flask

En tant qu'utilisateur `scodoc`:

    su scodoc # si besoin
    cd /opt/scodoc
    source venv/bin/activate
    #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
    flask user-create tata Ens Info

ou mieux, importer les utilisateurs de ScoDoc7 avec:

    flask user-db-import-scodoc7

(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

## 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
  ScoDoc 8 doit avoir été installé comme expliqué plus haut.

        sudo su
        cd /opt/scodoc/tools
        ./migrate_from_scodoc7.sh

## Création d'un département

    su scodoc # si besoin
    cd /opt/scodoc
    source venv/bin/activate
    flask sco-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 sco-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

## 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/*

## TODO

 - import/export Excel