From 46ea96bbba45b0177d76efdafa5c5a36d3e2fc62 Mon Sep 17 00:00:00 2001 From: viennet Date: Tue, 24 Aug 2021 19:51:54 +0200 Subject: [PATCH] Install ScoDoc 9 --- docs/GuideInstallDebian11.md | 188 +++++++++++++++++++++++++++++++++- docs/GuideInstallDebianDix.md | 4 +- docs/TestsScoDoc.md | 4 +- docs/attachments/scodoc.list | 2 + 4 files changed, 193 insertions(+), 5 deletions(-) create mode 100644 docs/attachments/scodoc.list diff --git a/docs/GuideInstallDebian11.md b/docs/GuideInstallDebian11.md index 7d1a400..9b527c2 100644 --- a/docs/GuideInstallDebian11.md +++ b/docs/GuideInstallDebian11.md @@ -7,8 +7,194 @@ 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. + +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 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, ...). + + +## 1) Préalable: configurer un serveur linux +Le serveur devrait être accessible depuis Internet. + +### Informations sur les flux réseau +Le serveur est fréquemment installé sur un réseau protégé ou sur un VPN. + + - le trafic entrant est sur le port 443 (le trafic http/80 est redirigé + vers le https). + + - le serveur doit pouvoir envoyer du mail (serveur postfix en local, à + configurer pour utiliser un relais smtp ou envoyer directement, selon + votre politique); + + - Les serveurs de mise à jour de Debian doivent être accessibles (en http, + voir `/etc/apt/sources.list`); + + - Les serveurs `scodoc.org` et `scodoc.iutv.univ-paris13.fr` doivent + ê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.). + +![InstallDebian6-1.png](screens/InstallDebian6-1.png) + +### Points à vérifier avant d'installer ScoDoc +Checklist minimale de votre système Linux Debian: + + 1. Connexion à Internet: le réseau doit être accessible. En effet, le script d'installation va installer des paquetages du système Debian puis télécharger la dernière mise à jour du logiciel ScoDoc (à partir du serveur Subversion). + 1. Vérifiez la connectivité, par exemple: +``` +ping www.univ-paris13.fr +(quitter avec ctrl-c) +cd /tmp +wget --no-check-certificate https://www-lipn.univ-paris13.fr/projects/scodoc +# doit créer un fichier nomme "scodoc" contenant du code HTML +``` + 3. Nom DNS: le serveur doit avoir un nom ("serveur.exemple.fr") connu dans le DNS (local ou public). Pour des tests, vous pouvez vous passer de DNS, mais dans ce cas le nom de votre serveur sera son adresse IP (eg 192.168.0.10) et il ne sera peut être pas accessible de l'extérieur. + 1. Vérifiez que votre serveur est accessible depuis une autre machine de votre réseau (voire d'Internet): par exemple "ping serveur.exemple.fr". + 1. Date et heure: vérifier que les dates et heure sont correctes, même après reboot. L'utilisation d'un serveur de temps (ntp) est recommandée (`aptitude install ntp`), et éventuellement `dpkg-reconfigure tzdata`). + 1. Cette liste est incomplète... et n'oubliez pas: avant de passer en production, mettez en place des sauvegardes sérieuses ! + +#### Configuration si utilisation d'un proxy + Si votre accès à Internet passe par un proxy, l'indiquer au moment de l'installation Debian. Il est possible qu'il vous faille configurer d'autres éléments, voir par exemple https://stackoverflow.com/questions/9445489/performing-http-requests-with-curl-using-proxy + + +## 2) Installation de ScoDoc sur Debian + +### 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**). + + - Ajouter le dépot scodoc: copier ce fichier scodoc.list dans `/etc/apt/sources.list.d/` + + - Installer la clé: en `root` sur le serveur, lancer + + apt-get 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 + +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 + + 1. Activer le firewall (optionnel, recommandé) + + ufw default deny incoming + ufw default allow outgoing + ufw allow ssh + ufw allow https + yes | ufw enable + + 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: + + 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. Démarrer nginx: `systemctl restart nginx` + + 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**: ``` diff --git a/docs/GuideInstallDebianDix.md b/docs/GuideInstallDebianDix.md index 21e3320..f41e041 100644 --- a/docs/GuideInstallDebianDix.md +++ b/docs/GuideInstallDebianDix.md @@ -7,7 +7,7 @@ Cette procédure doit être effectué sur la machine serveur avec un accès admi 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) 10 (Buster, 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 **très déconseillé** de tenter l'installation sur une autre version, à moins de disposer de temps et de bonnes connaissances sur Linux et les paquetages Python. +Cette documentation est prévue pour installer ScoDoc sur un système [Debian](http://www.debian.org) 10 (Buster) 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 **très déconseillé** de tenter l'installation sur une autre version, à moins de disposer de temps et de bonnes connaissances sur Linux et les paquetages Python. Merci de me signaler tout problème (emmanuel.viennet@gmail.com) @@ -17,7 +17,7 @@ Merci de me signaler tout problème (emmanuel.viennet@gmail.com) - Note 2: si quelqu'un produit, teste et documente une image Docker, merci de la partager (écrire à scodoc-devel). -/!\ 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, ...). ## Préalable: configurer un serveur linux diff --git a/docs/TestsScoDoc.md b/docs/TestsScoDoc.md index a79c262..b256762 100644 --- a/docs/TestsScoDoc.md +++ b/docs/TestsScoDoc.md @@ -34,13 +34,13 @@ TODO (Aurélien, JMP) Un faux portail "apogée" pour inscrire de faux étudiants avec photos. Utile pour tester les fonctions d'inscription/synchronisation, et aussi pour peupler rapidement une base de donnée. -Le code se trouve dans `scotests/fakeportal/`. +Le code se trouve dans `tools/fakeportal/`. Le serveur écoute par défaut sur `tcp/8678`. Il faudra paramétrer l'URL du "portail" dans les préférences du ScoDoc à tester, qui est en général sur le même hôte, donc `http://localhost:8678`. Lancement: - /opt/scodoc/scotests/fakeportal/fakeportal.py + /opt/scodoc/tools/fakeportal/fakeportal.py diff --git a/docs/attachments/scodoc.list b/docs/attachments/scodoc.list new file mode 100644 index 0000000..aa8d932 --- /dev/null +++ b/docs/attachments/scodoc.list @@ -0,0 +1,2 @@ +# ScoDoc repository +deb http://scodoc.org/repo bullseye main