Update README.md

README.md

@@ -1 +1,571 @@
-# Service PAD
+# Introduction
+
+Documentation à destination d'un administrateur de service pad de Chalec.
+
+L'objectif est d'installer un service basé sur le logiciel Etherpad-lite
+
+Il sera placé en amont, un service nginx qui gèrera le traffic TLS et ses
+
+certificats.
+
+# Base de données (BDD)
+
+Installer la base de données PostgreSQL et démarrer le service associé : 
+
+```
+
+# apt install postgresql postgresql-client
+
+# systemctl enable --now postgresql
+
+```
+
+On vérifie que l'on peut se connecter en IP avec vérification du mot de passe par la BDD. Éditer le fichier `/etc/postgresql/13/main/pg_hba.conf` : 
+
+```
+
+host    all             all             127.0.0.0/24            md5
+
+```
+
+Créer l'utilisateur et la base : 
+
+```
+
+# su - postgres
+
+$ createuser pad
+
+$ createdb pad -O pad
+
+$ psql pad
+
+  ALTER USER pad WITH PASSWORD '<MOTDEPASSE>' ;
+
+    ALTER ROLE;
+
+      \q
+
+      ```
+
+      # Installer Etherpad
+
+      Créer l'utilisateur d'Etherpad : 
+
+      ```
+
+      # adduser etherpad
+
+      ```
+
+      Connecter avec l'utilisateur etherpad : 
+
+      ```
+
+      # su - etherpad
+
+      ```
+
+      Suivre les recommandations de la documentation officielle d'Etherpad pour installer sur Debian :
+
+      ```
+
+      $ cd /home/etherpad
+
+      $ curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
+
+      # apt install -y nodejs
+
+      $ git clone --branch master https://github.com/ether/etherpad-lite.git
+
+      ```
+
+      # Récupérer les ressoures du pad Chalec
+
+      Cloner le dépot Pad de Chalec avec l'utilisateur etherpad : 
+
+      ```
+
+      $ git clone https://git.a-lec.org/a-lec/commissions/chalec/pad
+
+      ```
+
+      # Configuration Etherpad
+
+      Le fichier `/home/etherpad/pad.git/conf/etherpad-lite/settings.json` contient toute la configuration requise.
+
+      Pour une mise en place rapide, vous pouvez remplacer votre fichier settings.json par
+
+      celui-ci. Il faudra néanmoins mettre en place les secrets décrits ci-dessous.
+
+      Dans le cas contraire, si vous souhaitez conserver votre fichier initial,
+
+      veuillez suivre pas à pas cette section.
+
+      Les instructions suivantes s'appliquent au fichier `/home/etherpad/etherpad-lite/settings.json` : 
+
+      ```
+
+      $ cd /homer/etherpad/etherpad-lite 
+
+      ```
+
+      Commenter ou supprimer la BDD par défaut : 
+
+      ```
+
+      /*                                                                                    
+
+        "dbType": "dirty",                                                                  
+
+          "dbSettings": {                                                                     
+
+              "filename": "var/dirty.db"                                                        
+
+                },                                                                                  
+
+                */
+
+                ```
+
+                Décommenter la section `postgres` et compléter avec les secrets :
+
+                ```
+
+                  "dbType" : "postgres",
+
+                    "dbSettings" : {
+
+                        "user":     "pad",
+
+                            "host":     "localhost",
+
+                                  "port":     5432,
+
+                                        "password": "<MOTDEPASSE>",
+
+                                            "database": "pad",
+
+                                                "charset":  "utf8mb4"
+
+                                                  },
+
+                                                  ```
+
+                                                  Indiquer à l'instance qu'elle tourne derrière un proxy et donc que la communication
+
+                                                  est sécurisée même si elle dialogue en HTTP, sans TLS :
+
+                                                  ```
+
+                                                    "trustProxy": true,
+
+                                                    ```
+
+                                                    Configurer l'accès admin web : 
+
+                                                    ```
+
+                                                      "users": {
+
+                                                          "admin666": {
+
+                                                                "password": "<password>",
+
+                                                                      "is_admin": true
+
+                                                                          },
+
+                                                                            },
+
+                                                                            ```
+
+                                                                            Pour la réalisation des tests et la mise en place du pad, il est fortement conseillé
+
+                                                                            de régler le paramètre "minify" à false. Dans le cas contraire, le temps de chargement
+
+                                                                            du premier pad peut-être très long. Penser à reactiver ce paramètre si besoin pour réduire le traffic web.
+
+                                                                            ```
+
+                                                                              "minify": false,
+
+                                                                              ```
+
+                                                                              Personnaliser le titre : 
+
+                                                                              ```
+
+                                                                                "title": "Pad Chalec",
+
+                                                                                ```
+
+                                                                                Placer la favicon dans le dossier `/home/etherpad` et la référencer : 
+
+                                                                                ```
+
+                                                                                  "favicon": "../pad.chalec.org.svg",
+
+                                                                                  ```
+
+                                                                                  Ajouter le skin Chalec qui est basé sur le skin par défaut : 
+
+                                                                                  ```
+
+                                                                                  $ cd /home/etherpad/etherpad-lite/
+
+                                                                                  $ cp -r conf/etherpad-lite/skins/chalec src/static/skins 
+
+                                                                                  ```
+
+                                                                                  et l'activer dans la configuration : 
+
+                                                                                  ```
+
+                                                                                      "skinName": "chalec",
+
+                                                                                      ```
+
+                                                                                      Personnaliser le texte par défaut de la page d'un nouveau pad : 
+
+                                                                                      ```
+
+                                                                                      "defaultPadText" : " <---- Tapez votre texte ici et libre à vous d'effacer cette \
+
+                                                                                      page d'informations.\n\nBienvenue sur pad.chalec.org, un service Chalec, basé sur le \
+
+                                                                                      logiciel libre Etherpad-lite !\n\nNous vous souhaitons une agréable navigation ainsi \
+
+                                                                                      que de partager les valeurs du libre ici ou ailleurs.\n\nQuelques conseils : \n- cons\
+
+                                                                                      ervez pour vous-même l'adresse (URL) de ce pad et communiquez-la à vos collaborateurs\
+
+                                                                                      . Le contenu est synchronisé entre participants ;\n- attention, tout est public ! Mai\
+
+                                                                                      s sans adresse (URL) point d'accès. Ne la partagez pas avec n'importe qui ;\n- choisi\
+
+                                                                                      ssez un pseudonyme et une couleur (bouton en haut à droite) afin que les participants\
+
+                                                                                       puissent identifier l'utilisateur faisant les modifications.\n\nPolitique de conserv\
+
+                                                                                       ation et de suppression des données : \n- effacement à J+6 mois : votre pad est susce\
+
+                                                                                       ptible d'être effacé six mois après la date de dernière modification (utiliser les fo\
+
+                                                                                       nctions d'export si nécessaire) ;\n- nous ne traitons pas de demandes de suppression \
+
+                                                                                       autres que pour des motifs règlementés par la loi française. En effet, nous ne pouvon\
+
+                                                                                       s pas assurément vous identifier comme le propriétaire d'un pad !\n\nConditions Génér\
+
+                                                                                       ales d'Utilisation : \nEn utilisant ce service, vous acceptez tacitement les Conditio\
+
+                                                                                       ns Générales d'Utilisation (CGU) des services Chalec (https://www.chalec.org/CGU) qui\
+
+                                                                                        régissent formellement le service et priment sur toutes autres explications fournies\
+
+                                                                                         sur cette page.\n\nLibrement, \nL'équipe Chalec (https://www.chalec.org),\nCandidat \
+
+                                                                                         CHATONS par Libre en Communs (https://a-lec.org)\nmailto:contact+pad@chalec.org\nxmpp\
+
+                                                                                         :chalec@salons.a-lec.org?join",
+
+                                                                                         ```
+
+                                                                                         # Démarrer le service Etherpad
+
+                                                                                         Tester le démarrer du service etherpad-lite : 
+
+                                                                                         `$ src/bin/run.sh`
+
+                                                                                         Vérifier que le démarrage se passe sans encombre. Puis intérrompre le processus avec : CTRL-C
+
+                                                                                         Copier le fichier de service systemd :
+
+                                                                                         ```
+
+                                                                                         cp /home/etherpad/pad.git/conf/systemd/etherpad.service /etc/systemd/system/
+
+                                                                                         ```
+
+                                                                                         Activer et démarrer le service :
+
+                                                                                         ```
+
+                                                                                         systemctl enable --now etherpad
+
+                                                                                         ```
+
+                                                                                         Vérifier que le service tourne :
+
+                                                                                         ```
+
+                                                                                         systemctl status etherpad
+
+                                                                                         ```
+
+                                                                                         # Installation du proxy nginx
+
+                                                                                         Installer nginx et préparer le dossier de logs :
+
+                                                                                         ```
+
+                                                                                         # apt install nginx
+
+                                                                                         # mkdir /var/log/nginx/pad.chalec.org
+
+                                                                                         # chown www-data:www-data /var/log/nginx/pad.chalec.org
+
+                                                                                         ```
+
+                                                                                         Enregistrer le fichier de configuration de site nginx `/home/etherpad/pad.git/conf/nginx/sites-available/etherpad` à cet emplacement /etc/nginx/sites-available/etherpad et faire un lien symbolique dans  /etc/nginx/sites-available/etherpad : 
+
+                                                                                         ```
+
+                                                                                         # cp /home/etherpad/pad.git/conf/nginx/conf.d/* /etc/nginx/conf.d/
+
+                                                                                         # cd /etc/nginx/sites-enabled
+
+                                                                                         # ln -s ../sites-available/etherpad .
+
+                                                                                         ```
+
+                                                                                         Créer les certificats :
+
+                                                                                         ```
+
+                                                                                         # certbot certonly --nginx -d pad.chalec.org
+
+                                                                                         ```
+
+                                                                                         Démarrer le service nginx : 
+
+                                                                                         ```
+
+                                                                                         # systemctl enable --now nginx
+
+                                                                                         ```
+
+                                                                                         Ouvrir les ports du firewall : 
+
+                                                                                         ```
+
+                                                                                         # ufw allow proto tcp port 80,443
+
+                                                                                         ```
+
+                                                                                         Vérifier que le service répond en se rendant aux addresses suivantes : 
+
+                                                                                         ```
+
+                                                                                         http://pad.chalec.org
+
+                                                                                         https://pad.chalec.org
+
+                                                                                         ```
+
+                                                                                         # Installation des Greffons etherpad
+
+                                                                                         Pour complémenter l'installation de base d'Etherpad, il faut ajouter quelques
+
+                                                                                         greffons.
+
+                                                                                         Installer les greffons suivants en se rendant sur la page d'administration
+
+                                                                                         https://pad.chalec.org/admin :
+
+                                                                                         - adminpads2 : lister les pads et par exemple de les supprimer
+
+                                                                                         - align : aligner à gauche / droite / centrer
+
+                                                                                         - author_hover : afficher l'auteur d'un texte en survolant avec la souris
+
+                                                                                         - delete_after_delay : supprimer automatiquement un pad après un certain délais d'inactivité
+
+                                                                                         - delete_empty_pads : supprimer automatiquement un pad vide
+
+                                                                                         - font_color : utiliser des couleurs dans le texte
+
+                                                                                         - font_size : utiliser des polices de différentes tailles
+
+                                                                                         - headings2 : titres et sous-titres
+
+                                                                                         - table_of_contents : table des matières
+
+                                                                                         - spellcheck
+
+                                                                                         - markdown
+
+                                                                                         Note : il existe une méthode pour installer cela en ligne de commande. @todo
+
+                                                                                         ## Export libreoffice
+
+                                                                                         Pour supporter l'export au format ODT, installer libreoffice :
+
+                                                                                         ```
+
+                                                                                         # apt install libreoffice-nogui
+
+                                                                                         ```
+
+                                                                                         Puis configurer le chemin du binaire dans le `settings.json` : 
+
+                                                                                         ```
+
+                                                                                           "soffice": "/usr/bin/soffice",
+
+                                                                                           ```
+
+                                                                                           Ajouter le module de table des matières "table_of_contents" et configurer pour le
+
+                                                                                           désactiver par défaut (bug upstream, configuration non prise en compte, cf. #1) : 
+
+                                                                                           ```
+
+                                                                                               "ep_toc": {
+
+                                                                                               	"disable_by_default": true
+
+                                                                                                       },
+
+                                                                                                       ```
+
+                                                                                                       Ajouter le module de suppression automatique des pads inactif "delete_after_delay"
+
+                                                                                                       et le configurer à J + six mois (temps en secondes).
+
+                                                                                                       Indiquer qu'on fait la suppression au lancement et non de manière régulière en tâche de fond. En effet, il n'y a aucune urgence à faire ce genre de tâche.
+
+                                                                                                       ```
+
+                                                                                                           "ep_delete_after_delay": {
+
+                                                                                                           	"delay": 15811200, // 6 * 30.5 * 24 * 3600 
+
+                                                                                                               	"loop": false,
+
+                                                                                                                   	"deleteAtStart": true,
+
+                                                                                                                       	"text": ""
+
+                                                                                                                               },
+
+                                                                                                                               ```
+
+                                                                                                                               # Securité et limites
+
+                                                                                                                               Paramétrer un buffer HTTP suffisamment grand pour notament importer des pads jusqu'à 20Mo dans le fichier `/home/etherpad/etherpad-lite/settings.json`:
+
+                                                                                                                               ```
+
+                                                                                                                                socketIo {
+
+                                                                                                                                  [...]
+
+                                                                                                                                    
+
+                                                                                                                                       "maxHttpBufferSize": 20000000
+
+                                                                                                                                       ```
+
+                                                                                                                                       Puis augmenter, dans la même section, la limite sur import et export : 
+
+                                                                                                                                       ```
+
+                                                                                                                                         "importExportRateLimiting": {
+
+                                                                                                                                             // duration of the rate limit window (milliseconds)
+
+                                                                                                                                                 "windowMs": 90000,
+
+                                                                                                                                                     // maximum number of requests per IP to allow during the rate limit window
+
+                                                                                                                                                         "max": 10
+
+                                                                                                                                                           },
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           # Chalec infos
+
+                                                                                                                                                           Intaller Java : 
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           # apt install openjdk-jre-headless
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           Ajouter l'utilisateur statoolinfos : 
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           # adduser statoolinfos
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           Ajouter l'utilisateur statoolinfos au group admin pour qu'il puisse lire les logs : 
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           # adduser statoolinfos admin
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           Se connecter avec le nouvel utilisateur :
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           # su - statoolinfos
+
+                                                                                                                                                           $ cd
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           Télécharger le binaire (jar) Statoolinfos à l'adresse suivante :
+
+                                                                                                                                                           `https://forge.devinsy.fr/devinsy/statoolinfos/releases`
+
+                                                                                                                                                           Décompresser dans `/home/statoolinfos/statool-<version>`
+
+                                                                                                                                                           Faire un lien générique pour avoir un nom de dossier invariant "statoolinfos" :
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           $ ln -s statoolinfos-<verion> statoolinfos
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           Copier les fichiers html : 
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           cp -r /home/etherpad/pad.git/html/ /var/www/
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           Restaurer la configuration statoolinfos :
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           cp /home/etherpad/pad.git/conf/statoolinfos/pad.chalec.org.conf /home/statoolinfos/conf/
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           Lancer une génération maximale des métriques : 
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           /home/statoolinfos/statoolinfos/statoolinfos.sh probe -full /home/statoolinfos/statoolinfos/conf/pad.chalec.org.conf
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           Configurer le cron quotidien : 
+
+                                                                                                                                                           ```
+
+                                                                                                                                                           $ crontab -e
+
+                                                                                                                                                           23 55 * * * /home/statoolinfos/statoolinfos/statoolinfos.sh probe -previousday /home/statoolinfos/statoolinfos/conf/pad.chalec.org.conf >> /home/statoolinfos/statoolinfos.log
+
+                                                                                                                                                           ```