Héberger BookStack sur un VPS infogéré : votre documentation chez vous

Ce que fait BookStack

BookStack est une plateforme de documentation pensée pour rester simple : son README vise une prise en main immédiate, avec de simples notions de traitement de texte. Vos équipes y écrivent leurs procédures, leur documentation et leur base de connaissances, dans un navigateur, en français si elles le souhaitent.

• Quatre niveaux de rangement : les étagères regroupent des livres, les livres portent des chapitres et des pages, les chapitres sont facultatifs, et le contenu vit dans les pages.
• Deux éditeurs : un éditeur visuel par défaut, et un éditeur Markdown avec aperçu en direct, auxquels s'ajoutent les schémas diagrams.net.
• La recherche : dans un livre, ou sur l'ensemble des livres, chapitres et pages.
• Les droits : des rôles pour tout le système, et des permissions propres à une étagère, un livre, un chapitre ou une page.
• Les connexions : e-mail et mot de passe, OpenID Connect, SAML 2.0, LDAP, avec une double authentification par application ou par codes de secours, que l'on peut imposer par rôle.
• Le suivi et les échanges : l'historique des révisions de chaque page, une API REST, et l'export en HTML, PDF, texte, Markdown ou ZIP portable.

Le projet assume ses choix : son README précise que BookStack n'est pas conçu comme une plateforme extensible vers d'autres usages, et il reste tenu à la documentation. Son rendu PDF passe par dompdf, sans installation de plus, avec des capacités limitées ; le projet documente d'autres moteurs avec EXPORT_PDF_COMMAND.

Ce que permet la licence MIT

BookStack est publié sous licence MIT par Dan Brown et les contributeurs du projet. Elle autorise tout usage, toute modification et toute distribution, à une condition : garder la mention de copyright et le texte de la licence dans toute copie du logiciel. La FAQ du projet précise que cette attribution porte sur le code que vous partagez : rien ne vous oblige à afficher le nom ou le logo de BookStack sur votre instance.

Le projet tient une seule version, libre et gratuite : il ne propose pas d'édition entreprise, et il n'a pas d'hébergement officiel, ni de projet d'en ouvrir un. Il vend en revanche des formules de support, qui contribuent à son financement avec les dons et les parrainages. BookStack s'installe donc sur votre serveur, sans licence à acheter.

Les prérequis de BookStack

Docker reste facultatif. Le projet ne publie pas d'image officielle : les installations en conteneur viennent de projets communautaires, LinuxServer.io et solidnerd. Ce guide suit la voie officielle, PHP et MySQL directement sur le serveur, qui ne demande rien de plus.

La documentation écarte l'hébergement PHP mutualisé : BookStack demande un serveur que vous administrez. Elle ne chiffre ni la mémoire ni le processeur nécessaires. Sur un VPS infogéré, décrivez-nous votre usage, le nombre de personnes et le volume d'images et de pièces jointes, et nous vous recommandons la taille qui convient.

L'installation de BookStack

Le projet propose deux voies : un script pour Ubuntu, le plus court sur un serveur neuf, et une installation manuelle pour tous les autres cas.

Avec le script du projet, sur un Ubuntu tout neuf

wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-24.04.sh
chmod a+x installation-ubuntu-24.04.sh
sudo ./installation-ubuntu-24.04.sh

Ces scripts sont réservés à un système fraîchement installé : ils peuvent écraser une configuration web existante. Ils laissent aussi de côté deux sujets, les réglages d'e-mail et la sécurité du système, à prévoir à part.

Le script pose BookStack dans /var/www/bookstack. Celui d'Ubuntu 26.04 demande le domaine et l'adresse du compte administrateur, puis affiche à la fin un mot de passe tiré au hasard, absent de son journal : notez-le. Avec un autre script, relevez les accès affichés à la fin et changez tout accès par défaut dès la première connexion.

À la main, sur toute autre machine

Commencez par la base de données : une base, et un utilisateur limité à cette base. Le script du projet procède ainsi, avec le mot de passe de votre choix à la place de change-me :

sudo mysql -u root --execute="CREATE DATABASE bookstack;"
sudo mysql -u root --execute="CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'change-me';"
sudo mysql -u root --execute="GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';FLUSH PRIVILEGES;"

Récupérez ensuite la branche release, posez les droits que la documentation donne pour /var/www/bookstack, puis installez les dépendances :

cd /var/www
sudo git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack
sudo chown -R $USER:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack
sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
cd bookstack
composer install --no-dev
cp .env.example .env
sudo chmod 640 .env

