diff --git a/docs/GuideConfig.md b/docs/GuideConfig.md index 148a60a0..7d93aeb1 100644 --- a/docs/GuideConfig.md +++ b/docs/GuideConfig.md @@ -1,50 +1,140 @@ -# Prise en main et paramétrage de ScoDoc -Ce document suppose que le logiciel a été installé suivant la procédure décrite dans [GuideInstallDebianDix](GuideInstallDebianDix.md). +# Prise en main et paramétrage de ScoDoc 9 + +/!\ Cette +page concerne la version ScoDoc 9, distribuée à partir de septembre 2021. Pour l'ancienne +version, voir [cette page](GuideConfig7.md). + +Ce document suppose que le logiciel a été installé suivant la procédure décrite dans +[GuideInstallDebian11](GuideInstallDebian11.md). +# Administration en ligne de commande -## Procédure à suivre pour créer un département et son utilisateur administrateur - * Connectez-vous au site: `https://votre.site.fr/` +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`). -Vous allez voir la page d'accueil de ScoDoc (il est possible que votre navigateur vous demande d'accepter un certificat). +Se connecter et initialiser la session ainsi: -Il n'y a pas de "département défini": c'est normal, lors de l'installation nous avons créé des bases de données, mais pas les interfaces web. + 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 - * Suivez le lien *Identifiez vous comme administrateur*. L'utilisateur *admin* est administrateur et a tous les droits sur !ScoDoc. C'est le seul à pouvoir créer un nouveau département. +Après quoi, vous pouvez utiliser les commandes décrites ci-dessous. -Le logiciel va vous demander de changer immédiatement le mot de passe administrateur. -Entrez l'identifiant et le mot de passe définis pendant l'installation. +## Création d'un département -Après vous être identifié sur la page d'accueil ScoDoc, vous avez maintenant un lien 'Administration de ScoDoc' qui -vous permet d'ajouter un département, puis des utilisateurs. + flask create-dept DEPT - * Ajouter un département (donnez le nom du département créé pendant l'installation) +où `DEPT` est l'acronyme du département, par exemple "RT". Ce département +apparait immédiatement sur la page d'accueil. - * Ajouter un administrateur pour votre département: lien "Utilisateurs" (marge de gauche), puis suivre "ajouter un utilisateur". Donner à ce nouvel utilisateur les rôles `Admin`, `Ens` et `Secr` afin qu'il puisse effectuer toutes les opérations. +## Suppression d'un département -Quittez votre navigateur et reconnectez vous à ScoDoc avec votre nouvel utilisateur. +Opération très rarement nécessaire, proposée pour corriger une erreur +immédiatement après la création. -Vous pouvez si nécessaire créer plusieurs administrateurs par département (il est préférable que chaque compte ne soit utilisé que par une seule personne, pour éviter de divulguer les mots de passe et mieux suivre les opérations). + flask delete-dept DEPT + +## Création d'un utilisateur +Cette opération s'effectue en général depuyis le logiciel, via un formulaire +ou un import excel. Depuis la consoile, faire: -/!\ Surtout, évitez de travailler comme "admin": cet utilisateur doit être réservé à la création de départements. Prenez le temps de créer un utilisateur "chef de département !". + 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. + +## 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 prends du temps. + +**XXX la procédure de migration "en place" n'est pas encore disponible.** + +**Un script inétgré réalise les deux étapes suivantes, la doc arrive XXX** + +### 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 ## Changement des logos apparaissant sur les documents -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 (ce n'est pas bien, ils ne sont sans doute pas sous licence libre !). Pour les changer, placer vos logos (fichiers images JPEG ou PNG) dans le répertoire -``` -/opt/scodoc/var/scodoc/config/logos -``` -avec les noms `logo_header.jpg` (habituellement le logo de votre composante, mais faites comme vous voulez) et `logo_footer.jpg` (habituellement le logo de votre Université ou école). + +*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, placer vos logos (fichiers images JPEG ou PNG) +dans le répertoire + + /opt/scodoc-data/config/logos + +avec les noms `logo_header.jpg` (habituellement le logo de votre composante) +et `logo_footer.jpg` (habituellement le logo de votre université ou école). Ensuite, éditez le fichier -``` -/opt/scodoc/Products/ScoDoc/config/scodoc_config.py -``` -et changer les valeurs des variables `CONFIG.LOGO_FOOTER_ASPECT` et suivantes (ce n'est pas pratique, il faudrait modifier le code ScoDoc pour calculer ces valeurs à partir des fichiers images). + + /opt/scodoc-data/config/logos + +et changer les valeurs des variables `CONFIG.LOGO_FOOTER_ASPECT` et suivantes +(ce n'est pas pratique, il faudrait modifier le code ScoDoc pour calculer ces valeurs +à partir des fichiers images). + +Enfin, redémarrez ScoDoc après avoir vidé les caches: + + flask clear-cache + systemctl restart scodoc9 -Enfin, redémarrez ScoDoc (`/etc/init.d/scodoc start`). +# 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. + +/!\ 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. diff --git a/docs/GuideConfig7.md b/docs/GuideConfig7.md new file mode 100644 index 00000000..e5a1b49d --- /dev/null +++ b/docs/GuideConfig7.md @@ -0,0 +1,55 @@ + +# Prise en main et paramétrage de ScoDoc 7 + +/!\ Cette page +concerne la version ScoDoc 7, et ne s'applique pas à la version ScoDoc 9 distribuée à partir de septembre 2021. +Pour ScoDoc 9, voir [cette page](GuideConfig.md). + +Ce document suppose que le ScoDOc 7 a été installé suivant la procédure décrite dans [GuideInstallDebianDix](GuideInstallDebianDix.md). + + + +## Procédure à suivre pour créer un département et son utilisateur administrateur + * Connectez-vous au site: `https://votre.site.fr/` + + +Vous allez voir la page d'accueil de ScoDoc (il est possible que votre navigateur vous demande d'accepter un certificat). + +Il n'y a pas de "département défini": c'est normal, lors de l'installation nous avons créé des bases de données, mais pas les interfaces web. + + * Suivez le lien *Identifiez vous comme administrateur*. L'utilisateur *admin* est administrateur et a tous les droits sur !ScoDoc. C'est le seul à pouvoir créer un nouveau département. + +Le logiciel va vous demander de changer immédiatement le mot de passe administrateur. +Entrez l'identifiant et le mot de passe définis pendant l'installation. + +Après vous être identifié sur la page d'accueil ScoDoc, vous avez maintenant un lien 'Administration de ScoDoc' qui +vous permet d'ajouter un département, puis des utilisateurs. + + * Ajouter un département (donnez le nom du département créé pendant l'installation) + + * Ajouter un administrateur pour votre département: lien "Utilisateurs" (marge de gauche), puis suivre "ajouter un utilisateur". Donner à ce nouvel utilisateur les rôles `Admin`, `Ens` et `Secr` afin qu'il puisse effectuer toutes les opérations. + +Quittez votre navigateur et reconnectez vous à ScoDoc avec votre nouvel utilisateur. + +Vous pouvez si nécessaire créer plusieurs administrateurs par département (il est préférable que chaque compte ne soit utilisé que par une seule personne, pour éviter de divulguer les mots de passe et mieux suivre les opérations). + +/!\ Surtout, évitez de travailler comme "admin": cet utilisateur doit être réservé à la création de départements. Prenez le temps de créer un utilisateur "chef de département !". + + + +## Changement des logos apparaissant sur les documents +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 (ce n'est pas bien, ils ne sont sans doute pas sous licence libre !). Pour les changer, placer vos logos (fichiers images JPEG ou PNG) dans le répertoire +``` +/opt/scodoc/var/scodoc/config/logos +``` +avec les noms `logo_header.jpg` (habituellement le logo de votre composante, mais faites comme vous voulez) et `logo_footer.jpg` (habituellement le logo de votre Université ou école). + +Ensuite, éditez le fichier +``` +/opt/scodoc/Products/ScoDoc/config/scodoc_config.py +``` +et changer les valeurs des variables `CONFIG.LOGO_FOOTER_ASPECT` et suivantes (ce n'est pas pratique, il faudrait modifier le code ScoDoc pour calculer ces valeurs à partir des fichiers images). + + +Enfin, redémarrez ScoDoc (`/etc/init.d/scodoc start`). + diff --git a/docs/GuideInstallDebian11.md b/docs/GuideInstallDebian11.md index 9b527c20..dac07bef 100644 --- a/docs/GuideInstallDebian11.md +++ b/docs/GuideInstallDebian11.md @@ -8,20 +8,36 @@ XXX en cours de rédaction. En attendant, voir https://scodoc.org/git/viennet/ScoDoc -ScoDoc est livré avec des scripts d'installation qui configurer presque automatiquement votre serveur (serveur web, base de données, etc): vous pouvez donc installer et configurer ScoDoc avec des connaissances réduites sur le système Linux. +ScoDoc est livré avec des scripts d'installation qui configurer presque +automatiquement votre serveur (serveur web, base de données, etc): vous pouvez +donc installer et configurer ScoDoc avec des connaissances réduites sur le +système Linux. -Cette documentation est prévue pour installer ScoDoc sur un système [Debian](http://www.debian.org) 11 (Bullseye, stable) s'exécutant sur une machine intel-like **64bits** (architecture **AMD64**). Debian s'installe facilement en une quinzaine de minutes, sur une machine normale ou un serveur virtualisé. Il est **vivement déconseillé** de tenter l'installation sur une autre version. +Cette documentation est prévue pour installer ScoDoc sur un système +[Debian](http://www.debian.org) 11 (Bullseye, stable) s'exécutant sur une +machine intel-like **64bits** (architecture **AMD64**). Debian s'installe +facilement en une quinzaine de minutes, sur une machine normale ou un serveur +virtualisé. Il est **vivement déconseillé** de tenter l'installation sur une +autre version. Merci de signaler tout problème (emmanuel.viennet@gmail.com ou [scodoc-devel](https://listes.univ-paris13.fr/mailman/listinfo/scodoc-devel) ). -- Note 1: l'image du CD d'installation de Debian (amd64) peut se trouver ici: [https://www.debian.org/distrib/netinst](https://www.debian.org/distrib/netinst.md), choisir la version "petits CD" pour **amd64** (*Il est indispensable d'utiliser une version 64 bits ! *) +- Note 1: l'image du CD d'installation de Debian (amd64) peut se trouver ici: + [https://www.debian.org/distrib/netinst](https://www.debian.org/distrib/netinst.md), + choisir la version "petits CD" pour **amd64** (*Il est indispensable + d'utiliser une version 64 bits ! *) - Note 2: une version Docker serait utile: avis aux volontaires. -/!\ Important: La procédure d'installation décrite ci-dessous suppose que ScoDoc va s'exécuter sur un serveur dédié. Pour faire des tests, utilisez un serveur virtuel (comme VirtualBox ou VMWare). L'installation ci-dessous va en effet modifier de nombreux paramètres de votre système linux (serveur web, firewall, serveur SQL, messagerie, ...). +/!\ Important: +La procédure d'installation décrite ci-dessous suppose que ScoDoc va s'exécuter +sur un serveur dédié. Pour faire des tests, utilisez un serveur virtuel (comme +VirtualBox ou VMWare). L'installation ci-dessous va en effet modifier de +nombreux paramètres de votre système linux (serveur web, firewall, serveur SQL, +messagerie, ...). ## 1) Préalable: configurer un serveur linux @@ -44,8 +60,11 @@ Le serveur est fréquemment installé sur un réseau protégé ou sur un VPN. être accessibles (80 et 443). ### Installation Linux Debian -Nous recommandons d'effectuer une installation standard de Debian par le réseau (netinst). -Durant l'installation de Debian, lorsqu'il demande "logiciels à installer", tout décocher sauf "Serveur SSH" et "Utilitaires standard du système". Le script d'installation de ScoDoc se chargera ensuite d'installer tous les éléments nécessaires (serveur web, messagerie, etc.). +Nous recommandons d'effectuer une installation standard de Debian par le réseau (netinst), +et d'utiliser l'install en mode texte, très simple et rapide. +Durant l'installation de Debian, lorsqu'il demande "logiciels à installer", tout décocher +sauf "Serveur SSH" et "Utilitaires standard du système". Le script d'installation de ScoDoc +se chargera ensuite d'installer tous les éléments nécessaires (serveur web, messagerie, etc.). ![InstallDebian6-1.png](screens/InstallDebian6-1.png) @@ -74,144 +93,71 @@ wget --no-check-certificate https://www-lipn.univ-paris13.fr/projects/scodoc ### 2.1) Charger le logiciel - /!\ Les commandes ci-dessous sont à exécuter dans un terminal ouvert en tant que **root** sur le serveur. Vous pouvez utiliser `su` (ou `sudo su`) pour devenir **root**). + /!\ Les commandes ci-dessous sont à exécuter dans un terminal ouvert + en tant que **root** sur le serveur. Vous pouvez utiliser `su` (ou `sudo su`) + pour devenir **root**). + +Remarque: *Si ce n'est pas déjà le cas, vous avez intérêt à ouvrir une session `ssh` (ou `putty`) +depuis une machine normale, afin de pouvoir copier/coller facilement les commandes et éditer +les fichiers de configuration.* - Ajouter le dépot scodoc: copier ce fichier scodoc.list dans `/etc/apt/sources.list.d/` +ou le créer contenant juste cette ligne: + + # contenu du fichier /etc/apt/sources.list.d/scodoc.list + deb http://scodoc.org/repo bullseye main - Installer la clé: en `root` sur le serveur, lancer - apt-get install gnupg + apt-get -y install gnupg wget -O - https://scodoc.org/misc/scodoc-repo.gpg.key | apt-key add - - Installer le logiciel: - apt-get update - apt-get install scodoc9 + apt-get update + apt-get install scodoc9 -Notez que l'installation du paquet `scodoc9` va créer automatiquement un utilisateur `scodoc` qui sera utilisé par le serveur. +Notez que l'installation du paquet `scodoc9` va créer automatiquement un +utilisateur `scodoc` qui sera utilisé par le serveur. -### 2.2) Configuration des logiciels annexes + - Attribuer un mot de passe à l'utilisateur `scodoc`: + + passwd scodoc + + +### 2.2) Configuration des logiciels et des données - 1. Activer le firewall (optionnel, recommandé) +Vous pouvez le faire manuellement, ou simplement lancer le script suivant +en tant que `root` sur votre serveur nouvellement installé: - ufw default deny incoming - ufw default allow outgoing - ufw allow ssh - ufw allow https - yes | ufw enable + /opt/scodoc/tools/configure-scodoc9.sh - 2. ScoDoc utilise le serveur Web nginx. Installer les certificats SSL - nécessaires pour https. C'est indispensable sur un serveur en production. Sur un serveur de test, pour faire des essais, vous pouvez utiliser des certificats auto-signés. Procéder ainsi: +Vous devrez répondre à quelques questions et saisir le mot de passe que vous +attribuerez à l'utilisateur `admin`. - su scodoc # utilisateur scodoc - cd /opt/scodoc-data - mkdir -p certs && openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 -keyout certs/key.pem -out certs/cert.pem -Sinon, éditer le fichier `/etc/nginx/sites-available/scodoc9.nginx` -pour indiquer vos certificats. +### 3) **Lancer ScoDoc**: - 3. Démarrer nginx: `systemctl restart nginx` + sudo su # se connecter en root + systemctl restart scodoc9 - 4. Démarrer redis `systemctl start redis` - - - -### 2.3) Création des bases de données -ScoDoc 9 utilise une 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). - -Pour créer la base de données, lancer le script: - - su scodoc # au besoin (pas root !) - cd /opt/scodoc - ./tools/create_database.sh 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 (rôle) postgres `scodoc` -(qui a été créé par le script d'installation précédent). - -### 2.4) 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 sera lu automatiquement au démarrage: - - # .env for ScoDoc _development_ - - FLASK_APP=scodoc.py - FLASK_ENV=development # ou production - - 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 - -Le fichier `/opt/scodoc/.env-exemple`est donné à titre... d'exemple. Vous pouvez faire: - - # en tant qu'utilisateur scodoc - cd /opt/scodoc/ - cp .env-exemple .env - nano .env # édition - -Il est nécessaire de modifier MAIL_SERVER, SCODOC_ADMIN_MAIL et SECRET_KEY. -Cette dernière variable doit contenir une chaîne aléatoire qui servira -de clé pour sécuriser les formulaires. Vous pouvez utiliser la commande suivante -pour afficher une chaine de ce genre (choisie au hasard), que vous copierez -dans votre fichier `.env`: - - python3 -c "import uuid; print(uuid.uuid4().hex)" - -Nota: dans le futuir, on va intégrer cela dans le fichier d'install. - -### 2.5) Initialisation de la base et de l'utilisateur admin - -En tant qu'utilisateur `scodoc`: - - su scodoc # si besoin - cd /opt/scodoc - source venv/bin/activate - -Puis initialisation de l'appli: - - flask db-init - -Et saisie du mot de passe `admin`: - - flask user-password admin - -*Optionnel*: On peut ensuite à tout moment créer des utilisateurs la commande: - - flask user-create toto Ens DEPT - -où `Ens` indique le rôle (ici enseignant) et DEPT l'acronyme du département. - -Pour créer un utilisateur "super admin", c'est à dire admin dans tous les départements: - - flask user-create admin1 SuperAdmin @all - -xxx XXX xxx - - 7. **Lancer ScoDoc**: -``` - systemctl restart scodoc -``` et voila ! -Visiter `https://votre.site.fr/` pour achever la configuration et utiliser le logiciel: voir la page [GuideConfig](GuideConfig.md) +Visiter `https://monscodoc.mondomaine.fr/` pour achever la configuration et +utiliser le logiciel: voir la page [GuideConfig](GuideConfig.md). ## En cas de problème -Ne pas hésiter à me contacter ou à écrire sur la liste notes (voir [Listes de diffusion](ListesDeDiffusion.md)). +Ne pas hésiter à me contacter ou à écrire sur la liste notes (voir [Listes de +diffusion](ListesDeDiffusion.md)). * Problèmes d'envoi de courrier électronique (mail): voir [ProblemesMail](ProblemesMail.md) -Nota: sur certains réseaux, l'autoconfiguration IPv6 pose problème (par exemple: bloquage des envois de mails). Au besoin, il est possible de désactiver IPv6 (voir par exemple [ici](https://wiki.debian-fr.xyz/D%C3%A9sactiver_l%27IPv6)). +Nota: sur certains réseaux, l'autoconfiguration IPv6 pose problème (par exemple: +bloquage des envois de mails). Au besoin, il est possible de désactiver IPv6 +(voir par exemple [ici](https://wiki.debian-fr.xyz/D%C3%A9sactiver_l%27IPv6)). ## Ensuite... @@ -219,4 +165,4 @@ Nota: sur certains réseaux, l'autoconfiguration IPv6 pose problème (par exempl * Mettez en place des [sauvegardes](SauvegardesBases.md) - * Abonnez vous au moins à la liste d'annonces: voir [Listes de diffusion](ListesDeDiffusion.md) + * Abonnez-vous au moins à la liste d'annonces: voir [Listes de diffusion](ListesDeDiffusion.md) diff --git a/docs/GuideInstallDebian11Advanced.md b/docs/GuideInstallDebian11Advanced.md new file mode 100644 index 00000000..53cfe113 --- /dev/null +++ b/docs/GuideInstallDebian11Advanced.md @@ -0,0 +1,119 @@ +# Configuration manuelle de ScoDoc sur Debian 11 (Bullseye) + +Instructions pour utilisateurs ne souhaitant pas utiliser le script + + /opt/scodoc/tools/configure-scodoc9.sh + +Toutes les opérations décrites sur cette page sont effectuées par ce script. +Cette page est donc destinée aux curieux et futurs développeurs. Se référer au +script lui même pour les détails. + +## Activation du firewall + +(optionnel, recommandé) + + ufw default deny incoming + ufw default allow outgoing + ufw allow ssh + ufw allow http + ufw allow https + yes | ufw enable + +## Certificats pour nginx + +ScoDoc utilise le serveur Web nginx. Installer les certificats SSL +nécessaires pour https. C'est indispensable sur un serveur en production. +Sur un serveur de test, pour faire des essais, vous pouvez utiliser des +certificats auto-signés. Procéder ainsi: + + su scodoc # utilisateur scodoc + cd /opt/scodoc-data + mkdir -p certs && openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 -keyout certs/key.pem -out certs/cert.pem + +Répondre aux questions, la seule importante étant `Common Name (e.g. server +FQDN or YOUR name)` en réponse à laquelle vous devez fournir le nom que vous +utiliserez pour vous adresser au serveur: par exemple +`monscodoc.mondomaine.fr`. Ce nom dépend de votre configuration réseau. + + +Sinon, éditer le fichier `/etc/nginx/sites-available/scodoc9.nginx` pour +indiquer vos certificats. + +## Démarrage de nginx et redis + + su # se connecter en root d'une manière ou d'une autre + systemctl restart nginx + systemctl start redis + +Il est utile de vérifier que le serveur Web a bien démarré, avec + + systemctl status nginx + +## Création des bases de données +ScoDoc 9 utilise une 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). + +Pour créer la base de données, lancer le script: + + su scodoc # au besoin (pas root !) + cd /opt/scodoc + ./tools/create_database.sh 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 (rôle) 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 sera lu automatiquement au démarrage: + + # .env for ScoDoc (production) + + FLASK_APP=scodoc.py + FLASK_ENV=production + + 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 à changer + +Le fichier `/opt/scodoc/.env-exemple`est donné à titre... d'exemple. Vous pouvez faire: + + # en tant qu'utilisateur scodoc + cd /opt/scodoc/ + cp .env-exemple .env + nano .env # édition + +Il est nécessaire de modifier MAIL_SERVER, SCODOC_ADMIN_MAIL et SECRET_KEY. +Cette dernière variable doit contenir une chaîne aléatoire qui servira +de clé pour sécuriser les formulaires. Vous pouvez utiliser la commande suivante +pour afficher une chaine de ce genre (choisie au hasard), que vous copierez +dans votre fichier `.env`: + + python3 -c "import uuid; print(uuid.uuid4().hex)" + +Nota: dans le futur, on va intégrer cela dans le fichier d'install. + +## Initialisation de la base et de l'utilisateur admin + +En tant qu'utilisateur `scodoc`: + + su scodoc # si besoin + cd /opt/scodoc + source venv/bin/activate + +Puis initialisation de l'appli: + + flask db-init + +Et saisie du mot de passe `admin`: + + flask user-password admin diff --git a/docs/MisesAJour.md b/docs/MisesAJour.md index 8e5b331b..1250c520 100644 --- a/docs/MisesAJour.md +++ b/docs/MisesAJour.md @@ -1,48 +1,78 @@ # Mise à jour de ScoDoc + +**Les instructions ci-dessous concernent ScoDoc 7. A partir de ScoDoc 9, on +utilisera simplement `apt update && apt-get upgrade` (pas encore disponible !). +** + Il est recommandé de mettre à jour très régulièrement votre installation ScoDoc. -Le système Linux doit être correctement maintenu (en particulier, les mises à jour de sécurité de Debian doivent être appliquées quotidiennement). +Le système Linux doit être correctement maintenu (en particulier, les mises à +jour de sécurité de Debian doivent être appliquées quotidiennement). ScoDoc est actuellement prévu pour fonctionner avec Linux Debian 10. - * Les (rares) mises à jour majeures du logiciel ScoDoc sont annoncées sur la liste [scodoc-annonces](https://listes.univ-paris13.fr/mailman/listinfo/scodoc-annonces). - * Les (fréquentes) mises à jour mineures (corrections de bugs, améliorations) sont annoncées sur la liste [scodoc-devel](https://listes.univ-paris13.fr/mailman/listinfo/scodoc-devel). + * Les (rares) mises à jour majeures du logiciel ScoDoc sont annoncées sur la + liste + [scodoc-annonces](https://listes.univ-paris13.fr/mailman/listinfo/scodoc-annonces). + + * Les (fréquentes) mises à jour mineures (corrections de bugs, améliorations) + sont annoncées sur la liste + [scodoc-devel](https://listes.univ-paris13.fr/mailman/listinfo/scodoc-devel). + *Une mise à jour hebdomadaire (au moins) est recommandée* -Pour appliquer une mise à jour de ScoDoc, se connecter en tant que `root` sur le serveur, puis faire: -``` +Pour appliquer une mise à jour de ScoDoc, se connecter en tant que `root` sur le +serveur, puis faire: + cd /opt/scodoc/Products/ScoDoc/config ./upgrade.sh -``` -La première fois, il faudra accepter un certificat cryptographique, répondre "p (accept (p)ermanently)". -/!\ Si un message d'erreur apparaît à la fin de la mise à jour, relancer `./upgrade.sh`. +La première fois, il faudra accepter un certificat cryptographique, répondre "p +(accept (p)ermanently)". -/!\ La mise à jour entraine une déconnexion des utilisateurs (mais pas de pertes de données !). + Si un message d'erreur apparaît à la fin de la mise à jour, +relancer `./upgrade.sh`. -Note: cette procédure ne change pas de version majeure de ScoDoc, ni du système Linux. Pour cela, voir [MigrationDonneesScoDoc](MigrationDonneesScoDoc.md)) ou plus bas sur cette page. + La mise à jour entraine une déconnexion des utilisateurs (mais pas +de pertes de données !). + +Note: cette procédure ne change pas de version majeure de ScoDoc, ni du système +Linux. Pour cela, voir [MigrationDonneesScoDoc](MigrationDonneesScoDoc.md)) ou +plus bas sur cette page. ## Note concernant les anciens systèmes (Debian 9) -En Debian version 9 (et version antérieures), ScoDoc n'utilisait pas `systemd` et n'était pas automatiquement relancé lors de mises à jour de ceertains logiciels, comme la base de données `postgresql`. Sur ces systèmes, il est conseillé de mettre à jour Debian avec le script `/opt/scodoc/Products/ScoDoc/config/upgrade.sh` afin d'éviter d'interrompre le service ScoDoc. +En Debian version 9 (et version antérieures), ScoDoc n'utilisait pas `systemd` +et n'était pas automatiquement relancé lors de mises à jour de ceertains +logiciels, comme la base de données `postgresql`. Sur ces systèmes, il est +conseillé de mettre à jour Debian avec le script +`/opt/scodoc/Products/ScoDoc/config/upgrade.sh` afin d'éviter d'interrompre le +service ScoDoc. ## Mise à jour rapide de Debian 9 à Debian 10 -Procédure raccourcie réservée aux personnes à l'aise avec linux. On met à jour Debian mais on réinstalle ScoDoc proprement. +Procédure raccourcie réservée aux personnes à l'aise avec linux. On met à jour +Debian mais on réinstalle ScoDoc proprement. -Vérifiez que vous avez assez d'espace disque disponible (`df -h`, au moins 3Go libres sur `/` ou `/opt`). +Vérifiez que vous avez assez d'espace disque disponible (`df -h`, au moins 3Go +libres sur `/` ou `/opt`). - 0. Sauvegardez complètement votre système en lieu sûr. Si la procédure ci-dessous échoue, reprenez la voie normale: [MigrationDonneesScoDoc](MigrationDonneesScoDoc.md). + 0. Sauvegardez complètement votre système en lieu sûr. Si la procédure + ci-dessous échoue, reprenez la voie normale: + [MigrationDonneesScoDoc](MigrationDonneesScoDoc.md). 1. Mettre à jour votre ScoDoc: cd /opt/scodoc/Products/ScoDoc/config ./upgrade.sh - 2. Arrêter le service (en Debian 9 on utilisait *SysV-style init*, à partir de Debian 10 ScoDoc utilise `systemd`): + 2. Arrêter le service (en Debian 9 on utilisait *SysV-style init*, à partir de + Debian 10 ScoDoc utilise `systemd`): /etc/init.d/scodoc stop @@ -53,7 +83,9 @@ Vérifiez que vous avez assez d'espace disque disponible (`df -h`, au moins 3Go ./save_scodoc_data.sh /opt/data-scodoc-deb9 # par exemple - 4. Mettre à jour Debian: pour les détails voir [https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.html](https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.html). + 4. Mettre à jour Debian: pour les détails voir + [https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.html](https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.html). + En résumé: