From 4091464795a80cab0b261129161836ab0c9a151b Mon Sep 17 00:00:00 2001 From: Mathieu Gauthier-Pilote Date: Fri, 20 Jan 2023 09:31:39 -0500 Subject: [PATCH] =?UTF-8?q?Nouv.=20howto=20pour=20l'=C3=A9diteur=20collab.?= =?UTF-8?q?=20temps-r=C3=A9el=20HedgeDoc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- HowtoHedgeDoc.md | 286 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 286 insertions(+) create mode 100644 HowtoHedgeDoc.md diff --git a/HowtoHedgeDoc.md b/HowtoHedgeDoc.md new file mode 100644 index 00000000..d53a5cc0 --- /dev/null +++ b/HowtoHedgeDoc.md @@ -0,0 +1,286 @@ +--- +categories: web webapp +title: Howto HedgeDoc +... + +* Documentation : +* Code : +* Licence : AGPLv3 +* Langage : Javascript +* Ansible : à venir + +[HedgeDoc](https://github.com/hedgedoc/hedgedoc), anciennement CodiMD, est une application web de rédaction collaborative en temps réel. Construite sur node.js, elle exploite la syntaxe markdown et dispose d'un grand nombre de fonctionnalités. + + +## Installation + +Nous installons la version **1.9.6** sous **Debian 11 (Bullseye)** en mode manuel. (Il y a aussi un mode d'installation pour [Docker et Docker Compose](https://docs.hedgedoc.org/setup/docker/).) + +HedgeDoc s'appuie sur [NodeJS](HowtoNodeJS), [Yarn](HowtoYarn), [node-gyp](https://github.com/nodejs/node-gyp) et peut être configuré avec différents SGBD ([PostgreSQL](HowtoPostgreSQL), MySQL, mariaDB, SQLite) et proxy web ([Nginx](HowtoNginx), Apache). Dans la présente documentation, nous montrons comment faire avec PostgreSQL et Nginx. + +On installe les dépendances de la manière suivante : + +~~~ +# apt install apt-transport-https postgresql nginx git wget +# echo "deb https://deb.nodesource.com/node_16.x $(awk -F= '/VERSION_CODENAME/{print $2}' /etc/os-release) main" > /etc/apt/sources.list.d/nodesource.list +# wget https://deb.nodesource.com/gpgkey/nodesource.gpg.key -O /etc/apt/trusted.gpg.d/nodesource.asc +# chmod 644 /etc/apt/trusted.gpg.d/nodesource.asc +# apt update && apt install nodejs +# npm install --global yarn +# npm install --global node-gyp +~~~ + +### Compte UNIX + +Créer un compte UNIX *hedgedoc* : + +~~~ +# adduser --disabled-login --gecos 'HedgeDoc App' hedgedoc +~~~ + +### PostgreSQL + +Créer la base de données et l'utilisateur PostgreSQL : + +~~~ +# sudo -u postgres createuser hedgedoc -P +# sudo -u postgres createdb hedgedoc +# sudo -u postgres psql +# psql=# grant all privileges on database hedgedoc to hedgedoc; +# exit +~~~ + +> **Note** : Pensez à conserver le mot de passe pour la suite. + + +### HedgeDoc + +On clone le code et on bâtit l'application : + +~~~ +# sudo -iu hedgedoc +$ git clone https://github.com/hedgedoc/hedgedoc.git +$ cd hedgedoc/ +$ git checkout 1.9.6 +$ bin/setup +$ yarn install --frozen-lockfile +$ yarn build +~~~ + +> IMPORTANT : si votre machine dispose de < de 2 Go de RAM, vous ne pourrez bâtir le *frontend* (`yarn build`). Une alternative est d'installer à partir du [paquet tar.gz précompilé](https://github.com/hedgedoc/hedgedoc/releases/download/1.9.6/hedgedoc-1.9.6.tar.gz) par l'équipe de développement. + +On édite le fichier `config.json` généré par `bin/setup`. Vous devrez nécessairement modifier au minimum les valeurs des variables suivantes : `domain` (sous `"production":`), `username`, `password` et `database` (sous `"production":"db":`). + +~~~ +{ + "test": { + "db": { + "dialect": "sqlite", + "storage": ":memory:" + }, + "linkifyHeaderStyle": "gfm" + }, + "development": { + "loglevel": "debug", + "db": { + "dialect": "sqlite", + "storage": "./db.hedgedoc.sqlite" + }, + "domain": "localhost", + "urlAddPort": true + }, + "production": { + "domain": "hedgedoc.evolix.org", + "loglevel": "info", + "protocolUseSSL": "true", + "urlAddPort": false, + "hsts": { + "enable": true, + "maxAgeSeconds": 31536000, + "includeSubdomains": true, + "preload": true + }, + "csp": { + "enable": true, + "directives": { + }, + "upgradeInsecureRequests": "auto", + "addDefaults": true + }, + "cookiePolicy": "lax", + "db": { + "username": "hedgedoc", + "password": "MDP_POSTGRES_NOTE_PLUS_HAUT", + "database": "hedgedoc", + "host": "localhost", + "port": "5432", + "dialect": "postgres" + } + } +} +~~~ + + +### Unités systemd + +Pour lancer l'application au démarrage du serveur, on met le texte suivant le nouveau fichier `/etc/systemd/system/hedgedoc.service` + +~~~ +[Unit] +Description=HedgeDoc - The best platform to write and share markdown. +Documentation=https://docs.hedgedoc.org/ +After=network.target +# Uncomment if you use MariaDB/MySQL +# After=mysql.service +# Uncomment if you use PostgreSQL +After=postgresql.service + +[Service] +Type=exec +Environment=NODE_ENV=production +Restart=always +RestartSec=2s +ExecStart=/usr/bin/yarn start --production +CapabilityBoundingSet= +NoNewPrivileges=true +PrivateDevices=true +RemoveIPC=true +LockPersonality=true +ProtectControlGroups=true +ProtectKernelTunables=true +ProtectKernelModules=true +ProtectKernelLogs=true +ProtectClock=true +ProtectHostname=true +ProtectProc=noaccess +RestrictRealtime=true +RestrictSUIDSGID=true +RestrictNamespaces=true +RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 +ProtectSystem=strict +PrivateTmp=true +SystemCallArchitectures=native +SystemCallFilter=@system-service + +# You may have to adjust these settings +User=hedgedoc +Group=hedgedoc +WorkingDirectory=/home/hedgedoc/hedgedoc + +# Example: local storage for uploads and SQLite +# ReadWritePaths=/opt/hedgedoc/public/uploads /opt/hedgedoc/db + +[Install] +WantedBy=multi-user.target +~~~ + +On active et on démarre l'unité en question : + +~~~ +# systemctl enable hedgedoc.service +# systemctl start hedgedoc.service +~~~ + +### Nginx + +Pour accéder à l'application depuis Internet, on place nginx devant, qui agira comme serveur mandataire (proxy). +Il faut mettre le texte suivant dans le nouveau fichier `/etc/nginx/sites-available/hedgedoc.conf` : + +~~~ +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} + +server { + listen 80; + listen [::]:80; + server_name hedgedoc.evolix.org; + + # Let's Encrypt + include /etc/nginx/snippets/letsencrypt.conf; + + # Redirect all to https (port 443) + location / { return 301 https://$host$request_uri; } +} + +server { + listen [::]:443 ssl http2; + listen 443 ssl http2; + server_name hedgedoc.evolix.org; + + ssl_certificate /etc/letsencrypt/live/hedgedoc.evolix.org/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/hedgedoc.evolix.org/privkey.pem; + + location / { + proxy_pass http://127.0.0.1:3000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + + location /socket.io/ { + proxy_pass http://127.0.0.1:3000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + } +} +~~~ + +> **Note** : La partie SSL/TLS n'est pas développée. Vous pouvez par exemple générer et configurer un certificat [Let's Encrypt](HowtoLetsEncrypt) avec certbot. N'oubliez donc pas de modifier les directives `ssl_` dans le vhost. + +On active le vhost, on vérifie sa syntaxe et si tout est beau on recharge la configuration de nginx : + +~~~ +# ln -s /etc/nginx/sites-available/hedgedoc.conf /etc/nginx/sites-enabled/hedgedoc.conf +# nginx -t +# systemctl reload nginx.service +~~~ + +## Mises à jour + +Les mises à jour peuvent être récupérées comme ceci : + +~~~ +# systemctl stop hedgedoc.service +# sudo -iu hedgedoc +$ cd hedgedoc +$ git fetch origin && git checkout +$ bin/setup +$ yarn install --frozen-lockfile +$ yarn build +$ exit +# systemctl start hedgedoc.service +~~~ + +> **Note** : Ces commandes ne sont parfois pas suffisantes. Vous devez systématiquement lire les [notes de versions](https://github.com/hedgedoc/hedgedoc/releases). + + +## Configuration + +HedgeDoc est configurable via le fichier de config.json ou des variables d'environnement. +L'application est compatible avec divers modes d'athentification (local, ldap, oauth2, saml, etc.) et divers stockages externes (s3, minio, lutim, etc.). +La documentation officielle fournit la liste de toutes les [options de configuration](https://docs.hedgedoc.org/configuration/). + + +## Utilisation + +On peut utiliser en principe n'importe quel navigateur Web pour se connecter à HedgeDoc. +La syntaxe markdown compatible avec l'application fait l'objet d'[une page](https://docs.hedgedoc.org/references/hfm/) de la documentation officielle. +En gros, le standard [CommonMark](https://spec.commonmark.org/) est suivi avec quelques ajouts. + +## FAQ + +### À propos des logs + +On accès à la journalisation des événements de l'application via journald : + +~~~ +# systemctl status hedgedoc.service +# journalctl --unit=hedgedoc +~~~