Renseignez la base et l'adresse dans .env :

APP_URL=https://docs.example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=change-me

php artisan key:generate
php artisan migrate

Pointez enfin la racine web sur le dossier public : DocumentRoot sur Apache, root sur Nginx. Sans Apache, ou quand les fichiers .htaccess sont désactivés, ajoutez les règles de réécriture d'adresses : le projet publie des exemples pour Apache et pour Nginx.

Une installation manuelle s'ouvre avec le compte admin@admin.com et le mot de passe password. Changez l'adresse et le mot de passe dès la première connexion.

HTTPS et APP_URL

Les visiteurs arrivent sur les ports 80 et 443, sous le nom de domaine du serveur. Créez pour ce nom des enregistrements A et AAAA, puis demandez le certificat : le script d'Ubuntu 26.04 configure Apache sur le port 80 seul, et la page d'installation laisse HTTPS à votre main. Certbot pose le certificat Let's Encrypt, adapte Apache et renouvelle le certificat de lui-même. Sous Nginx, remplacez --apache par --nginx.

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
sudo certbot --apache -d docs.example.com

Passez ensuite l'adresse en HTTPS dans .env. APP_URL doit correspondre exactement à l'adresse de visite, préfixe compris : un écart se voit par des styles absents, des icônes démesurées et des menus cassés. Une adresse en https active d'elle-même les cookies sécurisés.

APP_URL=https://docs.example.com

Si des pages existent déjà, leurs liens gardent l'ancienne adresse dans la base. Sauvegardez la base, puis lancez la commande du projet :

php artisan bookstack:update-url http://docs.example.com https://docs.example.com

BookStack se sert à la racine d'un domaine ou d'un sous-domaine, et la documentation décrit aussi une installation sous un sous-dossier, comme example.com/bookstack. Si un proxy inverse s'ajoute devant Apache, déclarez son adresse dans APP_PROXIES : sans elle, le journal d'audit et la limitation de débit voient l'adresse du proxy à la place de celle des visiteurs. La documentation réserve APP_PROXIES="*" au diagnostic.

Où vivent vos données

Gardez la même APP_KEY dans la durée et sauvegardez-la. BookStack s'en sert pour chiffrer notamment les secrets de double authentification : la changer peut casser ces fonctions, et depuis la version 26.09 l'application renvoie une erreur si elle manque.

Les images sont publiques par défaut

Avec le stockage par défaut, le serveur web sert directement les images, ce qui va vite, et toute personne qui connaît leur adresse peut les ouvrir. Pour une documentation interne, le choix se fait dans STORAGE_TYPE :

Pour les fichiers lourds, trois réglages s'accordent : FILE_UPLOAD_SIZE_LIMIT dans .env, post_max_size et upload_max_filesize dans php.ini, et client_max_body_size sous Nginx, qui vaut 1 Mo par défaut.

Deux réglages comptent aussi pour une documentation vivante : chaque page garde 100 révisions par défaut (REVISION_LIMIT), et la corbeille conserve les éléments supprimés 30 jours (RECYCLE_BIN_LIFETIME).

Les e-mails : SMTP et file d'attente

BookStack envoie des e-mails pour la confirmation des adresses, l'oubli de mot de passe, les invitations et les notifications. Depuis un VPS Simafri, l'envoi passe par un relais SMTP authentifié, sur le port 587 : l'adresse d'un compte de messagerie que vous avez déjà, ou Simafri Suite.

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=bookstack@example.com
MAIL_PASSWORD=change-me
MAIL_FROM=bookstack@example.com
MAIL_FROM_NAME=BookStack

Vérifiez le résultat dans « Settings », « Maintenance », avec l'action « Send a Test Email », qui affiche les erreurs rencontrées. Un échec lors d'une invitation s'affiche à l'écran, alors qu'un échec de notification reste dans le journal de l'application.

Envoyer en arrière-plan

Par défaut, BookStack envoie e-mails et webhooks pendant la requête, ce qui peut ralentir les pages. Pour passer en arrière-plan, écrivez QUEUE_CONNECTION=database dans .env et faites tourner un service, avec l'exemple que la documentation donne pour une installation Ubuntu par script :

[Unit]
Description=BookStack Queue Worker

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable bookstack-queue.service
sudo systemctl start bookstack-queue.service

Sécuriser votre instance BookStack

La documentation de sécurité donne une liste à reprendre dès l'installation :

