Déployer BookStack sur Coolify avec MySQL : tutoriel complet 2026

📍 Article principal de la série : BookStack 2026 : guide pratique.

Trente minutes pour transformer un VPS vide en BookStack production. Méthode validée chez plusieurs PME francophones d’Afrique de l’Ouest et du Maghreb.

Prérequis

• Hetzner CX22 minimum (4 Go RAM).
• Coolify v4.
• Domaine : docs.votre-entreprise.com.
• SMTP (Brevo, Resend).
• Niveau attendu : intermédiaire.
• Temps estimé : 30-45 minutes.

BookStack est une wiki open-source maintenue par BookStackApp depuis 2017, écrite en PHP/Laravel. Pour le déployer sur Coolify, vous avez besoin d’un VPS Hetzner CX22 minimum (2 vCPU, 4 Go RAM) avec Coolify déjà installé. Un domaine avec DNS A. Comptez 30-45 minutes d’installation initiale, puis 1-2 heures de personnalisation (logo, structure des Shelves) avant la mise en production. La version stable au moment de cet article est BookStack 24.10 (publiée fin 2024).

Étape 1 — DNS et préparation

dig +short docs.votre-entreprise.com  # IP VPS

Configurez le DNS A pour wiki.example.sn pointant vers l’IP du VPS Hetzner. Vérifiez la propagation avec dig wiki.example.sn +short. Pour BookStack, prévoyez aussi un sous-domaine cdn.example.sn pour les assets statiques si vous utilisez Cloudflare devant (optionnel mais recommandé pour la performance ouest-africaine). La latence Hetzner Falkenstein vers Dakar tourne autour de 60-80 ms, suffisamment rapide pour la plupart des cas.

Étape 2 — Service BookStack dans Coolify

Resources → + New → Service → rechercher « BookStack ». Coolify déploie le template officiel avec MySQL 8.

Dans Coolify, cliquez Add new resource puis Service puis cherchez BookStack. Le template officiel inclut linuxserver/bookstack et MySQL 8.4 (BookStack ne supporte pas Postgres en 2026). Coolify précompose le compose YAML avec les volumes persistants pour les uploads et les configurations. Assignez le service à un projet (Documentation, Internal Tools selon votre taxonomie Coolify).

Étape 3 — Variables d’environnement

APP_URL=https://docs.votre-entreprise.com
APP_KEY=base64:générer
APP_DEBUG=false

DB_CONNECTION=mysql
DB_HOST=bookstack-db
DB_PORT=3306
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=mot-de-passe-fort

STORAGE_TYPE=local

MAIL_DRIVER=smtp
MAIL_HOST=smtp-relay.brevo.com
MAIL_PORT=587
MAIL_USERNAME=login
MAIL_PASSWORD=key
MAIL_ENCRYPTION=tls
MAIL_FROM=docs@votre-entreprise.com

Variables critiques BookStack : APP_URL avec l’URL HTTPS complète. APP_KEY générée via php artisan key:generate --show ou openssl rand -base64 32. DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD pré-remplis par Coolify. MAIL_DRIVER avec smtp ou ses-mail. MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD pour les invitations email. Sans email valide, vous ne pouvez pas inviter de nouveaux utilisateurs ni recevoir les notifications.

Étape 4 — Domaine HTTPS

Onglet Domains : https://docs.votre-entreprise.com. Force HTTPS.

Dans Coolify, onglet Domains. Ajoutez wiki.example.sn et cochez Force HTTPS Redirect. Coolify utilise Traefik pour générer le certificat Let’s Encrypt automatiquement. Vérifiez après 1-2 minutes que https://wiki.example.sn répond. Si erreur ACME (Let’s Encrypt rate limit en cas de redéploiements multiples), patientez 1 heure avant de réessayer ou utilisez le mode staging Let’s Encrypt pour tester.

Étape 5 — Lancer Deploy

