HedgeDoc zelf hosten in 2026: WebSockets, OAuth en geüploade bestanden

Er zijn twee versies van “HedgeDoc draaien”: er bestaat een container, of de service voert zijn echte taak uit. Alleen de tweede telt. Het bewijs bestaat hier uit een notitie maken, die gelijktijdig vanuit twee browsers bewerken, een afbeelding uploaden en authenticeren via de geselecteerde provider.

HedgeDoc is bedoeld voor realtime samenwerkende Markdown-notities. De deployment moet de onderdelen achter dat gedrag behouden; een poort, een volume en een certificaat zijn invoer, niet het resultaat.

Maak een backup van de state die HedgeDoc niet kan reconstrueren

Definieer het recovery point en de recovery time voor HedgeDoc aan de hand van de database, geüploade bestanden en authenticatieconfiguratie. Mount /hedgedoc/public/uploads voordat je de bootstrap uitvoert, schrijf onschadelijke voorbeelddata en vervang de container om te bewijzen dat dat pad daadwerkelijk persistent is. Een named volume zorgt voor persistentie bij redeployments; het beschermt niet tegen een compromise of serververlies.

Bouw een schone restore-omgeving, gebruik dezelfde gepinde applicatieversie en bewijs dat notities, revisies, gebruikers en uploads terugkomen en dat twee browsers kunnen samenwerken aan de herstelde notitie. Leg commando's, aanpassingen van eigenaarschap en de verstreken tijd vast. De backuphandleiding is een bruikbare standaard: een backup is pas betrouwbaar na een restore, niet na het uploaden.

Houd HedgeDoc en zijn dependencies gescheiden

De procesgezondheid en productgezondheid staan bij HedgeDoc los van elkaar. Poort 3000 kan antwoorden terwijl de user-facing transactie nog steeds mislukt. Het netwerkcontract voor HedgeDoc bestaat uit Postgres plus optionele OAuth- en SMTP-providers. Houd private endpoints op interne DNS, sta alleen noodzakelijke uitgaande verbindingen toe en geef HedgeDoc een service credential met beperkte scope.

Gebruik deze readiness-oefening na betekenisvolle configuratiewijzigingen: maak een notitie, bewerk die gelijktijdig vanuit twee browsers, upload een afbeelding en authenticeer via de geselecteerde provider. Houd dure externe checks uit liveness probes, zodat een storing bij een provider geen restart loop veroorzaakt. Volg bij capaciteitswerk WebSocket-verbindingen, databasewrites, geüploade media en documentgeschiedenis; die geven een beter beeld van de echte belasting van HedgeDoc dan paginaverzoeken.

Vijf checks die sterker zijn dan container health

Maak van de HedgeDoc-smoketest een herhaalbaar releasecommando of een korte runbook. De uitvoer moet het volgende resultaat aantonen: maak een notitie, bewerk die gelijktijdig vanuit twee browsers, upload een afbeelding en authenticeer via de geselecteerde provider. Leg samen met het resultaat de applicatieversie, container digest, route-hostname en identifier van de testdata vast.

Voer dezelfde check uit na een gewone containerswap en na het elders herstellen van de database, geüploade bestanden en authenticatieconfiguratie. De restore is geslaagd wanneer notities, revisies, gebruikers en uploads terugkomen en twee browsers kunnen samenwerken aan de herstelde notitie. Vergelijk de timing en het verbruik van WebSocket-verbindingen, databasewrites, geüploade media en documentgeschiedenis; een grote verandering verdient onderzoek, ook wanneer de laatste actie nog steeds slaagt.

Voer daarna een veilige fouttest uit: blokkeer tijdelijk de toegang van de testidentiteit tot Postgres plus optionele OAuth- en SMTP-providers. Controleer of HedgeDoc de fout zichtbaar maakt en terugkeert naar de normale toestand zonder destructieve handmatige wijzigingen. Bewaar alleen het noodzakelijke, geredigeerde logfragment. Deze vierdelige gate dekt startup, persistentie, recovery en foutafhandeling.

Start HedgeDoc zonder de bewegende onderdelen te verbergen

Een minimaal commando is nuttig wanneer het laat zien wat het platform later zal beheren.

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

Hier blijft poort 3000 privé op de host en is elk vereist pad expliciet. Voeg de gecontroleerde verbindingsinstellingen voor Postgres plus optionele OAuth- en SMTP-providers toe; gebruik private namen voor private services. Controleer de startup met zowel logs als het applicatiespecifieke bewijs: maak een notitie, bewerk die gelijktijdig vanuit twee browsers, upload een afbeelding en authenticeer via de geselecteerde provider. Zodra alles is geverifieerd, leg je de imageversie vast, zodat een gewone vervanging het gedrag niet stilzwijgend wijzigt.

Geef HedgeDoc niet de volledige host

Voor HedgeDoc bevindt het waardevolle oppervlak zich niet noodzakelijk op de landingspagina. De belangrijkste fout is het gebruiken van een voorbeeld voor het session secret of het onbedoeld toestaan van anoniem aanmaken van notities. Pak dit doelgericht aan: gebruik een stabiel session secret, beslis of anoniem aanmaken van notities acceptabel is en beperk de toegang tot private notities.