1. Changez l'adresse et le mot de passe du premier administrateur.
2. Vérifiez que le serveur web sert le seul dossier public, surtout si BookStack vit sous /var/www.
3. Limitez l'utilisateur de la base à la seule base de BookStack.
4. Renseignez APP_URL, pour que les adresses générées par le système ne puissent pas être manipulées.
5. Relisez les réglages d'inscription et d'accès public, puis les rôles.

La double authentification s'impose ensuite par rôle. Inscrivez-vous aussi à la liste de diffusion de sécurité du projet, pour recevoir ses alertes. L'adresse /status sert à une supervision : elle répond 200 quand tout va bien, et un code d'erreur égal ou supérieur à 400 sinon.

PHP compte autant que BookStack. Le projet a publié le 21 octobre 2026 une alerte sur une mise à jour critique de PHP, corrigée en 8.5.12, 8.4.27, 8.3.36 et 8.2.35. Ubuntu publie ces correctifs sous ses propres numéros de paquets, comme 8.3.6-0ubuntu0.24.04.13 pour Ubuntu 24.04.

Pour vos contenus, gardez le filtrage activé par défaut, et réservez son assouplissement aux instances où seules des personnes de confiance écrivent. Si un compte administrateur se perd, php artisan bookstack:create-admin en crée un autre, et php artisan bookstack:reset-mfa retire la double authentification d'un utilisateur.

Sauvegardes et mises à jour

Une sauvegarde complète réunit la base et les quatre emplacements de fichiers propres à votre instance. Les exports de contenu servent à autre chose : la documentation précise qu'ils ne remplacent pas une sauvegarde.

sudo mysqldump -u root bookstack > bookstack.backup.sql
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads themes

La première ligne vise une installation par script, où le root de MySQL se connecte par sudo ; ailleurs, écrivez mysqldump -u bookstack -p bookstack. Rangez ces deux fichiers à part, sur une autre machine de préférence. L'archive contient .env, donc APP_KEY et vos mots de passe : traitez-la comme un secret.

Restaurer

Sur une machine neuve, installez BookStack sans lancer php artisan migrate, une étape à commenter dans le script si vous l'utilisez, puis restaurez la base et les fichiers, en gardant l'APP_KEY d'origine :

sudo mysql -u root bookstack < bookstack.backup.sql
tar -xvzf bookstack-files-backup.tar.gz

Si la version installée est plus récente que la sauvegarde, lancez ensuite php artisan migrate. Remettez les droits d'écriture du serveur web sur les dossiers restaurés. Si l'adresse a changé, corrigez APP_URL et lancez bookstack:update-url.

Mettre à jour

Sauvegardez la base et les fichiers avant chaque mise à jour, puis, depuis le dossier de BookStack :

git pull origin release
composer install --no-dev
php artisan migrate
php artisan cache:clear
php artisan config:clear
php artisan view:clear

Le script pour Ubuntu 26.04 installe BookStack sans Composer. La page des mises à jour propose alors, en bêta, ./bookstack-system-cli download-vendor à la place de composer install --no-dev. Ce même outil sait sauvegarder et restaurer, mais le projet ne le considère pas encore prêt pour la production : testez-le avant de vous y fier.

La documentation tient une liste de consignes propres à chaque version, à lire pour la version visée. Quelques exemples :

• Version 26.09 : APP_KEY devient obligatoire.
• Version 26.05 : le dossier storage/fonts doit rester accessible en écriture au serveur web, sans quoi les exports PDF peuvent échouer.
• Version 26.03 : essayez l'envoi d'e-mails après la mise à jour.
• Version 25.11 : de gros changements de base, dont la migration peut prendre plusieurs minutes sur une grande instance.

Les failles se corrigent dans des versions de maintenance, comme la 26.09.3 du 11 novembre 2026 : les images et les dessins d'une page en brouillon ou à la corbeille restaient accessibles et modifiables, et le brouillon personnel d'un éditeur pouvait apparaître à d'autres personnes.

Qui fait quoi sur un VPS infogéré

L'auto-hébergement demande de tenir le serveur en plus de l'application. Sur un VPS infogéré, nos équipes prennent le serveur en main et suivent votre instance de manière proactive ; BookStack reste votre logiciel, avec ses réglages et ses données.

Si vous préférez que nos équipes interviennent dans l'application elle-même, cette prestation se facture à l'heure ou au forfait, avec un chiffrage communiqué avant l'intervention.