Héberger BookStack sur votre propre VPS

Pourquoi self-héberger BookStack sur un VPS

Bénéfices concrets d'un BookStack auto-hébergé

• Structure claire en étagères/livres/chapitres/pages : documentation navigable sans effort.
• Éditeur WYSIWYG et Markdown au choix, avec diagrammes Draw.io intégrés.
• Permissions granulaires par rôle et par livre pour cloisonner les contenus sensibles.
• Recherche full-text rapide sur l'ensemble de la base de connaissances.
• Authentification LDAP, SAML ou OAuth pour s'intégrer à votre annuaire d'entreprise.
• Empreinte légère : un VPS avec 2 Go de RAM suffit pour une documentation d'équipe.
• Aucun abonnement par utilisateur — un nombre sans limite de membres de contributeurs sans surcoût.

Prérequis matériels et logiciels

BookStack vs alternatives self-hosted

Faites défiler le tableau

Déployer BookStack avec Docker Compose et SSL

1. 01

   Préparer le VPS et installer Docker

   Connectez-vous en SSH puis installez Docker et le plugin Compose :

   curl -fsSL https://get.docker.com | sh
   apt install docker-compose-plugin
   mkdir -p /opt/bookstack && cd /opt/bookstack

   Vérifiez : docker compose version doit afficher v2.x ou supérieur. L'image communautaire lscr.io/linuxserver/bookstack est la plus répandue et la mieux maintenue pour un déploiement conteneurisé.

2. 02

   Créer le fichier docker-compose.yml

   Créez /opt/bookstack/docker-compose.yml avec les deux services — MariaDB et BookStack — sur un réseau dédié :

   services:
     mariadb:
       image: mariadb:10.11
       environment:
         MYSQL_ROOT_PASSWORD: changeme_root
         MYSQL_DATABASE: bookstack
         MYSQL_USER: bookstack
         MYSQL_PASSWORD: changeme_bk
       volumes:
         - ./data/mariadb:/var/lib/mysql
       networks: [bookstack]
   
     bookstack:
       image: lscr.io/linuxserver/bookstack:latest
       environment:
         PUID: 1000
         PGID: 1000
         APP_URL: https://wiki.votredomaine.com
         DB_HOST: mariadb
         DB_USER: bookstack
         DB_PASS: changeme_bk
         DB_DATABASE: bookstack
         MAIL_DRIVER: smtp
         MAIL_HOST: smtp.votredomaine.com
         MAIL_PORT: 587
         MAIL_FROM: [email protected]
         MAIL_USERNAME: [email protected]
         MAIL_PASSWORD: votre_mot_de_passe_smtp
       ports:
         - "6875:80"
       volumes:
         - ./data/bookstack:/config
       depends_on: [mariadb]
       networks: [bookstack]
   
   networks:
     bookstack:

   APP_URL doit correspondre exactement à l'URL HTTPS finale. Une valeur incorrecte casse les liens internes et les uploads.

3. 03

   Lancer la stack et vérifier les logs

   docker compose up -d
   docker compose logs -f bookstack

   Au premier démarrage, BookStack exécute automatiquement les migrations Laravel pour créer le schéma de la base. Attendez la ligne Server running on http://0.0.0.0:80 avant de continuer — cela prend 30 à 60 secondes.

4. 04

   Configurer le reverse proxy et SSL

   Avec Caddy (gestion automatique du certificat) :

   wiki.votredomaine.com {
       reverse_proxy localhost:6875
   }

   Redémarrez Caddy : systemctl reload caddy.

   Avec Nginx + Certbot :

   server {
       listen 80;
       server_name wiki.votredomaine.com;
       return 301 https://$host$request_uri;
   }
   server {
       listen 443 ssl;
       server_name wiki.votredomaine.com;
       ssl_certificate /etc/letsencrypt/live/wiki.votredomaine.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/wiki.votredomaine.com/privkey.pem;
       location / {
           proxy_pass http://127.0.0.1:6875;
           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;
       }
   }

   Obtenez le certificat avec certbot --nginx -d wiki.votredomaine.com.

5. 05

   Première connexion et sécurisation du compte admin

   Ouvrez https://wiki.votredomaine.com. Le compte par défaut est [email protected] avec le mot de passe password. Changez-les immédiatement dans Paramètres → Profil.

   Vérifiez ensuite que le SMTP fonctionne : Paramètres → Configuration des e-mails → Envoyer un e-mail de test. Si le test échoue, consultez les logs : docker compose logs bookstack | grep -i mail.

Configuration avancée : SSO, LDAP et SAML

Sauvegarder et restaurer BookStack

#!/bin/bash
BACKUP_DIR=/var/backups/bookstack
mkdir -p $BACKUP_DIR
DATE=$(date +%Y%m%d)
docker exec $(docker ps -qf name=mariadb) \
  mysqldump -u bookstack -pchangeme_bk bookstack \
  > $BACKUP_DIR/bookstack-db-$DATE.sql
tar -czf $BACKUP_DIR/bookstack-uploads-$DATE.tar.gz /opt/bookstack/data/bookstack/uploads
find $BACKUP_DIR -mtime +14 -delete

Dépannage : erreurs courantes

Problèmes fréquents et solutions

• Erreur SMTP « Connection refused » ou timeout : vérifiez que MAIL_PORT correspond au port réel (587 pour STARTTLS, 465 pour SSL). Certains serveurs SMTP bloquent le port 25 sortant. Testez la connectivité depuis le conteneur : docker exec -it bookstack curl -v telnet://smtp.votredomaine.com:587.
• Permissions sur storage/ : erreur 500 ou page blanche : le dossier /opt/bookstack/data/bookstack doit appartenir à l'UID 1000 (variable PUID). Corrigez avec chown -R 1000:1000 /opt/bookstack/data/bookstack puis redémarrez le conteneur.
• Lenteur ou timeout avec MariaDB au démarrage : BookStack attend que MariaDB soit prêt. Si le conteneur BookStack redémarre en boucle les premières secondes, c'est normal. Ajoutez un healthcheck sur le service mariadb dans le Compose ou attendez 30 secondes avant d'inspecter les logs.
• Images qui ne s'affichent pas après déplacement : APP_URL doit correspondre exactement à l'URL HTTPS publique. Si vous changez de domaine, mettez à jour APP_URL dans le Compose, redémarrez le conteneur, puis exécutez php artisan bookstack:update-url depuis le conteneur pour mettre à jour les URLs stockées en base.
• Migrations bloquées au premier démarrage (OOM) : si le VPS dispose de moins de 2 Go de RAM, les migrations Laravel peuvent être tuées par l'OOM killer. Ajoutez un fichier de swap de 2 Go (fallocate -l 2G /swapfile && mkswap /swapfile && swapon /swapfile) ou augmentez la RAM du VPS avant de relancer.

Mettre à jour BookStack

cd /opt/bookstack
docker compose pull
docker compose up -d
docker compose logs -f bookstack

Pour aller plus loin

• Héberger Nextcloud sur VPS — stockage cloud et collaboration documentaire.
• Héberger Gitea sur VPS — forge Git auto-hébergée pour vos équipes de développement.
• Authentik sur VPS — SSO open source pour centraliser l'authentification de BookStack et vos autres apps.