Genereer CMD_SESSION_SECRET als een lange, willekeurige waarde; door dit normaal te roteren worden sessies of tokens ongeldig, dus plan de impact voor gebruikers in plaats van dit een encryptiemigratie te noemen. Gebruik een container user zonder verhoogde rechten wanneer de image dit ondersteunt en mount geen niet-gerelateerde credentials. Pas rate- of sizelimieten toe bij de ingress, waar niet-vertrouwd werk WebSocket-verbindingen, databasewrites, geüploade media en documentgeschiedenis kan verbruiken.

Test HedgeDoc van buiten de server

Kies de definitieve HedgeDoc-hostname voordat gebruikers callbacks of clientinstellingen opslaan en stel CMD_DOMAIN en CMD_PROTOCOL_USESSL in voor de publieke URL. De platformroute moet TLS beëindigen en vervolgens doorsturen naar private poort 3000.

Voer de acceptatietransactie extern uit. Als de client HedgeDoc nooit bereikt, gebruik dan de SSL-validatiechecklist voor DNS- en certificaatcontroles. Als het verzoek HedgeDoc wel bereikt maar realtime bewerkingen mislukken doordat WebSockets of domeininstellingen verkeerd zijn, stop dan met het aanpassen van proxy redirects en inspecteer in plaats daarvan de applicatiespecifieke grens.

Beheer HedgeDoc rond het echte knelpunt

Gebruik “een notitie maken, die gelijktijdig vanuit twee browsers bewerken, een afbeelding uploaden en authenticeren via de geselecteerde provider” als HedgeDoc-smoketest na elke deployment. De bijbehorende metrics zijn WebSocket-verbindingen, databasewrites, geüploade media en documentgeschiedenis; stel alerts in waar deze resources een niveau naderen waarop de gebruikersactie verslechtert.

Het grootste risico bij wijzigingen is dat database migrations, OAuth-instellingen en wijzigingen aan plugins of renderers van HedgeDoc een gefaseerde release vereisen. Een veilige release begint met een herstelbare snapshot en valideert elke eenrichtingswijziging in de state voordat het verkeer wordt omgeleid. Wanneer realtime bewerkingen mislukken doordat WebSockets of domeininstellingen verkeerd zijn, houd je de mislukte container lang genoeg actief om de configuratie en de eerste fout te lezen.

Waar Dockup werk voor HedgeDoc wegneemt

Dockup kan de vervangbare platformonderdelen beheren: verkeer naar poort 3000 routeren, het domein en certificaat uitgeven, secrets injecteren, persistente opslag koppelen en HedgeDoc verbinden met managed of private gekoppelde services. Dit kan op de infrastructuur van Dockup of op een server die je koppelt.

Het acceptatiewerk voor HedgeDoc blijft expliciet. Stel na de one-click deployment CMD_DOMAIN en CMD_PROTOCOL_USESSL in voor de publieke URL, verbind met en test Postgres plus optionele OAuth- en SMTP-providers en voer dit scenario uit: maak een notitie, bewerk die gelijktijdig vanuit twee browsers, upload een afbeelding en authenticeer via de geselecteerde provider. Die verdeling is bewust: Dockup neemt repetitieve infrastructuurconfiguratie weg zonder te doen alsof applicatierollen, providercredentials of het restorebeleid vanzelf worden gekozen.

Veelgestelde vragen

Wat heeft HedgeDoc nodig voor een productie-deployment?

Routeer de HedgeDoc-container op poort 3000 via één HTTPS-origin. De ondersteunende netwerkvereiste bestaat uit Postgres plus optionele OAuth- en SMTP-providers. Noem HedgeDoc niet klaar totdat je een notitie kunt maken, die gelijktijdig vanuit twee browsers kunt bewerken, een afbeelding kunt uploaden en via de geselecteerde provider kunt authenticeren.

Welke gegevens van HedgeDoc horen in een backup?

Maak /hedgedoc/public/uploads persistent en neem de database, geüploade bestanden en authenticatieconfiguratie op in hetzelfde recovery manifest. Een schone HedgeDoc-restore is pas geslaagd wanneer notities, revisies, gebruikers en uploads terugkomen en twee browsers kunnen samenwerken aan de herstelde notitie.

Heeft HedgeDoc HTTPS nodig achter een reverse proxy?

Gebruik HTTPS voor de publieke HedgeDoc-origin en houd poort 3000 op de interne route. Pas de HedgeDoc-instelling correct toe: stel CMD_DOMAIN en CMD_PROTOCOL_USESSL in voor de publieke URL. Voor HedgeDoc beschermt HTTPS credentials of gebruikerscontent tijdens transport en zorgt het voor consistent clientgedrag dat gevoelig is voor de origin.

Hoe moet een HedgeDoc-upgrade worden getest?

Herstel de huidige HedgeDoc-state in een geïsoleerde deployment, pas de kandidaatversie toe en herhaal de acceptatietransactie. Let extra goed op, omdat database migrations, OAuth-instellingen en wijzigingen aan plugins of renderers van HedgeDoc een gefaseerde release vereisen. Bewaar de vorige HedgeDoc-image totdat de grenzen voor datamigratie en rollback duidelijk zijn.