Come installare BookStack con Nginx su Ubuntu 20.04

BookStack è una piattaforma self-hosted, open-source e facile da usare per organizzare e memorizzare informazioni. Può essere utilizzata per molteplici scopi come un Wiki, un sito di documentazione e un’applicazione per prendere appunti. È costruita utilizzando il framework PHP Laravel e utilizza MySQL per memorizzare i dati. Per scopi di editing, ti offre la scelta tra utilizzare un editor WYSIWYG o un editor Markdown. Supporta l’autenticazione a più fattori e la modalità scura ed è multilingue.

Questo tutorial ti insegnerà come installare BookStack su un server basato su Ubuntu 20.04.

Prerequisiti

1. Un server che esegue Ubuntu 20.04
2. Un Nome di Dominio Completo (FQDN) che punta verso il server.
3. Un utente non root con privilegi sudo.
4. Versione PHP 7.3 o superiore.
5. MySQL>=5.6 e MariaDB>=10.0
6. Git e Composer.

Passo 1 - Configurare il Firewall

Il primo passo è configurare il firewall. Ubuntu viene fornito con ufw (Uncomplicated Firewall) per impostazione predefinita.

Controlla se il firewall è attivo.

$ sudo ufw status

Dovresti ottenere il seguente output.

Status: inactive

Consenti la porta SSH in modo che il firewall non interrompa la connessione attuale quando viene abilitato.

$ sudo ufw allow OpenSSH

Consenti anche le porte HTTP e HTTPS.

$ sudo ufw allow 80
$ sudo ufw allow 443

Abilita il Firewall

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Controlla di nuovo lo stato del firewall.

$ sudo ufw status

Dovresti vedere un output simile.

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

Passo 2 - Installare Git

Il primo passo è installare Git. Sarà necessario per scaricare e aggiornare BookStack. Esegui il seguente comando per installare Git.

$ sudo apt install git

Verifica l’installazione.

$ git --version

Passo 3 - Installare PHP e le estensioni

Poiché BookStack dipende da PHP, è necessario installare PHP e le sue estensioni.

Ubuntu viene fornito con una versione di PHP obsoleta. Prima, dobbiamo aggiungere il repository PHP di Ondrej.

$ sudo add-apt-repository ppa:ondrej/php

Successivamente, installa PHP e le sue estensioni richieste da BookStack.

$ sudo apt install php7.4-fpm php7.4-mbstring php7.4-gd php7.4-xml unzip php7.4-bcmath php7.4-curl php7.4-mysql

Verifica l’installazione.

$ php --version
PHP 7.4.25 (cli) (built: Oct 22 2021 12:34:33) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.25, Copyright (c), by Zend Technologies

Passo 4 - Installare e configurare MariaDB

Ubuntu viene fornito con una versione più vecchia di MariaDB. Per installare l’ultima versione, aggiungi il repository ufficiale di MariaDB. Esegui i seguenti comandi per aggiungere il repository.

$ curl -LsS -O https://downloads.mariadb.com/MariaDB/mariadb_repo_setup
$ sudo bash mariadb_repo_setup --mariadb-server-version=10.6

Esegui il seguente comando per installare il server MariaDB.

$ sudo apt install mariadb-server

Metti in sicurezza l’installazione di MariaDB.

$ sudo mysql_secure_installation

Affronterai vari prompt. Rispondi come segue.

Enter current password for root (enter for none): Press Enter
Switch to unix_socket authentication [Y/n] Type y
Change the root password? [Y/n] Type n
Remove anonymous users? [Y/n] Type y
Disallow root login remotely? [Y/n] Type y
Remove test database and access to it? [Y/n] Type y
Reload privilege tables now? [Y/n] Type y

Connettiti alla shell di MariaDB utilizzando il seguente comando.

$ sudo mysql

Crea un nuovo database per Bookstack.

$ create database bookstack;

Crea un nuovo utente del database.

$ CREATE USER 'bookstackuser'@'localhost' identified by 'bookstackpassword';

Scegli una password forte.

Concedi i permessi sul database all’utente.

$ grant CREATE,ALTER,SELECT,INSERT,UPDATE,DELETE on `bookstack`.* to 'bookstackuser'@'localhost';

Esci dalla shell di MySQL.

$ exit

Passo 5 - Installare Composer

Composer è uno strumento di gestione delle dipendenze per PHP ed è richiesto da Laravel su cui si basa BookStack.

Scarica lo script di installazione di Composer.

$ curl -sS https://getcomposer.org/installer -o composer-setup.php

Esegui i seguenti comandi per verificare l’installer.

$ HASH=`curl -sS https://composer.github.io/installer.sig`
$ echo $HASH
$ php -r "if (hash_file('SHA384', 'composer-setup.php') === '$HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

I comandi sopra ottengono il valore hash dell’installer e lo confrontano con il tuo script scaricato. Dovresti vedere il seguente output se l’installer è sicuro da eseguire.

Installer verified

Installa Composer.

$ sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Verifica l’installazione controllando la sua versione.

