Sådan selvhoster du HedgeDoc i 2026: WebSockets, OAuth og uploadede filer

Der findes to versioner af at “køre HedgeDoc”: Enten findes der en container, eller også udfører servicen rent faktisk sin opgave. Kun den sidste del er vigtig. Her består beviset i at oprette en note, redigere den samtidig fra to browsere, uploade et billede og autentificere via den valgte udbyder.

HedgeDoc er beregnet til realtidsbaserede, kollaborative Markdown-noter. Din deployment skal bevare de dele, der gør denne funktionalitet mulig; en port, et volume og et certifikat er input – ikke resultatet.

Tag backup af den tilstand, HedgeDoc ikke kan genskabe

Definér recovery point og recovery time for HedgeDoc med udgangspunkt i databasen, uploadede filer og authentication-konfigurationen. Mount /hedgedoc/public/uploads før bootstrap, skriv harmløse eksempeldata, og udskift derefter containeren for at bevise, at stien faktisk er persistent. Et named volume løser persistence på tværs af redeployments; det beskytter ikke mod kompromittering eller tab af serveren.

Opbyg et rent restore-miljø, brug den samme pinned application-version, og bevis, at noter, revisioner, brugere og uploads kommer tilbage, og at to browsere kan samarbejde om den gendannede note. Dokumentér kommandoer, rettelser af ejerskab og den forløbne tid. Backup-guiden er en nyttig standard: En backup er først pålidelig efter en restore – ikke efter upload.

Adskil HedgeDoc fra dets afhængigheder

Process health og product health er to separate ting i HedgeDoc. Port 3000 kan svare, selvom den brugerrettede transaktion stadig fejler. Netværkskontrakten for HedgeDoc består af Postgres samt valgfrie OAuth- og SMTP-udbydere. Hold private endpoints på intern DNS, tillad kun nødvendige udgående forbindelser, og giv HedgeDoc en begrænset service credential.

Brug denne readiness-øvelse efter væsentlige konfigurationsændringer: Opret en note, rediger den samtidig fra to browsere, upload et billede, og autentificer via den valgte udbyder. Hold dyre eksterne checks ude af liveness probes, så et nedbrud hos en udbyder ikke medfører en restart-loop. Kapacitetsarbejde bør følge WebSocket-forbindelser, databaseskrivninger, uploadede medier og dokumenthistorik, fordi det afspejler HedgeDocs reelle belastning bedre end sideforespørgsler.

Fem checks, der er stærkere end container health

Gør HedgeDocs smoke test til en gentagelig release-kommando eller en kort runbook. Outputtet skal demonstrere dette resultat: Opret en note, rediger den samtidig fra to browsere, upload et billede, og autentificer via den valgte udbyder. Registrér application-versionen, container digest, route-hostnavnet og testdataidentifikatoren sammen med resultatet.

Kør den samme check efter en almindelig containerudskiftning og efter gendannelse af database, uploadede filer og authentication-konfiguration et andet sted. Restoren er lykkedes, når noter, revisioner, brugere og uploads kommer tilbage, og to browsere kan samarbejde om den gendannede note. Sammenlign tidsforbrug og ressourceforbrug relateret til WebSocket-forbindelser, databaseskrivninger, uploadede medier og dokumenthistorik; en stor ændring bør undersøges, selv når den afsluttende handling stadig lykkes.

Udfør derefter en sikker fejltest: Afvis midlertidigt testidentitetens adgang til Postgres samt valgfrie OAuth- og SMTP-udbydere. Bekræft, at HedgeDoc viser fejlen og vender tilbage til normal drift uden destruktive manuelle ændringer. Gem kun det nødvendige, redigerede udsnit af loggen. Denne gate i fire dele dækker opstart, persistence, recovery og fejlhåndtering.

Start HedgeDoc uden at skjule de bevægelige dele

En minimal kommando er nyttig, når den tydeliggør, hvad platformen senere skal administrere.

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

Her forbliver port 3000 privat på hosten, og alle nødvendige stier er eksplicit angivet. Tilføj de gennemgåede forbindelsesindstillinger for Postgres samt valgfrie OAuth- og SMTP-udbydere; brug private navne til private services. Kontrollér opstarten med både logs og det applikationsspecifikke bevis: Opret en note, rediger den samtidig fra to browsere, upload et billede, og autentificer via den valgte udbyder. Når det er verificeret, skal du låse image-versionen, så en almindelig udskiftning ikke i stilhed ændrer adfærden.

Giv ikke HedgeDoc hele hosten

For HedgeDoc er den værdifulde overflade ikke nødvendigvis landing page. Den primære fejl er at bruge en eksempelværdi for session secret eller utilsigtet tillade anonym oprettelse af noter. Modvirk det bevidst: Brug en stabil session secret, beslut om anonym oprettelse af noter er acceptabelt, og begræns adgangen til private noter.