Coolify pull lscr.io/linuxserver/bookstack + mariadb. Comptez 2-3 minutes.

Cliquez Deploy. BookStack démarre en 2-4 minutes : MySQL s’initialise, BookStack applique ses migrations Laravel, l’app démarre sur le port 80 interne. Suivez avec l’onglet Logs Coolify. Les premiers logs montrent les migrations Laravel qui créent les tables. Si erreur ‘Specified key was too long’ sur MySQL, c’est un problème de charset — vérifiez que MySQL tourne en utf8mb4 (cas par défaut sur MySQL 8.x).

Étape 6 — Premier login

Ouvrir https://docs.votre-entreprise.com. Login par défaut : admin@admin.com / password. Changer immédiatement password fort 14+ caractères.

Ouvrez https://wiki.example.sn dans le navigateur. Identifiant initial : admin@admin.com, mot de passe : password. Connectez-vous IMMÉDIATEMENT et changez le mot de passe via Settings → Users → admin → Edit. Modifiez aussi l’email vers une adresse fonctionnelle qui recevra les notifications admin. Sans ces deux changements, votre wiki est trivialement compromettable par n’importe qui qui connaît le pattern par défaut.

Étape 7 — Settings de base

Settings → Customization :

• App name : Votre Entreprise Docs.
• App language : Français.
• Logo : upload.
• Homepage : Default ou page custom.

Dans Settings → Customization, configurez le nom de l’organisation, le logo, les couleurs de marque. Settings → Registration → désactivez l’inscription publique (Allow Registration: off) si votre wiki est interne. Settings → Authentication choisissez la méthode (local, LDAP, SAML, OIDC). Pour une équipe à Plateau qui partage déjà Authentik pour Outline ou Mattermost, configurez OIDC vers la même instance Authentik pour unifier les identités.

Étape 8 — Premier Shelf, Book, Page

Sidebar → Shelves → Create new shelf : « Engineering ».

Dans Engineering → Add new book → « Déploiement Production ».

Dans book → Add Chapter → « VPS Hetzner ».

Dans chapter → Create Page → contenu Markdown ou WYSIWYG.

BookStack organise le contenu en trois niveaux. Shelves (étagères) regroupent des livres par thème (Onboarding, Process, Documentation produit). Books contiennent des chapters et des pages. Cette hiérarchie résiste mieux que les arborescences libres pour 100+ pages. Créez votre premier Shelf depuis le menu, puis un Book à l’intérieur, puis une Page de bienvenue. Cette structure devient le squelette de votre base de connaissances.

Étape 9 — Inviter membres

Settings → Users → Add user. Rôles : Admin, Editor, Viewer. Email magic link envoyé.

Settings → Users → Invite User. Saisissez l’email et le rôle (Admin, Editor, Viewer). BookStack envoie un email avec un lien pour définir le mot de passe. Pour des équipes plus larges, configurez les rôles personnalisés via Settings → Roles avec permissions granulaires (créer Shelf, supprimer Page, éditer mais pas publier). Pour une équipe distribuée entre Cocody et Saint-Louis, restreignez l’admin aux 1-2 personnes responsables de l’infrastructure pour éviter les changements de configuration accidentels.

Étape 10 — Sauvegardes

# Cron quotidien
docker exec bookstack-db mysqldump -u root -p$MYSQL_ROOT_PASSWORD bookstack | gzip > /tmp/bs-mysql.gz
restic backup /tmp/bs-mysql.gz /var/lib/coolify/services/bookstack-prod
rm /tmp/bs-mysql.gz

BookStack stocke ses données dans deux endroits. MySQL pour les contenus (textes des pages, structure, utilisateurs, permissions). Volume disque pour les fichiers uploadés (images, attachments). Sauvegardez les deux quotidiennement. Pour MySQL : mysqldump dans un cron container. Pour les uploads : restic ou borg vers Backblaze B2. Stockez hors VPS principal. Testez la restauration trimestriellement sur un VPS de staging — sinon vous découvrez en panne réelle que les backups étaient corrompus.

