Héberger BookStack : votre wiki et base de connaissances d'équipe

Une documentation interne dispersée entre des fichiers, des courriels et des conversations fait perdre du temps. Les procédures deviennent difficiles à retrouver, plusieurs versions circulent et les nouveaux membres de l’équipe dépendent constamment de leurs collègues pour obtenir une information.

BookStack répond à ce problème avec une plateforme open source conçue pour créer un wiki structuré et simple à utiliser. Son organisation visuelle convient aux équipes, PME et associations qui recherchent une alternative auto-hébergée à Confluence ou Notion pour leur documentation interne. Les données restent sur votre serveur et sous votre contrôle.

L’auto-hébergement permet aussi de choisir précisément la localisation et la sécurité de l’infrastructure. TalCloud propose notamment une offre VPS à partir de 4,99 € par mois, avec des serveurs situés en France, du stockage NVMe, une protection Anti-DDoS Netrix, une approche adaptée au RGPD et un support humain.

Comment BookStack organise votre documentation

BookStack repose sur une hiérarchie facile à comprendre :

• Les Étagères regroupent plusieurs livres autour d’un service, d’un métier ou d’un projet.
• Les Livres contiennent une documentation cohérente, comme un manuel d’exploitation ou un guide d’intégration.
• Les Chapitres organisent les grandes parties d’un livre.
• Les Pages accueillent le contenu proprement dit.

Une étagère « Informatique » peut, par exemple, contenir les livres « Procédures utilisateurs », « Administration système » et « Sécurité ». Le livre consacré à l’administration peut ensuite être divisé en chapitres sur les serveurs, le réseau et les sauvegardes.

Les contributeurs disposent d’un éditeur WYSIWYG pour mettre en forme une page sans connaître de syntaxe particulière. Un éditeur markdown est également disponible pour les utilisateurs qui préfèrent travailler avec du texte balisé. Les images, tableaux, liens internes et pièces jointes facilitent la rédaction de procédures complètes.

Le moteur de recherche retrouve rapidement une page ou une expression dans l’ensemble de la documentation autorisée. Chaque modification crée aussi une version de la page. L’historique permet de comparer les changements, d’identifier un contributeur et de restaurer un contenu précédent après une erreur.

Prérequis pour héberger BookStack

Le déploiement présenté ici nécessite :

• Un VPS Linux avec au moins 2 Go de mémoire vive pour une petite équipe.
• Docker Engine et le module Docker Compose (voir installer Docker sur un VPS).
• Un nom de domaine ou un sous-domaine, par exemple docs.example.fr.
• Un enregistrement DNS pointant vers l’adresse IP du VPS.
• Les ports 80 et 443 accessibles pour le reverse proxy.
• Une base MariaDB, déployée ici dans un conteneur séparé.

BookStack ne sera pas directement exposé sur Internet. Son port HTTP sera uniquement publié sur l’adresse locale 127.0.0.1, puis un reverse proxy prendra en charge le domaine et le certificat HTTPS.

Déployer BookStack avec Docker Compose

Créez un répertoire de travail et placez-y un fichier .env. Générez d’abord la clé d’application avec l’outil fourni par l’image LinuxServer :

docker run --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

La commande renvoie une valeur commençant par base64:. Copiez toute la valeur dans .env. Cette clé sert au chiffrement des données applicatives. Elle doit être unique, conservée secrètement et sauvegardée. Ne la remplacez pas après la mise en production sans procédure de migration adaptée.

APP_KEY=base64:REMPLACEZ_PAR_LA_CLE_GENEREE
DB_PASSWORD=REMPLACEZ_PAR_UN_MOT_DE_PASSE_LONG
DB_ROOT_PASSWORD=REMPLACEZ_PAR_UN_AUTRE_MOT_DE_PASSE_LONG

Créez ensuite compose.yaml :

services:
  bookstack_db:
    image: mariadb:11.4
    container_name: bookstack_db
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: bookstack
      MARIADB_USER: bookstack
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - bookstack_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10

  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    restart: unless-stopped
    depends_on:
      bookstack_db:
        condition: service_healthy
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Europe/Paris
      APP_URL: https://docs.example.fr
      APP_KEY: ${APP_KEY}
      DB_HOST: bookstack_db
      DB_PORT: 3306
      DB_DATABASE: bookstack
      DB_USERNAME: bookstack
      DB_PASSWORD: ${DB_PASSWORD}
    ports:
      - "127.0.0.1:6875:80"
    volumes:
      - bookstack_config:/config

volumes:
  bookstack_config:
    name: bookstack_config
  bookstack_db:
    name: bookstack_db

Remplacez docs.example.fr par votre domaine public. Démarrez ensuite les services :

docker compose up -d
docker compose ps
docker compose logs --tail=100 bookstack

