From 23a2609833569ddc7e8374a6dd96cd448ce23f68 Mon Sep 17 00:00:00 2001 From: viennet Date: Mon, 24 Jul 2023 21:56:44 +0200 Subject: [PATCH] docs install ScoDOc 9.6 / Debian 12 --- docs/GuideInstallDebian11.md | 2 +- docs/GuideInstallDebian12.md | 342 +++++++++++++++++++++++++++++++++++ docs/UpgradeToDeb12Sco96.md | 3 + 3 files changed, 346 insertions(+), 1 deletion(-) create mode 100644 docs/GuideInstallDebian12.md diff --git a/docs/GuideInstallDebian11.md b/docs/GuideInstallDebian11.md index 49bb3a4..2573785 100644 --- a/docs/GuideInstallDebian11.md +++ b/docs/GuideInstallDebian11.md @@ -11,7 +11,7 @@ donc installer et configurer ScoDoc avec des connaissances réduites sur le système Linux. Cette documentation est prévue pour installer ScoDoc version 9 sur un système -[Debian](http://www.debian.org) 11 (Bullseye, stable) s'exécutant sur une +[Debian](http://www.debian.org) 11 (Bullseye, oldstable) s'exécutant sur une machine intel-like **64bits** (architecture **AMD64** sur Intel/AMD, ou **aarch64** sur Apple ARM). Debian s'installe facilement en cinq minutes, sur une machine normale ou un serveur virtualisé. Il est **vivement déconseillé** de diff --git a/docs/GuideInstallDebian12.md b/docs/GuideInstallDebian12.md new file mode 100644 index 0000000..516108c --- /dev/null +++ b/docs/GuideInstallDebian12.md @@ -0,0 +1,342 @@ + +# Installation de ScoDoc 9.6+ sur Debian 12 (Bookworm) + +Ce document décrit la procédure d'installation et de configuration de ScoDoc +version 9.6 et suivantes. + +Si vous mettez à jour une installation ScoDoc 9 existante (9.5 sous Debian 11 +Bullseye), suivez la +[procédure de migration décrite sur cette page](UpgradeToDeb12Sco96.md). + +La procédure décrite ici doit être effectué sur la machine serveur fraiche avec +un accès administrateur (root). **Ne pas l'utiliser pour migrer une installation existante**. + +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 version 9 sur un système +[Debian](http://www.debian.org) 12 (Bullseye, stable) s'exécutant sur une +machine intel-like **64bits** (architecture **AMD64** sur Intel/AMD, ou +**aarch64** sur Apple ARM). Debian s'installe facilement en cinq minutes, sur +une machine normale ou un serveur virtualisé. Il est **vivement déconseillé** de +tenter l'installation sur une autre version de Linux. + +Merci de signaler tout problème [sur le Discord](https://discord.gg/ybw6ugtFsZ). + +- Note: l'image du CD d'installation de Debian (amd64) peut se trouver ici: + [https://www.debian.org/CD/netinst/](https://www.debian.org/CD/netinst/), +choisir la version "petits CD" pour **amd64** +(*Il est indispensable d'utiliser une version 64 bits !*) + +🚸 **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, ou UTM sur Mac). L'installation de ScoDoc 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. + +### Configuration matérielle + +- taille disque: prévoir au moins 24Go sur la partition où sera scodoc (en + général `/`). + +- mémoire: prévoir au moins 8Go de RAM, et plutôt 12 ou 16. + +### 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. Au besoin, pour le reconfigurer, lancer `dpkg-reconfigure postfix`); + +- 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), et d'utiliser l'installation 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.). + +🚸 *Veiller à sélectionner une locale `UTF-8` par défaut.* + +![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 + scodoc.org). + 1. Vérifiez la connectivité, par exemple: + +```bash + ping www.univ-paris13.fr + (quitter avec ctrl-c) + cd /tmp + wget --no-check-certificate https://scodoc.org + # doit créer un fichier index.html 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. + 4. Mail: vérifiez que le serveur peut envoyer des e-mail: `mail + votre@adresse.fr`, puis entrer un message terminé par `ctrl-d`: si vous ne + recevez pas le message après quelques minutes, vérifiez votre configuration + (et le log `/var/log/mail.log`). Un serveur ScoDoc qui n'envoie pas de mail + ne peut pas vérifier ceux des utilisateurs, qui à leur tour ne pourront pas + changer leurs mots de passe (bien d'autres fonctions dépendent des mails). + Au besoin, revoir la configuration avec `dpkg-reconfigure postfix` (voir + aussi [envoi des courriers électroniques](ProblemesMail.md)). + + 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 ( + `apt-get install ntp`), et éventuellement `dpkg-reconfigure tzdata`). + 1. Si vous avez installé à partir d'un support (DVD, clé USB...), pensez à le + retirer des sources Debian afin de ne pas bloquer les mises à jour (commenter + la ligne `deb cdrom:` dans le fichier `/etc/apt/sources.list`) + 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. + +Vérifiez aussi que ces variables sont bien définies dans `/etc/environment` (si +l'installeur Linux Debian ne les a pas déjà indiquées là, les ajouter ou créer +ce fichier): + +```bash +# /etc/environment +export HTTP_PROXY=http://proxy.univ-xxx.fr:1234 +export HTTPS_PROXY=http://proxy.univ-xxx.fr:1234 +# Versions en minuscules utilisées par wget +export http_proxy="${HTTP_PROXY}" +export https_proxy="${HTTPS_PROXY}" +``` + +Ensuite, après installation du paquet scodoc9 (voir plus bas), il faudra +indiquer votre proxy: pour cela, éditer le fichier + +``` + /opt/scodoc/.env +``` + +et ajouter les variables d'environnement nécessaires. Typiquement, il s'agit de : + +```bash + HTTP_PROXY=http://proxy.univ-xxx.fr:1234 + HTTPS_PROXY=http://proxy.univ-xxx.fr:1234 +``` + +Après modification de ces fichiers (qui *doivent* être lisible par l'utilisateur `scodoc`), +redémarrer le service: + +```bash + sudo systemctl restart scodoc9 +``` + + Dans les cas compliqués, il est possible qu'il vous faille configurer d'autres + éléments, voir par exemple + [ce post sur Stack Overflow](https://stackoverflow.com/questions/9445489/performing-http-requests-with-curl-using-proxy). + +#### Note sur l'install dans un container LXC + +Il y a deux possibilités : + +**Option 1**, si vous installez dans un container LXC privilégié via le compte +root et/ou sudo, attention: la config par défaut de Redis (un gestionnaire de +cache utilisé par ScoDoc) n'est pas compatible, en raison d'un problème de +système de fichier en lecture seule. Installer redis avant ScoDoc, comme suit: + +```bash + apt-get install redis +``` + +Puis créer un dossier `/etc/systemd/system/redis.service.d` contenant le fichier +`redis.conf` avec les lignes suivantes : + +```text + [Service] + PrivateTmp=no + ProtectSystem=false + PrivateDevices=false + ProtectHome=no + ProtectControlGroups=no + ProtectKernelTunables=no + ProtectKernelModules=no + ReadWritePaths= + ReadOnlyDirectories= +``` + +Ensuite + +```bash + systemctl daemon-reload + systemctl start redis +``` + +... et poursuivez l'installation comme ci-dessous. + +**Option 2**, si vous installez dans un container LXC non-privilégié via un +compte utilisateur normal, vous pouvez activer l'option « nesting » +(imbriqué) de LXC pour permettre à Redis de fonctionner normalement. + +🚸 Attention ! N'activez pas le *nesting* sur un conteneur privilégié. Cela +provoquerait une faille de sécurité. + +Si vous avez construit votre conteneur manuellement avec `lxc-create`, modifiez +le fichier `/var/lib/lxc/${nomDuConteneur}/config` et ajoutez les lignes +ci-dessous : + +```text + lxc.apparmor.allow_nesting = 1 + lxc.apparmor.profile = generated +``` + +Si vous utilisez un conteneur LXC sur l'hyperviseur Proxmox, modifiez le +fichier `/etc/pve/lxc/${CTID}.conf` et ajoutez la ligne suivante : + +```text + features: nesting=1 +``` + +... et poursuivez l'installation comme ci-dessous. + +## 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**). + +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 bien le créer afin qu'il contienne juste cette ligne: + +```text + # contenu du fichier /etc/apt/sources.list.d/scodoc.list + deb http://scodoc.org/deb/bookworm bookworm main +``` + +- Installer la clé: en `root` sur le serveur, lancer + +```bash + apt-get -y install gnupg + wget -O - https://scodoc.org/misc/scodoc-repo.gpg.key | apt-key add - +``` + +- Installer le logiciel: + +```bash + apt-get update + apt-get install nginx +``` + S'assurer que le logiciel `nginx` s'est bien installé. En cas de problème se + référer à sa doc (par exemple, si + [votre serveur ne supporte pas + IPv6](https://techglimpse.com/nginx-error-address-family-solution/)). + + Ensuite: + +```bash + apt-get install scodoc9 +``` + +Notez que l'installation du paquet `scodoc9` va créer automatiquement un +utilisateur `scodoc` qui sera utilisé par le serveur. + +- Attribuer un mot de passe à l'utilisateur `scodoc`: + +```bash + passwd scodoc +``` + +### 2.2) Configuration des logiciels et des données + +Lancer le script suivant en tant que `root` sur votre serveur nouvellement installé: + +```bash + /opt/scodoc/tools/configure-scodoc9.sh +``` +Vous devrez répondre à quelques questions et saisir le mot de passe que vous +attribuerez à l'utilisateur `admin`. + +(note: pour en savoir plus sur ce script, [voir l'explication](GuideInstallDebian11Advanced.md)) + +### 3) **Lancer ScoDoc** + +```bash + sudo su # se connecter en root + systemctl restart nginx + systemctl restart scodoc9 +``` +✨ et voila ! + +Visiter `https://monscodoc.mondomaine.fr/` pour achever la configuration et +utiliser le logiciel: voir la page [GuideConfig](GuideConfig.md). + +## Importation des données ScoDoc 7 + +Si vous aviez une installation très ancienne avec ScoDoc 7, vous pouvez migrer +toutes vos données (comptes utilisateurs, étudiants, formations, notes, photos +et fichiers divers) depuis une l'ancien serveur ScoDoc 7, ou même en place. + +Voir [la procédure de migration](MigrationScoDoc7a9.md). + +## En cas de problème + +Ne pas hésiter à nous contacter (voir [contacts](Contact.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)). + +## Ensuite... + +- Mettez en place des [sauvegardes](SauvegardesBases.md) + +- Si vous le souhaitez, vous pouvez mettre en place un anti-virus pour + surveiller les fichiers uploadés par les utilisateurs. Les fichiers sont + conservés dans `/opt/scodoc-data`: le plus simple est de faire surveiller tout + ce répertoire sauf `/opt/scodoc-data/logs`. + +- Abonnez-vous au moins à la liste d'annonces ou rejoignez le Discord: voir [contacts](Contact.md) + +!!! note "Voir aussi" + + - [Guide configuration](GuideConfig.md) + - [Guide administrateur ScoDoc](GuideAdminSys.md) + - [FAQ](FAQ.md) + - [Contacts](Contact.md) diff --git a/docs/UpgradeToDeb12Sco96.md b/docs/UpgradeToDeb12Sco96.md index aea9c16..942fe11 100644 --- a/docs/UpgradeToDeb12Sco96.md +++ b/docs/UpgradeToDeb12Sco96.md @@ -6,6 +6,9 @@ Linux Debian 11 vers la version suivante: ScoDoc 9.6 sous Debian 12. On commence par mettre à jour normalement le système Debian, puis on change la version de la base de données postgresql puis on met à jour ScoDoc. +Si vous souhaitez installer ScoDoc 9.6 sans partir d'un serveur 9.5, +[voir la page d'installation](GuideInstallDebian12.md) + ## Upgrade Debian 11 vers Debian 12 La documentation officielle est là: