Comment auto-héberger Wiki.js en 2026 : configuration de la base de données, TLS et tests de restauration

La plupart des notes d'installation de Wiki.js s'arrêtent au premier chargement de page. C'est trop tôt : DB_HOST vaut localhost à l'intérieur du conteneur ou les en-têtes du proxy TLS sont absents. Un test de production utile est plus exigeant : terminer la configuration, créer et modifier une page, importer des médias, les rechercher et consulter l'historique des versions après un redémarrage.

Le rôle de Wiki.js est simple : un wiki Markdown avec gestion des versions et un éditeur moderne. Son périmètre opérationnel dépasse le processus web ; la dépendance, l'état persistant et la route publique doivent donc tous être définis explicitement avant l'arrivée des vraies données.

Définir le périmètre d'exécution de Wiki.js

La topologie Wiki.js minimale et responsable comprend un seul listener privé sur le port 3000, une route d'ingress et une limite d'état documentée. Le contrat réseau de Wiki.js repose sur une base de données Postgres, MySQL, MariaDB, MSSQL ou SQLite accessible. Conservez les endpoints privés sur le DNS interne, n'autorisez que les appels sortants nécessaires et attribuez à Wiki.js un identifiant de service aux permissions limitées.

Validez la topologie en demandant à un client vierge de terminer la configuration, de créer et modifier une page, d'importer des médias, de les rechercher et de consulter l'historique des versions après un redémarrage. Surveillez le temps de réponse de la base de données, l'indexation de la recherche, le stockage des médias et la latence du fournisseur d'authentification pendant l'exécution. Le résultat vous indiquera si la prochaine amélioration doit concerner la mémoire, le stockage, le réseau ou un worker distinct, plutôt que de vous pousser à dimensionner arbitrairement le conteneur.

Concevoir la restauration de Wiki.js avant le lancement

Aucun état applicatif inscriptible n'est attendu dans l'image Wiki.js standard. Préservez la base de données ainsi que les imports locaux et les ressources personnalisées, notamment le digest épinglé et la configuration de routage vérifiée, au lieu de sauvegarder un système de fichiers de conteneur vide.

Recréez Wiki.js à partir de zéro sur un autre hôte et vérifiez que les pages, l'historique, les utilisateurs, les groupes, les médias et la navigation sont restaurés, et qu'une page connue reste consultable. Si vous ajoutez une base de données distincte, un serveur de discussion ou une couche d'authentification, attribuez à chaque composant un responsable de reprise explicitement défini. Le guide du dépôt Git à la production explique comment un artefact reproductible remplace une sauvegarde de conteneur.

Enregistrez la commande de reconstruction et le test avec sortie attendue avec la release. Un plan de reprise sans état réussit en reproduisant le comportement à partir d'entrées fiables ; il ne doit pas dépendre de la copie d'un conteneur opaque en cours d'exécution.

Définir la limite de confiance de Wiki.js

Un déploiement Wiki.js sécurisé commence par une réduction des privilèges. Évitez de laisser l'écran de configuration exposé après la création du premier administrateur ; supprimez plutôt l'accès public à la configuration, restreignez l'administration et attribuez à la base de données du wiki ses propres identifiants.

Traitez DB_PASS en fonction de son rôle dans Wiki.js : gardez les valeurs sensibles hors de Git, documentez les effets d'une rotation et ne remplacez jamais un exemple public en production. Restreignez les routes d'administration, utilisez le DNS privé pour les dépendances et examinez chaque bind mount. Lorsque les logs sont envoyés vers un système centralisé, filtrez les secrets et les contenus privés avant leur sortie du serveur.

Ce qui doit être validé avant l'arrivée des vraies données Wiki.js

Une mise en production de Wiki.js doit pouvoir être validée par une personne qui n'a pas construit le déploiement. Donnez-lui la version épinglée, un compte de test non sensible et cette tâche : terminer la configuration, créer et modifier une page, importer des médias, les rechercher et consulter l'historique des versions après un redémarrage. Si les instructions nécessitent un accès shell non documenté, le service n'est pas encore prêt sur le plan opérationnel.

Répétez la validation en ne remplaçant que le conteneur. Restaurez ensuite la base de données ainsi que les imports locaux et les ressources personnalisées dans une infrastructure vierge, puis prouvez que les pages, l'historique, les utilisateurs, les groupes, les médias et la navigation sont restaurés et qu'une page connue reste consultable. Mesurez le temps de réponse de la base de données, l'indexation de la recherche, le stockage des médias et la latence du fournisseur d'authentification lors des deux exécutions réussies ; les différences inattendues révèlent souvent l'absence d'un cache, d'un index, d'un worker ou d'un montage de données.

Ajoutez un exercice de panne : interdisez temporairement à l'identité de test l'accès à une base de données Postgres, MySQL, MariaDB, MSSQL ou SQLite accessible. Wiki.js doit générer une erreur exploitable, préserver l'état existant et récupérer lorsque la condition valide est rétablie. Conservez les horodatages et les lignes de log pertinentes, en masquant les secrets. Ces éléments serviront de référence lors de la prochaine modification de l'image ou de la configuration.

Démarrer Wiki.js sans masquer les éléments importants