Erreurs fréquentes

Erreur	Cause	Solution
500 error initial	APP_KEY non généré	Coolify env var APP_KEY base64
Email magic link non reçu	SMTP pas testé	Settings → Email Test
Upload images échoue	PHP limit	Edit php.ini upload_max
Recherche vide	Index pas généré	php artisan bookstack:regenerate-references
HTTPS Let’s Encrypt fail	Port 80 bloqué	UFW allow 80
Performance dégradée	Cache désactivé	Cache config production

Pratique locale vs documentation internationale

Trois précisions. Multilingue interface : BookStack supporte FR + AR + EN, switch par utilisateur. Recherche : MySQL FULLTEXT performant pour <100k pages. Backup MySQL : daily mysqldump + restic vers B2 = 1,20 USD/mois.

BookStack est en anglais par défaut mais offre une traduction française complète et de bonne qualité (activez via Settings → Languages → French). Pour une équipe francophone à Bamako ou Ouagadougou, activez aussi la locale fr-FR pour les formats de date. Évitez de mélanger les langues dans le contenu — une équipe qui rédige moitié français moitié anglais finit par avoir un wiki incohérent que personne ne consulte. Choisissez une langue dominante et tenez-vous-y.

Tutoriels frères

• Organiser shelves et books
• SSO Authentik

BookStack se complète bien avec d’autres outils self-hostés cohérents. Authentik pour le SSO unifié. Outline si vous voulez plus de flexibilité éditoriale (markdown live + collaboration temps réel). Mattermost pour la messagerie d’équipe qui complète la knowledge base statique. MinIO pour stocker les uploads sur S3-compatible. Cette stack collaborative coûte 30-60 USD/mois en VPS contre 200-500 USD/mois pour les SaaS équivalents.

FAQ

Capacité 100 users ? CX22 confortable. CX42 pour 500.

Mises à jour ? Coolify Pull image + Redeploy. Migrations DB auto.

Multi-domaine ? Une instance = un domaine. Plusieurs instances pour multi-tenancy.

Postgres ? Pas supporté nativement. MySQL/MariaDB uniquement.

Performance 50k pages ? MariaDB 10.6+ pour FULLTEXT moderne.

Q : BookStack supporte-t-il Postgres ? R : Non, MySQL/MariaDB uniquement en 2026. Q : Markdown ou WYSIWYG ? R : Les deux, configurable par utilisateur dans le profil. Q : Multi-tenancy ? R : Pas nativement, déployez plusieurs instances pour isoler les organisations. Q : Recherche full-text ? R : Oui, basée sur MySQL FULLTEXT par défaut, ou Elasticsearch via plugin pour les très gros wikis (1000+ pages).

Dans la continuité

• 🔝 Retour au guide général : guide pratique BookStack 2026
• Documentation : bookstackapp.com/docs/admin

Une fois BookStack opérationnel, étendez progressivement la couverture documentaire : commencez par les process critiques (onboarding, sécurité, déploiement), puis les guides produits, enfin les retours d’expérience post-incident. Programmez une revue trimestrielle des pages les plus consultées pour les rafraîchir. Cette discipline transforme le wiki d’un cimetière de notes obsolètes en actif vivant qui réduit les questions répétitives en interne.

Pourquoi BookStack derriere Coolify avec MySQL externe

BookStack est une plateforme de wiki self-hosted en PHP/Laravel qui stocke ses pages dans MySQL. Le coupler a Coolify (PaaS open source qui orchestre Docker) permet d’obtenir un wiki d’equipe deployable en moins d’une heure sur un VPS Hetzner CX22 a Helsinki ou un Scaleway DEV1-S a Paris (≈ 4 EUR/mois soit 2 624 FCFA). L’interet d’externaliser MySQL plutot que d’utiliser SQLite : sauvegardes incrementales avec mysqldump + restic, montee en charge si l’equipe depasse 30 redacteurs, et compatibilite avec les outils BI (Metabase) pour suivre les contributions.

