Comment auto-héberger HedgeDoc en 2026 : WebSockets, OAuth et fichiers téléversés

Il existe deux façons de « faire fonctionner HedgeDoc » : disposer d’un container, ou faire en sorte que le service remplisse réellement sa fonction. Seule la seconde compte. Ici, la preuve consiste à créer une note, à la modifier simultanément depuis deux navigateurs, à téléverser une image et à s’authentifier via le fournisseur sélectionné.

HedgeDoc est conçu pour cela : des notes Markdown collaboratives en temps réel. Le déploiement doit préserver les éléments qui permettent ce comportement ; un port, un volume et un certificat sont des prérequis, pas le résultat.

Sauvegarder l’état que HedgeDoc ne peut pas recréer

Définissez le point et le délai de reprise de HedgeDoc en tenant compte de la base de données, des fichiers téléversés et de la configuration d’authentification. Montez /hedgedoc/public/uploads avant l’initialisation, écrivez quelques données de test inoffensives et remplacez le container pour vérifier que ce chemin est réellement persistant. Un volume nommé garantit la persistance lors d’un redeploy ; il ne protège ni contre une compromission ni contre la perte du serveur.

Construisez un environnement de restauration propre, utilisez la même version d’application verrouillée et vérifiez que les notes, les révisions, les utilisateurs et les fichiers téléversés sont restaurés, puis que deux navigateurs peuvent collaborer sur la note restaurée. Consignez les commandes, les corrections de propriété et le temps écoulé. Le guide des sauvegardes constitue une bonne référence : une sauvegarde est fiable après sa restauration, pas après son téléversement.

Séparer HedgeDoc de ses dépendances

La santé du processus et celle du produit sont deux choses différentes pour HedgeDoc. Le port 3000 peut répondre alors que la transaction côté utilisateur échoue toujours. Le contrat réseau de HedgeDoc repose sur Postgres, ainsi que, facultativement, sur des fournisseurs OAuth et SMTP. Conservez les endpoints privés sur un DNS interne, n’autorisez que les appels sortants nécessaires et attribuez à HedgeDoc des identifiants de service aux permissions limitées.

Utilisez cet exercice de readiness après toute modification importante de configuration : créez une note, modifiez-la simultanément depuis deux navigateurs, téléversez une image et authentifiez-vous via le fournisseur sélectionné. Évitez d’inclure des vérifications externes coûteuses dans les probes de liveness afin qu’une panne de fournisseur ne provoque pas une boucle de redémarrage. Le dimensionnement doit suivre les connexions WebSocket, les écritures en base de données, les médias téléversés et l’historique des documents, ce qui reflète mieux la pression réelle exercée sur HedgeDoc que les requêtes de pages.

Cinq vérifications plus fiables que la santé du container

Transformez le smoke test de HedgeDoc en commande de release réutilisable ou en runbook court. Sa sortie doit démontrer le résultat suivant : créer une note, la modifier simultanément depuis deux navigateurs, téléverser une image et s’authentifier via le fournisseur sélectionné. Associez au résultat la version de l’application, le digest du container, le hostname de la route et l’identifiant des données de test.

Exécutez la même vérification après un remplacement courant du container et après la restauration de la base de données, des fichiers téléversés et de la configuration d’authentification dans un autre environnement. La restauration est réussie lorsque les notes, les révisions, les utilisateurs et les fichiers téléversés sont rétablis et que deux navigateurs peuvent collaborer sur la note restaurée. Comparez les temps et la consommation associés aux connexions WebSocket, aux écritures en base de données, aux médias téléversés et à l’historique des documents ; une variation importante mérite d’être examinée, même si la dernière action réussit encore.

Testez ensuite une panne sans danger : refusez temporairement à l’identité de test l’accès à Postgres ainsi qu’aux fournisseurs OAuth et SMTP. Vérifiez que HedgeDoc signale l’erreur et revient à la normale sans modifications manuelles destructrices. Ne conservez que l’extrait de log nécessaire, après l’avoir expurgé. Cette validation en quatre parties couvre le démarrage, la persistance, la récupération et la gestion des pannes.

Démarrer HedgeDoc sans masquer les éléments importants

Une commande minimale est utile lorsqu’elle révèle ce que la plateforme prendra ensuite en charge.

docker run -d \
  --name hedgedoc \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v hedgedoc-data:/hedgedoc/public/uploads \
  -e CMD_SESSION_SECRET=replace-with-a-long-random-value \
  -e CMD_DOMAIN=app.example.com \
  -e CMD_PROTOCOL_USESSL=true \
  -e CMD_DB_URL=postgres://hedgedoc:replace-password@postgres.internal:5432/hedgedoc \
  quay.io/hedgedoc/hedgedoc:latest

Ici, le port 3000 reste privé sur l’hôte et chaque chemin requis est explicite. Ajoutez les paramètres de connexion validés pour Postgres ainsi que pour les fournisseurs OAuth et SMTP facultatifs ; utilisez des noms privés pour les services privés. Vérifiez le démarrage à l’aide des logs et de la preuve propre à l’application : créez une note, modifiez-la simultanément depuis deux navigateurs, téléversez une image et authentifiez-vous via le fournisseur sélectionné. Une fois le fonctionnement vérifié, verrouillez la version de l’image afin qu’un remplacement courant ne modifie pas silencieusement le comportement.

Ne donnez pas à HedgeDoc les droits sur tout l’hôte

