HedgeDoc

Ci siamo occupati già in passato di markdown in diverse occasioni. Riteniamo markdown una risorsa essenziale

HedgeDoc è una risorsa software open source, web-based, che consiste in un editor markdown collaborativo.

In sostanza, con HedgeDoc è possibile scrivere documenti in markdown utilizzando l’interfaccia web mediante il browser e condividerli con altri, sia in sola lettura sia autorizzando l’editing a seconda dei permessi che si intendono impostare.

È possibile utilizzare HedgeDoc in modalità self-hosted, installandolo sul proprio server.

Il codice sorgente è disponibile su GitHub.

HedgeDoc deriva dal fork di CodiMD, come è spiegato nella pagina della sua storia.

Il progetto HedgeDoc è seguito dal Team Core Developers.

Installazione

Per l’installazione di HedgeDoc si possono consultare le istruzioni disponibili sulla pagina ufficiale.

HedgeDoc si può installare da immagine Docker oppure manualmente.

Installazione manuale

Abbiamo optato per l’installazione manuale, probabilmente meno semplice di quella mediante immagine docker.

Sono necessari dei prerequisiti sul server.

Abbiamo seguito i seguenti step per installare HedgeDoc su un server con Ubuntu 20.04.

Aggiornamento del sistema

aggiornare il sistema con

apt update && apt upgrade -y

Creazione di utente e gruppo

Creare l’utente hedgedoc e il gruppo hedgedoc con

adduser hedgedoc

Il sistema risponderà come segue:

Adding user `hedgedoc' ...
Adding new group `hedgedoc' (1001) ...
Adding new user `hedgedoc' (1001) with group `hedgedoc' ...
Creating home directory `/home/hedgedoc' ...
Copying files from `/etc/skel' ...
New password:

A questo punto, si può procedere con invio per non dare alcuna password fino alla fine confermando con Y e si avrà la risposta seguente:

Retype new password:
No password supplied
New password:
Retype new password:
No password supplied
New password:
Retype new password:
No password supplied
passwd: Authentication token manipulation error
passwd: password unchanged
Try again? [y/N] n
Changing the user information for hedgedoc
Enter the new value, or press ENTER for the default
	Full Name []:
	Room Number []:
	Work Phone []:
	Home Phone []:
	Other []:
Is the information correct? [Y/n] Y

Database (PostgreSQL)

La procedura che segue dovrebbe creare automaticamente il database, ma nel nostro caso abbiamo dovuto provvedere manualmente come segue:

spostarsi sull’utente postgres con

su postgres

quindi accedere al database PostgteSQL con

psql

creare il database hedgedoc con il comando

CREATE DATABASE hedgedoc;

creare l’utente hedgedoc con la password con il comando (sostituire ‘password’ con una propria)

ALTER USER hedgedoc password 'password';

garantire i privilegi all’utente hedgedoc sul database hedgedoc con

GRANT ALL privileges on database hedgedoc to hedgedoc;

uscire da PostgreSQL con

\q

e poi digitare

exit

Download dell’ultima versione disponibile e decomprimere il file

scaricare l’ultima versione disponibile (nel nostro caso la 1.9.3)

wget https://github.com/hedgedoc/hedgedoc/releases/download/1.9.3/hedgedoc-1.9.3.tar.gz

decomprimere il file in una cartella (abbiamo scelto /opt/hedgedoc) e quindi:

cd /opt

e poi

tar -xzvf hedgedoc-1.9.3.tar.gz

Permessi

Bisogna attribuire i permessi alla cartella /op/hedgedoc con il seguente comando:

chown -R hedgedoc:hedgedoc /opt/hedgedoc

Installazione

A questo punto, spostarsi nella cartella /op/hedgedoc con

cd /opt/hedgedoc

Lanciare il file di setup che creerà il file config.json

./bin/setup

Configurazione

È necessario generare un codice segreto da inserire nel file config.json e quindi lanciamo il comando

pwgen -s 64 1

Sarà generato un codice che dovremo copiare per utilizzarlo all’interno del file config.json

Editare il file config.json con

nano config.json

La configurazione è fondamentale perché la fase successiva si baserà sul contenuto del file config.json. Per comodità, riportiamo di seguito il contenuto del nostro config.json

{
    "production": {
        "domain": "domainname",
        "loglevel": "info",
        "hsts": {
            "enable": true,
            "maxAgeSeconds": 31536000,
            "includeSubdomains": true,
            "preload": true
        },
        "csp": {
            "enable": true,
            "directives": {
            },
            "upgradeInsecureRequests": "auto",
            "addDefaults": true,
            "addDisqus": true,
            "addGoogleAnalytics": false
        },
        "cookiePolicy": "lax",
        "db": {
            "username": "hedgedoc",
            "password": "password",
            "database": "hedgedoc",
            "host": "localhost",
            "port": "5432",
            "dialect": "postgres"
        },
        "sessionSecret": "insert your secret here",
        "port": "3220",
        "email": true,
        "allowEmailRegister": false,
        "protocolUseSSL": true,
        "urlAddPort": false
        }
}