Generér CMD_SESSION_SECRET som en lang, tilfældig værdi; en rotation ugyldiggør normalt sessions eller tokens, så planlæg brugeroplevelsen i stedet for at kalde det en encryption migration. Brug en unprivileged container user, når imaget understøtter det, og mount ingen uvedkommende credentials. Anvend rate- eller størrelsesbegrænsninger ved ingress, hvor ikke-betroet arbejde kan opbruge WebSocket-forbindelser, databaseskrivninger, uploadede medier og dokumenthistorik.

Test HedgeDoc udefra serveren

Vælg det endelige HedgeDoc-hostnavn, før brugerne gemmer callbacks eller client settings, og angiv derefter CMD_DOMAIN og CMD_PROTOCOL_USESSL for den offentlige URL. Platformens route skal terminere TLS én gang og pege på den private port 3000.

Kør acceptance-transaktionen eksternt. Hvis klienten aldrig når frem til HedgeDoc, kan du bruge SSL-valideringschecklisten til DNS- og certifikatkontroller. Hvis requesten når frem til HedgeDoc, men realtidsredigering mislykkes, fordi WebSockets eller domain settings er forkerte, skal du stoppe med at ændre proxy redirects og i stedet undersøge den applikationsspecifikke grænse.

Driftssæt HedgeDoc omkring den reelle flaskehals

Brug oprettelse af en note, samtidig redigering fra to browsere, upload af et billede og authentication via den valgte udbyder som HedgeDocs smoke test efter hver deployment. De understøttende metrics er WebSocket-forbindelser, databaseskrivninger, uploadede medier og dokumenthistorik; opsæt alarmer dér, hvor ressourcerne nærmer sig et niveau, der forringer brugerhandlingen.

Den største ændringsrisiko er, at HedgeDocs databasemigrationer, OAuth-indstillinger og ændringer i plugins eller renderers kræver en staged release. En sikker release starter med et restorebart snapshot og validerer enhver irreversible state change, før trafikken flyttes. Når realtidsredigering mislykkes, fordi WebSockets eller domain settings er forkerte, skal den fejlede container bevares længe nok til, at du kan læse dens konfiguration og den første fejl.

Hvor Dockup fjerner arbejde for HedgeDoc

Dockup kan håndtere de udskiftelige platformdele: route trafik til port 3000, udsted domænet og certifikatet, inject secrets, tilknyt persistent storage, og forbind HedgeDoc med managed services eller privat tilknyttede services. Det kan ske på Dockup-infrastruktur eller på en server, du tilknytter.

Acceptance-arbejdet for HedgeDoc er stadig eksplicit. Efter one-click-deploymenten skal du angive CMD_DOMAIN og CMD_PROTOCOL_USESSL for den offentlige URL, forbinde og teste Postgres samt valgfrie OAuth- og SMTP-udbydere og køre dette scenarie: Opret en note, rediger den samtidig fra to browsere, upload et billede, og autentificer via den valgte udbyder. Denne opdeling er tilsigtet: Dockup fjerner gentagende infrastruktur-setup uden at lade som om, at applikationsroller, credentials til udbydere eller restore-politik vælger sig selv.

Ofte stillede spørgsmål

Hvad skal HedgeDoc bruge til en deployment i produktion?

Route HedgeDoc-containeren på port 3000 gennem én HTTPS-origin. Det understøttende netværkskrav er Postgres samt valgfrie OAuth- og SMTP-udbydere. Kald ikke HedgeDoc klar, før du kan oprette en note, redigere den samtidig fra to browsere, uploade et billede og autentificere via den valgte udbyder.

Hvilke HedgeDoc-data skal med i en backup?

Gør /hedgedoc/public/uploads persistent, og inkludér database, uploadede filer og authentication-konfiguration i det samme recovery-manifest. En ren HedgeDoc-restore er først godkendt, når noter, revisioner, brugere og uploads kommer tilbage, og to browsere kan samarbejde om den gendannede note.

Kræver HedgeDoc HTTPS bag en reverse proxy?

Brug HTTPS til den offentlige HedgeDoc-origin, og behold port 3000 på den interne route. Anvend HedgeDoc-indstillingen korrekt: Angiv CMD_DOMAIN og CMD_PROTOCOL_USESSL for den offentlige URL. For HedgeDoc beskytter HTTPS credentials eller brugerindhold under transport og sikrer en ensartet client-adfærd, der afhænger af origin.

Hvordan bør en HedgeDoc-opgradering testes?

Gendan den aktuelle HedgeDoc-tilstand i en isoleret deployment, anvend kandidatversionen, og gentag acceptance-transaktionen. Vær særligt opmærksom, fordi HedgeDocs databasemigrationer, OAuth-indstillinger og ændringer i plugins eller renderers kræver en staged release. Behold det tidligere HedgeDoc-image, indtil datamigrationens og rollbackens grænser er forstået.