DocScoDoc/docs/GuideConfig.md

##  Prise en main et paramétrage de ScoDoc 9

<img src="/img/alert.png" style="vertical-align: bottom; margin:0 0 0 0;" alt="/!\" /> Cette 
page  concerne la version ScoDoc 9, distribuée à partir de septembre 2021.

Ce document suppose que le logiciel a été installé suivant la procédure décrite dans 
[GuideInstallDebian11](GuideInstallDebian11.md).


##  Administration en ligne de commande

Les opérations d'administration se résument à la création de départements, et l'installation
des logos, et la création d'utilisateurs "super admin", c'est à dire admin pour tous les 
départements. Le reste des paramétrages (création de comptes, de formations, import 
d'étudiants, etc) se fait à partir du logiciel (web).

L'administration se fait dans un terminal connecté au serveur (en général via 
ssh), en tant qu'utilisateur `scodoc` (*et non* `root`).

Se connecter et initialiser la session ainsi:

    ssh votre.serveur # si nécessaire
    su scodoc         # idem, 
    # ou tout autre moyen d'ouvrir un shell comme scodoc
    
    cd /opt/scodoc
    source venv/bin/activate

Après quoi, vous pouvez utiliser les commandes décrites ci-dessous.
*Attention: le lancement de chaque commande est assez long (quelques secondes)
car toute l'application scodoc est initialisée à chaque fois.*

### Création d'un département

    flask create-dept DEPT

où `DEPT` est l'acronyme du département, par exemple "RT". Ce département 
apparait immédiatement sur la page d'accueil.

### Suppression d'un département

Opération très rarement nécessaire, proposée pour corriger une erreur 
immédiatement après la création.

    flask delete-dept DEPT
    
### Création d'un utilisateur
Cette opération s'effectue en général depuis le logiciel, via un formulaire
ou un import Excel. Pour créer un utilisateur depuis le terminal, lancer:

    flask user-create LOGIN ROLE DEPT

où `LOGIN` sera le pseudo de l'utilisateur (utilisé pour se connecter),
et `ROLE` le rôle (`Ens`, `Secr`, `Admin`) dans le département `DEPT`.

### Création d'un super-administrateur

Il s'agit d'un utilisateur ayant tous les droits, comme s'il était 
`Admin` dans tous les départements. 

    flask user-create admin2 SuperAdmin @all

où `admin2` est ici le pseudo du nouvel admin.

### Changement du mot de passe d'un utilisateur
Cette opération peut s'effectuer via la page de gestion web des
utilisateurs, mais il est parfois commode de le faire depuis la 
console:

    flask user-password LOGIN

où `LOGIN` est le pseudo de l'utilisateur. Le mot de passe est demandé 
sur la ligne de commande.

### Création d'un nouveau rôle

    flask create-role role_name [permissions...]

Exemple: création d'une rôle "Observateur" ayant juste la permission de "voir":

    flask create-role Observateur ScoView

### Liste des rôles

    flask list-roles

### Édition d'un rôle (ajout/retrait permissions)

    flask edit-role [-a permission] [-r permission] role_name

Ajoute ou retire une permission.

### Ajout/retrait d'un rôle à un utilisateur

    flask user-role username [-d departement] [-a RoleAAjouter] [-r RoleARetirer]

Exemple:

    flask user-role dupont -d MMI -a Observateur

donne le rôle `Observateur` (qui doit déjà exister) à l'utilisateur `dupont` dans
le département `MMI`.