$ composer --version
Composer version 2.1.9 2021-10-05 09:47:38

Passo 6 - Scaricare e installare BookStack

Crea la cartella radice per l’app BookStack.

$ sudo mkdir -p /var/www/bookstack

Cambia la proprietà della directory /var/www/bookstack all’utente attualmente connesso.

$ sudo chown -R $USER:$USER /var/www/bookstack

Clona il ramo di rilascio del repository Github di BookStack nella cartella appena creata.

$ cd /var/www/bookstack
$ git clone https://github.com/BookStackApp/BookStack.git --branch=release --single-branch .

Non dimenticare il punto alla fine del comando clone. Assicura che tutti i file vengano scaricati nella directory corrente invece di crearne una nuova.

Esegui l’installer di Composer dalla directory /var/www/bookstack.

$ composer install --no-dev

Copia il file .env.example in .env per memorizzare le variabili ambientali per l’installazione.

$ cp .env.example .env

Apri il file per la modifica.

$ sudo nano .env

Compila l’URL dell’applicazione e i dettagli del database. Se intendi utilizzare le funzionalità email, compila i dettagli SMTP oppure eliminali dal file.

APP_URL=https://example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstackuser
DB_PASSWORD=bookstackpassword

Salva il file premendo Ctrl + X e inserendo Y quando richiesto al termine. Ci sono molte altre impostazioni che puoi configurare. Per saperne di più, apri il file .env.example.complete e copia quelle di cui hai bisogno nel tuo file .env.

Genera una chiave unica per l’applicazione. Questo valore viene automaticamente compilato nel file .env. Digita yes per procedere con il comando.

$ php artisan key:generate
**************************************
*     Application In Production!     *
************************************

 Do you really wish to run this command? (yes/no) [no]:
 > yes

Application key set successfully.

Aggiorna il Database.

$ php artisan migrate
************************************
*     Application In Production!     *
**************************************

 Do you really wish to run this command? (yes/no) [no]:
 > yes
Migration table created successfully.
Migrating: 2014_10_12_000000_create_users_table
Migrated:  2014_10_12_000000_create_users_table (0.12 seconds)
.......

Passo 7 - Installare SSL di Let’s Encrypt

Per installare un certificato SSL utilizzando Let’s Encrypt, dobbiamo installare lo strumento Certbot.

Utilizzeremo l’installer di pacchetti Snapd per questo. La maggior parte dei server Ubuntu non viene fornita con lo strumento Snap. Per risolvere questo problema, installa Snap.

$ sudo apt install snapd

Assicurati che la tua versione di Snapd sia aggiornata.

$ sudo snap install core 
$ sudo snap refresh core

Installa Certbot.

$ sudo snap install --classic certbot

Usa il seguente comando per assicurarti che il comando Certbot possa essere eseguito creando un collegamento simbolico alla directory /usr/bin.

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Verifica l’installazione.

$ certbot --version
certbot 1.20.0

Genera il certificato SSL.

$ sudo certbot certonly --standalone --agree-tos --preferred-challenges http -m [email protected] -d example.com

Il comando sopra scaricherà un certificato nella directory /etc/letsencrypt/live/etherpad.example.com sul tuo server.

Genera un certificato Diffie-Hellman group.

$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Crea una directory web root di sfida per il rinnovo automatico di Let’s Encrypt.

$ sudo mkdir -p /var/lib/letsencrypt

Crea un Cron Job per rinnovare l’SSL. Verrà eseguito ogni giorno per controllare il certificato e rinnovarlo se necessario. Per questo, prima crea il file /etc/cron.daily/certbot-renew e aprilo per la modifica.

$ sudo nano /etc/cron.daily/certbot-renew

Incolla il seguente codice.

#!/bin/sh
certbot renew --cert-name bookstack.example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

Salva il file premendo Ctrl + X e inserendo Y quando richiesto.

Cambia i permessi sul file del task per renderlo eseguibile.

$ sudo chmod +x /etc/cron.daily/certbot-renew

Passo 8 - Installare e configurare Nginx

Ubuntu viene fornito con una versione più vecchia di Nginx. Per installare l’ultima versione, devi scaricare il repository ufficiale di Nginx.

Aggiungi il repository per la versione stabile di Nginx.

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

Installa Nginx.

$ sudo apt install nginx

Verifica l’installazione.

$ nginx -v
nginx version: nginx/1.20.1

Abilita il servizio Nginx.

$ sudo systemctl enable nginx

Configurare PHP-FPM

Apri il file /etc/php/7.4/fpm/pool.d/www.conf.

$ sudo nano /etc/php/7.4/fpm/pool.d/www.conf

Dobbiamo impostare l’utente/gruppo Unix dei processi PHP su nginx. Trova le righe user=www-data e group=www-data nel file e cambiale in nginx.

...
; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
;       will be used.
user = nginx
group = nginx
...

Inoltre, trova le righe listen.owner=www-data e listen.group=www-data nel file e cambiale in nginx.

listen.owner = nginx
listen.group = nginx