Sortie attendue de cette procedure : un wiki BookStack accessible sur https://wiki.votredomaine.com avec TLS Let’s Encrypt automatique, base MySQL 8.4 isolee dans un reseau Docker prive, et sauvegardes nocturnes vers un bucket S3 Scaleway Glacier.

Etape 1 : Provisionner le VPS et installer Coolify

Connectez-vous en SSH au VPS frais (Ubuntu 24.04 LTS recommande). Coolify exige 2 vCPU, 2 Go RAM et 30 Go disque pour heberger confortablement BookStack + MySQL + reverse proxy Traefik. La commande officielle d’installation v4 :

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Le script installe Docker Engine 27, configure les volumes /data/coolify et expose le panneau sur le port 8000. Apres 3 a 5 minutes, vous voyez le message « Coolify is ready » et l’URL de premiere connexion. Creez immediatement votre compte admin sur http://IP_VPS:8000/register avant qu’un attaquant ne le fasse a votre place.

Etape 2 : Creer le service MySQL 8.4 isole

Dans Coolify, cliquez sur « Resources » puis « + New » et choisissez « Database > MySQL 8 ». Donnez-lui le nom « mysql-bookstack », generez un mot de passe root fort (32 caracteres) avec openssl rand -base64 32, et laissez Coolify generer un reseau Docker dedie. Ne cochez PAS « Public » : la base ne doit etre joignable que par le conteneur BookStack via le reseau interne.

Une fois deployee (≈ 2 minutes), connectez-vous au shell MySQL depuis le terminal Coolify et creez la base + l’utilisateur applicatif :

CREATE DATABASE bookstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack'@'%' IDENTIFIED BY 'MOT_DE_PASSE_FORT';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'%';
FLUSH PRIVILEGES;

Sortie attendue : « Query OK, 0 rows affected » pour chaque ligne. Notez la chaine de connexion interne fournie par Coolify, du type mysql-bookstack:3306.

Etape 3 : Deployer BookStack via Docker Compose dans Coolify

Dans « Resources > + New > Docker Compose », collez la stack suivante (image officielle linuxserver/bookstack version 24.10) :

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:24.10
    environment:
      - APP_URL=https://wiki.votredomaine.com
      - DB_HOST=mysql-bookstack
      - DB_PORT=3306
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack
      - DB_PASSWORD=MOT_DE_PASSE_FORT
      - APP_KEY=base64:GENEREZ_AVEC_php_artisan_key_generate
    volumes:
      - bookstack_data:/config
    networks:
      - mysql-bookstack_default
volumes:
  bookstack_data:
networks:
  mysql-bookstack_default:
    external: true

Genrez la cle APP_KEY avec docker run --rm lscr.io/linuxserver/bookstack:24.10 php /app/www/artisan key:generate --show. Sans cette cle, BookStack refuse de demarrer et les sessions utilisateurs sont compromises.

Etape 4 : Configurer le domaine et TLS Let’s Encrypt

Dans l’onglet « Domains » du service BookStack, ajoutez wiki.votredomaine.com. Coolify configure automatiquement Traefik pour servir le certificat Let’s Encrypt via le challenge HTTP-01. Cote DNS (Cloudflare, OVH, Gandi), creez un enregistrement A pointant vers l’IP publique du VPS, mode « DNS only » (nuage gris sur Cloudflare) le temps du premier certificat, puis vous pouvez activer le proxy.

Verifiez la propagation DNS depuis Dakar ou Abidjan avec dig wiki.votredomaine.com +short. Sortie de référence : l’IP du VPS, sans CNAME intermediaire. Cliquez ensuite « Deploy » : le certificat est emis en 30 secondes.

Etape 5 : Premiere connexion et durcissement

