Comment installer BookStack avec Nginx sur Ubuntu 20.04

BookStack est une plateforme auto-hébergée, open-source et facile à utiliser pour organiser et stocker des informations. Elle peut être utilisée à diverses fins comme un Wiki, un site de documentation et une application de prise de notes. Elle est construite avec le framework PHP Laravel et utilise MySQL pour stocker les données. Pour les besoins d’édition, elle vous offre le choix entre un éditeur WYSIWYG ou un éditeur Markdown. Elle prend en charge l’authentification multi-facteurs et le mode sombre et est multilingue.

Ce tutoriel vous apprendra à installer BookStack sur un serveur basé sur Ubuntu 20.04.

Prérequis

1. Un serveur exécutant Ubuntu 20.04
2. Un nom de domaine entièrement qualifié (FQDN) pointant vers le serveur.
3. Un utilisateur non-root avec des privilèges sudo.
4. PHP version 7.3 ou supérieure.
5. MySQL>=5.6 et MariaDB>=10.0
6. Git et Composer.

Étape 1 - Configurer le pare-feu

La première étape consiste à configurer le pare-feu. Ubuntu est livré avec ufw (Uncomplicated Firewall) par défaut.

Vérifiez si le pare-feu est en cours d’exécution.

$ sudo ufw status

Vous devriez obtenir la sortie suivante.

Status: inactive

Autorisez le port SSH afin que le pare-feu ne rompe pas la connexion actuelle lors de son activation.

$ sudo ufw allow OpenSSH

Autorisez également les ports HTTP et HTTPS.

$ sudo ufw allow 80
$ sudo ufw allow 443

Activez le pare-feu

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

Vérifiez à nouveau l’état du pare-feu.

$ sudo ufw status

Vous devriez voir une sortie similaire.

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)

Étape 2 - Installer Git

La première étape consiste à installer Git. Il sera nécessaire pour télécharger et mettre à jour BookStack. Exécutez la commande suivante pour installer Git.

$ sudo apt install git

Vérifiez l’installation.

$ git --version

Étape 3 - Installer PHP et les extensions

Puisque BookStack dépend de PHP, vous devez installer PHP et ses extensions.

Ubuntu est livré avec une version PHP obsolète. Tout d’abord, nous devons ajouter le dépôt PHP d’Ondrej.

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

Ensuite, installez PHP et ses extensions requises par 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

Vérifiez l’installation.

$ 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

Étape 4 - Installer et configurer MariaDB

Ubuntu est livré avec une version plus ancienne de MariaDB. Pour installer la dernière version, ajoutez le dépôt officiel de MariaDB. Exécutez les commandes suivantes pour ajouter le dépôt.

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

Exécutez la commande suivante pour installer le serveur MariaDB.

$ sudo apt install mariadb-server

Sécurisez l’installation de MariaDB.

$ sudo mysql_secure_installation

Vous serez confronté à divers prompts. Répondez comme suit.

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

Connectez-vous à l’interface de commande de MariaDB en utilisant la commande suivante.

$ sudo mysql

Créez une nouvelle base de données pour Bookstack.

$ create database bookstack;

Créez un nouvel utilisateur de base de données.

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

Choisissez un mot de passe fort.

Accordez des permissions sur la base de données à l’utilisateur.

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

Quittez l’interface de commande MySQL.

$ exit

Étape 5 - Installer Composer

Composer est un outil de gestion des dépendances pour PHP et est requis par Laravel sur lequel BookStack est basé.

Téléchargez le script d’installation de Composer.

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

Exécutez les commandes suivantes pour vérifier l’installateur.

$ 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;"

Les commandes ci-dessus récupèrent la valeur de hachage de l’installateur et la comparent avec votre script téléchargé. Vous devriez voir la sortie suivante si l’installateur est sûr à exécuter.

Installer verified

Installez Composer.

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

Vérifiez l’installation en vérifiant sa version.

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

Étape 6 - Télécharger et installer BookStack

Créez le dossier racine pour l’application BookStack.