Conservez une commande de démarrage initiale de Wiki.js suffisamment reproductible pour être examinée dans une pull request.

docker run -d \
  --name wiki-js \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e DB_PASS=replace-with-a-long-random-value \
  -e DB_TYPE=postgres \
  -e DB_HOST=postgres.internal \
  -e DB_PORT=5432 \
  -e DB_USER=wiki \
  -e DB_NAME=wiki \
  ghcr.io/requarks/wiki:2

Ne vous fiez pas à latest une fois les vraies données présentes. Consignez le digest utilisé, l'utilisateur du conteneur et les permissions des montages. Suivez le log de l'application pendant un test complet — terminer la configuration, créer et modifier une page, importer des médias, les rechercher et consulter l'historique des versions après un redémarrage — et notez les éventuelles migrations avant de placer la route derrière le trafic de production.

Bien distinguer les URL internes et externes

Considérez l'URL externe de Wiki.js comme une configuration qui doit survivre aux redéploiements. Configurez d'abord l'URL du site après avoir fait passer le service par HTTPS ; acheminez ensuite le hostname vers le port 3000 en conservant l'hôte et le schéma d'origine.

La checklist d'accessibilité d'un déploiement peut prouver que les requêtes entrent bien dans le conteneur. Après cette étape, le problème connu — DB_HOST vaut localhost à l'intérieur du conteneur ou les en-têtes du proxy TLS sont absents — doit être recherché dans Wiki.js, son état ou sa charge de travail, et non dans l'automatisation des certificats.

Surveiller la charge de travail, pas seulement le conteneur

Construisez des dashboards autour du temps de réponse de la base de données, de l'indexation de la recherche, du stockage des médias et de la latence du fournisseur d'authentification. Un graphique CPU dépourvu de ce contexte de charge ne peut pas expliquer pourquoi Wiki.js est lent. Ajoutez un contrôle synthétique ou planifié qui tente de terminer la configuration, de créer et modifier une page, d'importer des médias, de les rechercher et de consulter l'historique des versions après un redémarrage, en utilisant des données de test inoffensives.

Avant une mise à niveau, tenez compte de ce risque propre à l'application : les migrations de base de données et les modules d'authentification de Wiki.js doivent être validés en staging avant de passer à une autre branche de release. Restaurez une sauvegarde récente dans un déploiement isolé, exécutez-y les migrations et comparez le comportement. Si DB_HOST vaut localhost à l'intérieur du conteneur ou si les en-têtes du proxy TLS sont absents, examinez la limite concernée — origine publique, stockage ou dépendance — avant de modifier des paramètres sans rapport.

Garder Wiki.js explicite pendant que Dockup gère le routage

Le routage, les certificats, le remplacement des services et le stockage attaché sont de bonnes cibles pour l'automatisation. Dockup s'en charge pour Wiki.js et peut provisionner la base de données managée associée ou se connecter à des services hébergés sur le propre serveur d'un client.

En revanche, il ne doit pas inventer la politique de confiance de Wiki.js. Après le déploiement, configurez l'URL du site après avoir fait passer le service par HTTPS, appliquez cette limite — supprimez l'accès public à la configuration, restreignez l'administration et attribuez à la base de données du wiki ses propres identifiants — puis vérifiez le résultat de ce scénario : terminer la configuration, créer et modifier une page, importer des médias, les rechercher et consulter l'historique des versions après un redémarrage. Vous obtenez ainsi une infrastructure en un clic accompagnée d'un test d'acceptation propre à l'application.

Foire aux questions

De quoi Wiki.js a-t-il besoin pour être déployé en production ?

Acheminez le conteneur Wiki.js sur le port 3000 via une origine HTTPS unique. La dépendance réseau est une base de données Postgres, MySQL, MariaDB, MSSQL ou SQLite accessible. Ne considérez pas Wiki.js comme prêt tant que vous ne pouvez pas terminer la configuration, créer et modifier une page, importer des médias, les rechercher et consulter l'historique des versions après un redémarrage.

Quelles données de Wiki.js doivent figurer dans une sauvegarde ?

L'image Wiki.js standard ne possède aucun montage obligatoire pour les données applicatives. Préservez sa configuration de déploiement et sauvegardez séparément tout état connecté ; la reprise est validée lorsque les pages, l'historique, les utilisateurs, les groupes, les médias et la navigation sont restaurés et qu'une page connue reste consultable.

Wiki.js nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l'origine publique de Wiki.js et conservez le port 3000 sur la route interne. Appliquez correctement le paramètre Wiki.js : configurez l'URL du site après avoir fait passer le service par HTTPS. Pour Wiki.js, HTTPS protège les identifiants ou le contenu utilisateur en transit et garantit un comportement cohérent des clients dépendant de l'origine.

Comment tester une mise à niveau de Wiki.js ?

Restaurez l'état actuel de Wiki.js dans un déploiement isolé, appliquez la version candidate et répétez sa transaction d'acceptation. Soyez particulièrement attentif, car les migrations de base de données et les modules d'authentification de Wiki.js doivent être validés en staging avant de passer à une autre branche de release. Conservez l'image Wiki.js précédente jusqu'à ce que les limites de migration des données et de rollback soient comprises.