Ouvrez https://wiki.votredomaine.com et connectez-vous avec admin@admin.com / password (identifiants par defaut linuxserver). Changez immediatement ces identifiants dans Settings > Users, puis activez l’authentification a deux facteurs TOTP. Desactivez l’inscription publique dans Settings > Registration si le wiki est interne.

Configurez le SMTP (Brevo offre 300 emails/jour gratuits, parfait pour les notifications) en editant les variables MAIL_HOST, MAIL_PORT=587, MAIL_USERNAME et MAIL_PASSWORD dans la stack Coolify, puis redeployez.

Etape 6 : Sauvegardes nocturnes vers S3

Dans Coolify, ouvrez le service MySQL et activez « Scheduled Backups » : frequence quotidienne 03:00 UTC, retention 14 jours, destination S3-compatible. Renseignez l’endpoint Scaleway s3.fr-par.scw.cloud, le bucket « backups-bookstack », et les cles d’API. Coolify execute mysqldump –single-transaction puis upload le .sql.gz chiffre.

Testez la restauration sur un VPS de staging avant de considerer la sauvegarde fiable. Une sauvegarde non testee n’est pas une sauvegarde.

Etape 7 : Maintenance et mises a jour

BookStack publie une nouvelle version mineure tous les 1 a 2 mois. Pour mettre a jour, modifiez le tag de l’image (24.10 vers 24.12 par exemple) dans la stack Coolify et cliquez « Redeploy ». Les migrations de base sont executees automatiquement au demarrage du conteneur. Surveillez les logs : un echec de migration laisse le wiki en mode maintenance.

Pour étoffer le tableau, consultez nos guides Coolify vs Dokku et sauvegardes MySQL avec restic.

Etape 8 : Optimisation MySQL pour un wiki actif

Par defaut, MySQL 8.4 dans Docker alloue 128 Mo a innodb_buffer_pool_size, insuffisant des que le wiki contient plus de 500 pages avec recherche full-text. Editez les variables d’environnement du service MySQL dans Coolify et ajoutez MYSQL_INNODB_BUFFER_POOL_SIZE=512M ainsi que MYSQL_MAX_CONNECTIONS=80. Sur un VPS 2 Go RAM, ne depassez pas 768 Mo pour laisser de la marge a BookStack et au systeme.

Verifiez la configuration appliquee avec SHOW VARIABLES LIKE 'innodb_buffer_pool_size';. Sortie de référence : 536870912 (512 Mo en octets). Une valeur a 134217728 indique que la variable n’a pas ete prise en compte, redeployez le service.

Etape 9 : Recherche full-text et indexation

BookStack utilise les indexes FULLTEXT de MySQL pour la barre de recherche. Apres un import massif de pages (migration depuis Confluence ou Notion), reconstruisez les index avec la commande artisan integree :

docker exec -it bookstack php /app/www/artisan bookstack:regenerate-search

Sortie attendue : « Search index regenerated. X pages processed. » sur quelques secondes a quelques minutes selon le volume. Si la commande renvoie « Class not found », verifiez que vous etes bien dans le conteneur applicatif et non dans le conteneur MySQL.

Etape 10 : Latence depuis l’Afrique de l’Ouest

Un VPS a Helsinki affiche typiquement 180 a 220 ms de latence depuis Dakar et 200 a 240 ms depuis Abidjan, acceptable pour un wiki consulte ponctuellement. Pour une equipe entierement basee a Cotonou ou Lome qui consulte intensivement la documentation, preferez un VPS Scaleway DEV1-S a Paris (90 a 110 ms) ou un Hetzner CCX a Falkenstein avec Cloudflare en cache devant. Activez le cache HTML de BookStack via le plugin officiel pour reduire les requetes MySQL de 60 a 70 pour cent sur les pages publiques.

Etape 8 : Optimisation MySQL pour un wiki actif