Le volume bookstack_db conserve les données MariaDB. Le volume bookstack_config contient la configuration BookStack ainsi que les fichiers téléversés, notamment les images. Les conteneurs peuvent donc être recréés sans supprimer le contenu persistant.

Premier accès et sécurisation du compte administrateur

Une fois le reverse proxy configuré, ouvrez l’adresse publique de BookStack. Le compte initial utilise généralement les identifiants suivants :

Adresse e-mail: admin@admin.com
Mot de passe: password

Changez immédiatement l’adresse électronique et le mot de passe depuis le profil administrateur. Un mot de passe long et unique est indispensable. Créez ensuite un compte nominatif pour chaque personne au lieu de partager le compte administrateur.

Vérifiez également le nom de l’instance, la langue, les paramètres d’inscription et l’envoi des courriels. Désactivez l’inscription publique si seuls les membres autorisés doivent accéder au wiki.

Créer une première base de connaissances

Commencez avec une structure limitée et compréhensible. Créez, par exemple, une étagère « Documentation interne », puis un livre « Accueil des nouveaux membres ». Ajoutez des chapitres consacrés aux outils, aux règles internes et aux procédures courantes.

Chaque page doit répondre à un besoin précis. Préférez des titres recherchables comme « Configurer son accès VPN » ou « Restaurer un fichier supprimé ». L’éditeur WYSIWYG convient aux contributeurs occasionnels, tandis que markdown facilite la rédaction technique et l’insertion de blocs de code.

Ajoutez des liens entre les pages liées et utilisez la recherche avant de créer un nouveau contenu. Cette habitude limite les doublons et maintient une source de vérité claire.

Gérer les utilisateurs, les rôles et les permissions

BookStack permet de créer des rôles adaptés aux responsabilités de l’équipe : administrateurs, rédacteurs, relecteurs ou lecteurs. Chaque rôle peut recevoir des droits de consultation, création, modification et suppression.

Les permissions peuvent être adaptées au contenu, notamment pour une étagère ou un livre. Une documentation RH, juridique ou financière peut ainsi être réservée à certains groupes. Attention toutefois : restreindre une étagère ne remplace pas nécessairement la restriction de chaque livre qu’elle contient. Vérifiez les permissions effectives des livres sensibles avec un compte de test.

Appliquez le principe du moindre privilège. Les lecteurs n’ont pas besoin de modifier les pages, et les rédacteurs n’ont généralement pas besoin d’administrer les utilisateurs ou la configuration globale.

Activer HTTPS avec un reverse proxy

Le reverse proxy reçoit les connexions publiques, gère le certificat TLS et transmet les requêtes vers BookStack. Avec Caddy, une configuration minimale peut ressembler à ceci :

docs.example.fr {
    reverse_proxy 127.0.0.1:6875
}

Le DNS doit pointer vers le VPS et les ports 80 et 443 doivent être disponibles. Caddy peut alors obtenir et renouveler automatiquement le certificat. Nginx Proxy Manager convient également si vous préférez une interface graphique.

La variable APP_URL doit correspondre exactement à l’URL publique, protocole compris. Pour https://docs.example.fr, ne configurez pas une adresse HTTP, une IP privée ou un autre sous-domaine. Une incohérence provoque souvent des redirections incorrectes, des images absentes ou des problèmes de connexion.

Sécurité, mises à jour et sauvegardes

Limitez l’accès SSH, utilisez des clés, activez un pare-feu et n’exposez jamais directement MariaDB. Le port BookStack étant lié à 127.0.0.1, seul le reverse proxy local peut l’atteindre. La protection Anti-DDoS Netrix de TalCloud apporte une couche supplémentaire au niveau de l’infrastructure.

Avant une mise à jour, consultez les changements de version et réalisez une sauvegarde. Téléchargez ensuite les images récentes et recréez les conteneurs :

docker compose pull
docker compose up -d
docker compose logs --tail=100 bookstack

Sauvegardez MariaDB avec mariadb-dump :

mkdir -p backups
docker compose exec -T bookstack_db sh -c 'mariadb-dump -u root -p"$MARIADB_ROOT_PASSWORD" --single-transaction "$MARIADB_DATABASE"' > "backups/bookstack-$(date +%F).sql"

Sauvegardez aussi le volume de configuration, qui contient les images et fichiers téléversés :

docker run --rm -v bookstack_config:/source:ro -v "$PWD/backups:/backup" alpine tar -czf "/backup/bookstack-config-$(date +%F).tar.gz" -C /source .

Une sauvegarde utile doit être copiée hors du VPS, chiffrée si elle contient des informations sensibles et testée régulièrement par une restauration. Notre guide sur les sauvegardes chiffrées avec restic détaille l’automatisation. Conservez ensemble le dump MariaDB, le volume bookstack_config, le fichier Compose et la valeur APP_KEY. Cette stratégie permet de reconstruire votre wiki après une panne sans perdre la documentation de l’équipe.