$ sudo mkdir -p /var/www/bookstack

Changez la propriété du répertoire /var/www/bookstack à l’utilisateur actuellement connecté.

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

Clonez la branche de version du dépôt Github de BookStack dans le dossier nouvellement créé.

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

Ne manquez pas le point à la fin de la commande clone. Cela garantit que tous les fichiers sont téléchargés dans le répertoire actuel au lieu de créer un nouveau.

Exécutez l’installateur Composer depuis le répertoire /var/www/bookstack.

$ composer install --no-dev

Copiez le fichier .env.example en .env pour stocker les variables d’environnement pour l’installation.

$ cp .env.example .env

Ouvrez le fichier pour l’éditer.

$ sudo nano .env

Remplissez l’URL de l’application et les détails de la base de données. Si vous allez utiliser les fonctionnalités d’email, remplissez les détails SMTP ou sinon supprimez-les du fichier.

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

Enregistrez le fichier en appuyant sur Ctrl + X et en entrant Y lorsque vous y êtes invité une fois terminé. Il y a beaucoup plus de paramètres que vous pouvez configurer. Pour en savoir plus à leur sujet, ouvrez le fichier .env.example.complete et copiez ceux dont vous avez besoin dans votre fichier .env.

Générez une clé d’application unique. Cette valeur est automatiquement remplie dans le fichier .env. Tapez yes pour procéder à la commande.

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

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

Application key set successfully.

Mettez à jour la base de données.

$ 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)
.......

Étape 7 - Installer le SSL Let’s Encrypt

Pour installer un certificat SSL en utilisant Let’s Encrypt, nous devons installer l’outil Certbot.

Nous utiliserons l’installateur de paquets Snapd pour cela. La plupart des serveurs Ubuntu ne sont pas livrés avec l’outil Snap. Pour corriger cela, installez Snap.

$ sudo apt install snapd

Assurez-vous que votre version de Snapd est à jour.

$ sudo snap install core 
$ sudo snap refresh core

Installez Certbot.

$ sudo snap install --classic certbot

Utilisez la commande suivante pour vous assurer que la commande Certbot peut être exécutée en créant un lien symbolique vers le répertoire /usr/bin.

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

Vérifiez l’installation.

$ certbot --version
certbot 1.20.0

Générez le certificat SSL.

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

La commande ci-dessus téléchargera un certificat dans le répertoire /etc/letsencrypt/live/etherpad.example.com sur votre serveur.

Générez un certificat de groupe Diffie-Hellman.

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

Créez un répertoire racine de défi pour le renouvellement automatique de Let’s Encrypt.

$ sudo mkdir -p /var/lib/letsencrypt

Créez un Cron Job pour renouveler le SSL. Il s’exécutera tous les jours pour vérifier le certificat et le renouveler si nécessaire. Pour cela, créez d’abord le fichier /etc/cron.daily/certbot-renew et ouvrez-le pour l’éditer.

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

Collez le code suivant.

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

Enregistrez le fichier en appuyant sur Ctrl + X et en entrant Y lorsque vous y êtes invité.

Changez les permissions sur le fichier de tâche pour le rendre exécutable.

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

Étape 8 - Installer et configurer Nginx

Ubuntu est livré avec une version plus ancienne de Nginx. Pour installer la dernière version, vous devez télécharger le dépôt officiel de Nginx.

Ajoutez le dépôt pour la version stable de 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

Installez Nginx.

$ sudo apt install nginx

Vérifiez l’installation.

$ nginx -v
nginx version: nginx/1.20.1

Activez le service Nginx.

$ sudo systemctl enable nginx

Configurer PHP-FPM

Ouvrez le fichier /etc/php/7.4/fpm/pool.d/www.conf.

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

Nous devons définir l’utilisateur/groupe Unix des processus PHP sur nginx. Trouvez les lignes user=www-data et group=www-data dans le fichier et changez-les en 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
...

De plus, trouvez les lignes listen.owner=www-data et listen.group=www-data dans le fichier et changez-les en nginx.