Pour HedgeDoc, la surface utile ne se limite pas forcément à la landing page. L’erreur principale consiste à utiliser un exemple de secret de session ou à autoriser involontairement la création anonyme de notes. Corrigez-la délibérément : utilisez un secret de session stable, décidez si la création anonyme de notes est acceptable et restreignez l’accès aux notes privées.

Générez CMD_SESSION_SECRET comme une valeur aléatoire longue ; sa rotation invalide normalement les sessions ou les tokens. Anticipez donc son impact sur les utilisateurs au lieu de la considérer comme une migration de chiffrement. Utilisez un utilisateur de container non privilégié lorsque l’image le permet et ne montez aucun identifiant sans rapport. Appliquez les limites de débit ou de taille au niveau de l’ingress, là où des opérations non fiables peuvent consommer des connexions WebSocket, des écritures en base de données, des médias téléversés et l’historique des documents.

Tester HedgeDoc depuis l’extérieur du serveur

Choisissez le hostname HedgeDoc définitif avant que les utilisateurs n’enregistrent des callbacks ou des paramètres client, puis configurez CMD_DOMAIN et CMD_PROTOCOL_USESSL pour l’URL publique. La route de la plateforme doit terminer TLS une seule fois et cibler le port privé 3000.

Exécutez la transaction d’acceptation depuis l’extérieur. Si le client n’atteint jamais HedgeDoc, utilisez la checklist de validation SSL pour vérifier le DNS et le certificat. Si la requête atteint HedgeDoc mais que les éditions en temps réel échouent à cause des WebSockets ou de paramètres de domaine incorrects, cessez de modifier les redirections du proxy et examinez plutôt la boundary propre à l’application.

Exploiter HedgeDoc autour de son vrai goulot d’étranglement

Utilisez « créer une note, la modifier simultanément depuis deux navigateurs, téléverser une image et s’authentifier via le fournisseur sélectionné » comme smoke test HedgeDoc après chaque déploiement. Les métriques associées sont les connexions WebSocket, les écritures en base de données, les médias téléversés et l’historique des documents ; configurez les alertes lorsque ces ressources approchent un seuil qui dégrade l’action de l’utilisateur.

Le principal risque lors d’une modification vient du fait que les migrations de base de données, les paramètres OAuth et les changements de plugin ou de renderer de HedgeDoc nécessitent une release progressive. Une release sûre commence par un snapshot restaurable et valide toute modification d’état irréversible avant le basculement du trafic. Lorsque les éditions en temps réel échouent à cause des WebSockets ou de paramètres de domaine incorrects, conservez le container défaillant assez longtemps pour lire sa configuration et sa première erreur.

Ce que Dockup prend en charge pour HedgeDoc

Dockup peut gérer les composants remplaçables de la plateforme : acheminer le trafic vers le port 3000, émettre le domaine et le certificat, injecter les secrets, monter le stockage persistant et connecter HedgeDoc à des services managés ou attachés en privé. Cette opération peut être effectuée sur l’infrastructure Dockup ou sur un serveur que vous rattachez.

Le travail d’acceptation de HedgeDoc reste explicite. Après le déploiement en un clic, configurez CMD_DOMAIN et CMD_PROTOCOL_USESSL pour l’URL publique, connectez et testez Postgres ainsi que les fournisseurs OAuth et SMTP facultatifs, puis exécutez ce scénario : créez une note, modifiez-la simultanément depuis deux navigateurs, téléversez une image et authentifiez-vous via le fournisseur sélectionné. Cette séparation est intentionnelle : Dockup élimine la configuration répétitive de l’infrastructure sans prétendre que les rôles applicatifs, les identifiants des fournisseurs ou la politique de restauration se définissent automatiquement.

Foire aux questions

De quoi HedgeDoc a-t-il besoin pour un déploiement en production ?

Acheminez le container HedgeDoc sur le port 3000 via une origine HTTPS unique. La dépendance réseau associée est Postgres ainsi que, facultativement, des fournisseurs OAuth et SMTP. Ne considérez pas HedgeDoc comme prêt tant que vous ne pouvez pas créer une note, la modifier simultanément depuis deux navigateurs, téléverser une image et vous authentifier via le fournisseur sélectionné.

Quelles données HedgeDoc doivent figurer dans une sauvegarde ?

Conservez /hedgedoc/public/uploads et incluez la base de données, les fichiers téléversés et la configuration d’authentification dans le même manifest de reprise. Une restauration propre de HedgeDoc n’est validée que lorsque les notes, les révisions, les utilisateurs et les fichiers téléversés sont rétablis et que deux navigateurs peuvent collaborer sur la note restaurée.

HedgeDoc nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origine publique de HedgeDoc et gardez le port 3000 sur la route interne. Appliquez correctement le paramètre HedgeDoc : configurez CMD_DOMAIN et CMD_PROTOCOL_USESSL pour l’URL publique. Pour HedgeDoc, HTTPS protège les identifiants ou le contenu utilisateur en transit et garantit un comportement cohérent du client, sensible à l’origine.

Comment tester une mise à niveau de HedgeDoc ?

Restaurez l’état actuel de HedgeDoc 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, les paramètres OAuth et les changements de plugin ou de renderer de HedgeDoc nécessitent une release progressive. Conservez l’image HedgeDoc précédente jusqu’à ce que les limites de migration des données et de rollback soient bien comprises.