Par defaut, MySQL 8.4 dans Docker alloue 128 Mo a innodb_buffer_pool_size, insuffisant des que le wiki contient plus de 500 pages avec recherche full-text. Editez les variables d’environnement du service MySQL dans Coolify et ajoutez MYSQL_INNODB_BUFFER_POOL_SIZE=512M et MYSQL_MAX_CONNECTIONS=80. Sur un VPS 2 Go RAM, ne depassez pas 768 Mo pour laisser de la marge a BookStack et au systeme.

Verifiez avec SHOW VARIABLES LIKE 'innodb_buffer_pool_size';. Résultat type : 536870912 (512 Mo en octets). Une valeur a 134217728 indique que la variable n’a pas ete prise en compte, redeployez le service.

Etape 9 : Recherche full-text et indexation

BookStack utilise les indexes FULLTEXT MySQL pour la barre de recherche. Apres un import massif de pages (migration depuis Confluence ou Notion), reconstruisez les index avec la commande artisan integree :

docker exec -it bookstack php /app/www/artisan bookstack:regenerate-search

Sortie de référence : « Search index regenerated. X pages processed. » en quelques secondes a quelques minutes selon le volume. Si la commande renvoie « Class not found », verifiez que vous etes dans le conteneur applicatif et non MySQL.

Etape 10 : Latence depuis l’Afrique de l’Ouest

Un VPS a Helsinki affiche typiquement 180 a 220 ms de latence depuis Dakar et 200 a 240 ms depuis Abidjan, acceptable pour un wiki consulte ponctuellement. Pour une equipe basee a Cotonou ou Lome qui consulte intensivement la documentation, preferez un VPS Scaleway DEV1-S a Paris (90 a 110 ms) ou un Hetzner CCX a Falkenstein avec Cloudflare en cache devant. Activez le cache HTML de BookStack via le plugin officiel pour reduire les requetes MySQL de 60 a 70 pour cent sur les pages publiques.

Etape 11 : Monitoring et alertes

Coolify expose des metriques Prometheus sur le port interne 9100. Branchez-y un Grafana Cloud (free tier 10 000 series) pour suivre la RAM, le CPU et le nombre de connexions MySQL. Configurez une alerte si innodb_buffer_pool_pages_free passe sous 5 pour cent : c’est le signe qu’il faut augmenter le buffer pool ou migrer vers un VPS plus large.

Etape 12 : Migration depuis un wiki existant

Si vous remplacez un wiki Confluence ou DokuWiki, BookStack offre un import via l’API REST documentee. Generez un token API dans Settings > Users > votre profil > API Tokens, puis utilisez le script Python officiel bookstack-importer disponible sur GitHub. Pour Confluence Cloud, exportez d’abord en HTML via Space Settings > Content Tools > Export, puis pointez l’importer sur le dossier extrait. Comptez environ 30 minutes pour 200 pages, principalement contraint par les uploads d’images.

Verifiez apres migration que les liens internes pointent vers les nouveaux slugs BookStack et non vers d’anciens identifiants Confluence. Une recherche regex grep -r "atlassian.net" /data/coolify dans les pages exportees liste les liens a reecrire avant import.

Etape 13 : Cle API et integrations CI

L’API BookStack permet de publier automatiquement des changelogs depuis GitHub Actions. Exemple de workflow qui cree une page apres chaque release :

- name: Publier la release dans BookStack
  run: |
    curl -X POST https://wiki.votredomaine.com/api/pages \
      -H "Authorization: Token ${{ secrets.BS_TOKEN_ID }}:${{ secrets.BS_TOKEN_SECRET }}" \
      -H "Content-Type: application/json" \
      -d '{"book_id":3,"name":"Release ${{ github.ref_name }}","markdown":"${{ github.event.release.body }}"}'

Vous devriez obtenir : un JSON contenant l’id de la page creee et son URL publique. Une erreur 401 signale un token invalide, 403 un token sans permission « create-pages » sur le book cible.