listen.owner = nginx
listen.group = nginx

Enregistrez le fichier en appuyant sur Ctrl + X et en entrant Y lorsque vous y êtes invité.

Redémarrez le processus PHP-fpm.

$ sudo systemctl restart php7.4-fpm

Configurer Nginx

Créez et ouvrez le fichier /etc/nginx/conf.d/bookstack.conf pour l’éditer.

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

Collez le code suivant dedans.

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

Enregistrez le fichier en appuyant sur Ctrl + X et en entrant Y lorsque vous y êtes invité une fois terminé.

Ouvrez le fichier /etc/nginx/nginx.conf pour l’éditer.

$ sudo nano /etc/nginx/nginx.conf

Ajoutez la ligne suivante avant la ligne include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Enregistrez le fichier en appuyant sur Ctrl + X et en entrant Y lorsque vous y êtes invité. Validez à nouveau Nginx.

Vérifiez la syntaxe du fichier de configuration 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

Enfin, démarrez le service Nginx pour activer la nouvelle configuration.

$ sudo systemctl start nginx

Changez la propriété du répertoire à l’utilisateur nginx afin que le serveur web puisse accéder et écrire dans le dossier.

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

Étape 9 - Exécuter BookStack

Votre Bookstack est prêt à être utilisé. Ouvrez l’URL https://bookstack.example.com dans votre navigateur et vous obtiendrez la page de connexion.

Connectez-vous avec le compte administrateur par défaut [email protected] avec un mot de passe de password. Ouvrez la page Paramètres >> Utilisateurs et cliquez sur le bouton AJOUTER UN NOUVEAU UTILISATEUR.

Remplissez les détails de l’utilisateur, cochez la case Admin sous Rôles d’utilisateur et décochez Envoyer un e-mail d’invitation à l’utilisateur puisque nous n’avons pas défini les détails SMTP. Sélectionnez un mot de passe fort. Cliquez sur Enregistrer lorsque vous avez terminé.

Ensuite, cliquez sur l’utilisateur Admin par défaut et supprimez l’utilisateur en cliquant sur le bouton Supprimer l’utilisateur.

Transférez la propriété de l’utilisateur Admin à votre nouvel utilisateur créé en le sélectionnant dans le menu déroulant avant de le supprimer. Cliquez sur Confirmer pour terminer. Si vous êtes connecté avec cet utilisateur, vous serez automatiquement déconnecté. Vous devrez vous reconnecter avec le nouvel utilisateur créé.

Sauvegarder et restaurer BookStack

Sauvegarder BookStack

Vous devez sauvegarder la base de données et les fichiers séparément. Pour sauvegarder la base de données, utilisez l’outil mysqldump.

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

Vous devez également sauvegarder les fichiers et dossiers suivants.

1. .env - fichier contenant des configurations importantes.
2. public/uploads - dossier contenant des images téléchargées.
3. storage/uploads - dossier contenant des pièces jointes de page téléchargées.

Exécutez la commande suivante pour créer une archive compressée des fichiers et dossiers ci-dessus.

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

Restaurer BookStack

Exécutez la commande suivante pour restaurer la base de données.

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

Si vous restaurez vers une nouvelle version de BookStack, vous devrez exécuter la commande sudo php artisan migrate.

Pour restaurer les fichiers compressés créés ci-dessus, utilisez la commande suivante.

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

Vous devrez également changer les permissions.

Mettre à jour BookStack

Avant de mettre à jour BookStack, assurez-vous de faire une sauvegarde appropriée en utilisant le processus mentionné précédemment.

Pour mettre à jour BookStack, tirez les fichiers originaux de son dépôt Git.

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

Exécutez les commandes suivantes pour continuer l’installation.

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

Vous devrez également exécuter les commandes suivantes pour vider le cache.

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

Conclusion

Cela conclut notre tutoriel sur l’installation de BookStack sur un serveur Ubuntu 20.04. Si vous avez des questions, postez-les dans les commentaires ci-dessous.