Abbiamo eliminato le impostazioni relative a development lasciando unicamente production perché abbiamo utilizzato un nostro nome a dominio.

Nel nostro caso, poiché la porta 3000 è impegnata da un altro servizio, l’abbiamo modificata con la porta 3220. Se non ci sono motivi particolari, si può evitare di aggiungere la riga "port": "3220", perché la porta di default sarà 3000.

Realizzare il frontend (possibile)

Completata la configurazione, si procede lanciando il seguente comando

yarn install --frozen-lockfile

Verifica dell’installazione

Successivamente lanciare il seguente comando

yarn build

Per verificare che l’installazione sia andata a buon fine e non ci siano errori, all’interno della cartella /opt/hedgedoc si lancia il seguente comando

NODE_ENV=production yarn start

Se tutto è andato bene, il servizio risulterà attivo, diversamente saranno indicati gli errori da verificare.

Impostare il reverse proxy con NGINX

Abbiamo impostato il reverse proxy con NGINX seguendo le indicazioni e il template disponibile a questa pagina.

Quindi abbiamo creato il file hedgedoc.conf come di seguito

cd /etc/nginx/sites-available

e poi

nano hedgedoc.conf

Quindi abbiamo incollato il contenuto del file di NGINX come riportiamo di seguito

map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
}
server {
        server_name hedgedoc.example.com;

        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;
        }
}

N.B.: abbiamo lasciato il proxy_pass sulla porta 3000 ma - nel nostro caso - abbiamo dovuto modificare con la porta 3220.

Quindi, salviamo il file con CTRL+X e poi ripondiamo Y

A questo punto verifichiamo che NGINX non generi errori con il comando

nginx -t

Se la risposta sarà OK, tutto sarà impostato regolarmente.

A questo punto riavviamo il servizio di NGINX con il comando

systemctl restart nginx

Creare il certificato SSL e redirect su HTTPS

Lanciare il seguente comando

certbot --nginx

Seguire le indicazioni, selezionando il nome a dominio che si intende utilizzare per HedgeDoc.

Impostare il servizio Systemd

A questa pagina è disponibile il contenuto del file per il servizio systemd.

Procediamo con la creazione del file come di seguito:

ci spostiamo nella cartella /etc/systemd/system con il comando

cd /etc/systemd/system

Quindi, creiamo il file hedgedoc.service con il comando

nano hedgedoc.service

Incolliamo il contenuto del file. Per comodità riportiamo il contenuto del nostro file 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
ProtectHome=false
PrivateTmp=true
SystemCallArchitectures=native
SystemCallFilter=@system-service

# You may have to adjust these settings
User=hedgedoc
Group=hedgedoc
WorkingDirectory=/opt/hedgedoc

# Example: local storage for uploads and SQLite
ReadWritePaths=/opt/hedgedoc/public/uploads

[Install]
WantedBy=multi-user.target

Quindi, salviamo il file con CTRL+X e poi ripondiamo Y

A questo punto, avviamo il servizio con i comandi seguenti:

systemctl enable hedgedoc.service

e poi

systemctl start hedgedoc.service

Conclusioni

Se tutto è andato bene, il servizio sarà disponibile raggiungendo la pagina del nome a dominio che abbiamo scelto per HedgeDoc.

Se questa risorsa è stata utile, potreste contribuire con

Buy me a coffee

o donare via

Liberapay

Follow us on Mastodon

Stay tuned!

HedgeDoc#

Installazione#

Installazione manuale#

Aggiornamento del sistema#

Creazione di utente e gruppo#

Database (PostgreSQL)#

Download dell’ultima versione disponibile e decomprimere il file#

Permessi#

Installazione#

Configurazione#

Realizzare il frontend (possibile)#

Verifica dell’installazione#

Impostare il reverse proxy con NGINX#

Creare il certificato SSL e redirect su HTTPS#

Impostare il servizio Systemd#

Conclusioni#

HedgeDoc

Installazione

Installazione manuale

Aggiornamento del sistema

Creazione di utente e gruppo

Database (PostgreSQL)

Download dell’ultima versione disponibile e decomprimere il file

Permessi

Installazione

Configurazione

Realizzare il frontend (possibile)

Verifica dell’installazione

Impostare il reverse proxy con NGINX

Creare il certificato SSL e redirect su HTTPS

Impostare il servizio Systemd

Conclusioni