Salva il file premendo Ctrl + X e inserendo Y quando richiesto.

Riavvia il processo PHP-fpm.

$ sudo systemctl restart php7.4-fpm

Configurare Nginx

Crea e apri il file /etc/nginx/conf.d/bookstack.conf per la modifica.

$ sudo nano /etc/nginx/conf.d/bookstack.conf

Incolla il seguente codice in esso.

server {
    listen       443 ssl http2;
    listen       [::]:443 ssl http2;
    server_name  bookstack.example.com;

    access_log  /var/log/nginx/bookstack.access.log;
    error_log   /var/log/nginx/bookstack.error.log;
    
    ssl_certificate      /etc/letsencrypt/live/bookstack.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/bookstack.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/bookstack.example.com/chain.pem;

    ssl_session_timeout  5m;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;

    root /var/www/bookstack/public;
    index index.php index.html;

    location / {
      try_files $uri $uri/ /index.php?$query_string;
    }
  
    location ~ \.php$ {
      fastcgi_split_path_info ^(.+\.php)(/.+)$;
      include fastcgi_params;
      fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
      fastcgi_param PATH_INFO $fastcgi_path_info;
      fastcgi_pass unix:/run/php/php7.4-fpm.sock;
    }
}

# enforce HTTPS
server {
    listen       80;
    listen       [::]:80;
    server_name  bookstack.example.com;
    return 301   https://$host$request_uri;
}

Salva il file premendo Ctrl + X e inserendo Y quando richiesto al termine.

Apri il file /etc/nginx/nginx.conf per la modifica.

$ sudo nano /etc/nginx/nginx.conf

Aggiungi la seguente riga prima della riga include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Salva il file premendo Ctrl + X e inserendo Y quando richiesto. Valida di nuovo Nginx.

Verifica la sintassi del file di configurazione di Nginx.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Infine, avvia il servizio Nginx per abilitare la nuova configurazione.

$ sudo systemctl start nginx

Cambia la proprietà della directory all’utente nginx in modo che il server web possa accedere e scrivere nella cartella.

$ sudo chown -R nginx:nginx /var/www/bookstack

Passo 9 - Esegui BookStack

Il tuo Bookstack è pronto per l’uso. Apri l’URL https://bookstack.example.com nel tuo browser e vedrai la pagina di accesso.

Accedi utilizzando l’account amministratore predefinito [email protected] con una password di password. Apri la pagina Impostazioni >> Utenti e fai clic sul pulsante AGGIUNGI NUOVO UTENTE.

Compila i dettagli dell’utente, seleziona la casella Admin sotto Ruoli Utente e deseleziona Invia email di invito all’utente poiché non abbiamo impostato i dettagli SMTP. Seleziona una password forte. Fai clic su Salva quando hai finito.

Successivamente, fai clic sull’utente Admin predefinito e elimina l’utente facendo clic sul pulsante Elimina Utente.

Trasferisci la proprietà dell’utente Admin al tuo nuovo utente selezionandolo dal menu a discesa prima di eliminarlo. Fai clic su Conferma per terminare. Se sei connesso con quell’utente, verrai disconnesso automaticamente. Dovrai accedere di nuovo con il nuovo utente creato.

Backup e ripristino di BookStack

Backup di BookStack

Devi eseguire il backup del database e dei file separatamente. Per eseguire il backup del database, utilizza lo strumento mysqldump.

$ sudo mysqldump -u bookstackuser bookstack > bookstack.backup.sql

Devi eseguire il backup anche dei seguenti file e cartelle.

1. .env - file contenente configurazioni importanti.
2. public/uploads - cartella contenente immagini caricate.
3. storage/uploads - cartella contenente allegati di pagina caricati.

Esegui il seguente comando per creare un archivio compresso dei file e delle cartelle sopra.

$ sudo tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads

Ripristina BookStack

Esegui il seguente comando per ripristinare il database.

$ sudo mysql -u bookstack < bookstack.backup.sql

Se stai ripristinando a una nuova versione di BookStack, dovrai eseguire il comando sudo php artisan migrate.

Per ripristinare i file compressi creati sopra, utilizza il seguente comando.

$ sudo tar -xvzf bookstack-files-backup.tar.gz

Dovrai anche cambiare i permessi.

Aggiorna BookStack

Prima di aggiornare BookStack, assicurati di eseguire un backup adeguato utilizzando il processo menzionato in precedenza.

Per aggiornare BookStack, estrai i file originali dal suo repository Git.

$ cd /var/www/bookstack
$ sudo git pull origin release

Esegui i seguenti comandi per continuare l’installazione.

$ sudo composer install --no-dev
$ sudo php artisan migrate

Dovrai anche eseguire i seguenti comandi per cancellare la cache.

$ sudo php artisan cache:clear
$ sudo php artisan config:clear
$ sudo php artisan view:clear

Conclusione

Questo conclude il nostro tutorial su come installare BookStack su un server Ubuntu 20.04. Se hai domande, postale nei commenti qui sotto.