Si le département n'est pas spécifié, le rôle est donné dans *tous* les
départements (utile pour certains compte administrateurs ou utilisés en lecture
par des clients de l'API).

### Migration des données de ScoDoc 7
Les données dans ScoDoc 9 ayant un format et une organisation très différents
de ScoDoc 7, une étape de conversion (migration) est nécessaire. Elle est automatique
mais prend du temps.

Se reporter à [MigrationScoDoc7a9](MigrationScoDoc7a9.md)

Ces commandes sont utilisées par le script de migration de ScoDoc 7 à ScoDoc 9.
*Ne pas utiliser sauf si vous savez vraiment ce que vous faites.*

#### Comptes utilisateurs

Toujours migrer les comptes utilisateurs avant d'importer les 
départements.

    flask import-scodoc7-users

#### Départements
Pour migrer un seul département:

    flask import-scodoc7-dept DEPT DBNAME

Exemple:

    flask import-scodoc7-dept InfoComm DBINFOCOMM

### Liste des commandes Flask/ScoDoc
```
Usage: app [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  clear-cache                    Clear ScoDoc cache This cache (currently...
  create-dept                    Create new departement
  create-role                    Create a new role
  delete-dept                    Delete existing departement
  delete-role                    Delete a role
  dumphelp
  edit-role                      Add [-a] and/or remove [-r] a permission...
  import-scodoc7-dept            Import département ScoDoc 7: dept:...
  import-scodoc7-users           Import users defined in ScoDoc7...
  list-depts                     If dept exists, print it, else nothing.
  localize-logo                  Make local to a dept a global logo (both...
  migrate-scodoc7-dept-archives  Post-migration: renomme les archives en...
  migrate-scodoc7-dept-logos     Post-migration: renomme les logos en...
  photos-import-files
  profile                        Start the application under the code...
  sco-db-init                    Initialize the database.
  scodoc-database                print the database connexion string
  user-create                    Create a new user
  user-db-clear                  Erase all users and roles from the...
  user-delete                    Try to delete this user.
  user-password                  Set (or change) user’s password
  user-role                      Add or remove a role to the given user...

Usage: app sco-db-init [OPTIONS]

  Initialize the database. Starts from an existing database and create all the
  necessary SQL tables and functions.

Options:
  --erase / --no-erase

Usage: app user-db-clear [OPTIONS]

  Erase all users and roles from the database !



Usage: app user-create [OPTIONS] USERNAME ROLE DEPT

  Create a new user

Options:
  -n, --nom TEXT
  -p, --prenom TEXT

Usage: app user-delete [OPTIONS] USERNAME

  Try to delete this user. Fails if it’s associated to some scodoc objects.


Usage: app user-password [OPTIONS] USERNAME

  Set (or change) user’s password

Options:
  --password TEXT

Usage: app create-role [OPTIONS] ROLENAME [PERMISSIONS]...

  Create a new role


Usage: app edit-role [OPTIONS] ROLENAME

  Add [-a] and/or remove [-r] a permission to/from a role. In ScoDoc,
  permissions are not associated to users but to roles. Each user has a set of
  roles in each departement.

  Example: `flask edit-role -a ScoEditApo Ens`

Options:
  -a, --add TEXT
  -r, --remove TEXT

Usage: app delete-role [OPTIONS] ROLENAME

  Delete a role

Options:
  --help  Show this message and exit.

Usage: app user-role [OPTIONS] USERNAME

  Add or remove a role to the given user in the given dept

Options:
  -d, --dept TEXT
  -a, --add TEXT
  -r, --remove TEXT
  --help             Show this message and exit.

Usage: app delete-dept [OPTIONS] DEPT

  Delete existing departement

Options:
  --yes
  --help  Show this message and exit.

Usage: app create-dept [OPTIONS] DEPT

  Create new departement


Usage: app list-depts [OPTIONS] [DEPTS]...

  If dept exists, print it, else nothing. Called without arguments, list all
  depts along with their ids.



Usage: app scodoc-database [OPTIONS]

  print the database connexion string

Options:
  -n, --name  show database name instead of connexion string (required for
              dropdb/createdb commands)


Usage: app import-scodoc7-users [OPTIONS]

  Import users defined in ScoDoc7 postgresql database into ScoDoc 9 The old
  database SCOUSERS  must be alive and readable by the current user. This
  script is typically run as unix user "scodoc". The original SCOUSERS
  database is left unmodified.


Usage: app import-scodoc7-dept [OPTIONS] DEPT DEPT_DB_NAME

  Import département ScoDoc 7: dept: InfoComm, dept_db_name: SCOINFOCOMM


Usage: app migrate-scodoc7-dept-archives [OPTIONS] [DEPT]

  Post-migration: renomme les archives en fonction des id de ScoDoc 9


Usage: app migrate-scodoc7-dept-logos [OPTIONS] [DEPT]

  Post-migration: renomme les logos en fonction des id / dept de ScoDoc 9


Usage: app localize-logo [OPTIONS] LOGO DEPT

  Make local to a dept a global logo  (both logo and dept names are mandatory)


Usage: app photos-import-files [OPTIONS] FORMSEMESTRE_ID XLSFILE ZIPFILE

  Import des photos d’étudiants à partir d’une liste excel et d’un zip avec les images.

Usage: app clear-cache [OPTIONS]

  Clear ScoDoc cache This cache (currently Redis) is persistent between
  invocation and it may be necessary to clear it during upgrades, development
  or tests.

Options:
  --sanitize / --no-sanitize

Usage: app dumphelp [OPTIONS]

  Génère la page d’aide complète pour la doc.

Usage: app profile [OPTIONS]

  Start the application under the code profiler.

Options:
  -h, --host TEXT     The interface to bind to.
  -p, --port INTEGER  The port to bind to.
  --length INTEGER    Number of functions to include in the profiler report.
  --profile-dir TEXT  Directory where profiler data files are saved.
  --help              Show this message and exit.
```

(*la liste ci-dessus est générée à l'aide de la commande* `flask dumphelp`).

###  Changement des logos apparaissant sur les documents 

*Note: après migration, vos logos de ScoDoc 7 sont installés dans ScoDoc 9*.

Les documents PDF (PV de jurys...) incluent les logos de l'établissement. 
Par défaut, ceux de l'IUT de Villetaneuse et de l'Université Paris 13 sont 
distribués. [Pour les changer, voir la FAQ](/FAQ/#comment-changer-les-logos-sur-les-documents-pdf-pv)

Si vous êtes administrateur système, vous pouvez aussi placer vos images (fichiers JPEG ou PNG) 
dans le répertoire

    /opt/scodoc-data/config/logos

On peut fournir des images (logos, fond de pages) par département en créant des sous-répertoires

    /opt/scodoc-data/config/logos/logo_<dept>/

Après quoi, redémarrez ScoDoc après avoir vidé les caches:

    flask clear-cache
    sudo systemctl restart scodoc9


## Utilisation via le Web

 * Connectez-vous au site: `https://votre.site.fr/`


Vous allez voir la page d'accueil de ScoDoc, vous permettant de choisir le département 
où travailler.

<img src="/img/alert.png" style="vertical-align: bottom; margin:0 0 0 0;" alt="/!\" /> Surtout, 
évitez de travailler comme "admin" (super admin): prenez le temps de créer un utilisateur 
"chef de département !" dans chaque département, qui à son tour pour déléguer des droits.