Slik drifter du HedgeDoc selv i 2026: WebSockets, OAuth og opplastede filer

Det finnes to varianter av «å kjøre HedgeDoc»: Enten finnes det en container, eller så utfører tjenesten den faktiske jobben sin. Det er bare den siste varianten som teller. Her er beviset at du kan opprette et notat, redigere det samtidig i to nettlesere, laste opp et bilde og autentisere via den valgte leverandøren.

HedgeDoc er laget for dette: Markdown-notater for samarbeid i sanntid. Distribusjonen må ta vare på komponentene som muliggjør denne oppførselen; en port, et volume og et sertifikat er forutsetninger, ikke resultatet.

Sikkerhetskopier tilstanden HedgeDoc ikke kan gjenskape

Definer gjenopprettingspunkt og gjenopprettingstid for HedgeDoc med utgangspunkt i databasen, opplastede filer og autentiseringskonfigurasjonen. Monter /hedgedoc/public/uploads før oppstart, skriv ufarlige eksempeldata og erstatt containeren for å bevise at banen faktisk er persistent. Et navngitt volume løser persistens ved redeploy; det beskytter deg ikke mot kompromittering eller tap av serveren.

Bygg et rent gjenopprettingsmiljø, bruk den samme låste applikasjonsversjonen og bekreft at notater, revisjoner, brukere og opplastinger kommer tilbake, og at to nettlesere kan samarbeide om det gjenopprettede notatet. Dokumenter kommandoer, retting av eierskap og medgått tid. Veiledningen for sikkerhetskopiering er en nyttig standard: En sikkerhetskopi er til å stole på etter gjenoppretting, ikke etter opplasting.

Skill HedgeDoc fra avhengighetene

Prosesshelse og produkthelse er to forskjellige ting for HedgeDoc. Port 3000 kan svare selv om brukertransaksjonen fortsatt mislykkes. Nettverkskontrakten for HedgeDoc er Postgres samt valgfrie OAuth- og SMTP-leverandører. Hold private endepunkter på intern DNS, tillat bare nødvendige utgående kall og gi HedgeDoc en avgrenset tjenestelegitimasjon.

Bruk denne readiness-øvelsen etter vesentlige konfigurasjonsendringer: Opprett et notat, rediger det samtidig i to nettlesere, last opp et bilde og autentiser via den valgte leverandøren. Hold kostbare eksterne kontroller borte fra liveness-prober, slik at et leverandøravbrudd ikke fører til en restart-loop. Kapasitetsarbeidet bør følge med på WebSocket-tilkoblinger, databaseskrivinger, opplastede medier og dokumenthistorikk. Det sier mer om det reelle belastningspunktet i HedgeDoc enn sideforespørsler gjør.

Fem kontroller som er bedre enn containerhelse

Gjør HedgeDocs smoke-test om til en repeterbar release-kommando eller en kort runbook. Resultatet må dokumentere dette utfallet: Opprett et notat, rediger det samtidig i to nettlesere, last opp et bilde og autentiser via den valgte leverandøren. Registrer applikasjonsversjon, container-digest, rutevertsnavn og identifikator for testdata sammen med resultatet.

Kjør den samme kontrollen etter et vanlig containerskifte og etter at databasen, opplastede filer og autentiseringskonfigurasjonen er gjenopprettet et annet sted. Gjenopprettingen er vellykket når notater, revisjoner, brukere og opplastinger kommer tilbake, og to nettlesere kan samarbeide om det gjenopprettede notatet. Sammenlign tidsbruk og forbruk knyttet til WebSocket-tilkoblinger, databaseskrivinger, opplastede medier og dokumenthistorikk. En stor endring bør undersøkes, selv når den siste handlingen fortsatt lykkes.

Test deretter en trygg feilscenario: Avslå midlertidig testidentitetens tilgang til Postgres samt valgfrie OAuth- og SMTP-leverandører. Bekreft at HedgeDoc viser feilen og går tilbake til normal drift uten destruktive manuelle endringer. Ta vare på bare det nødvendige, anonymiserte utdraget fra loggen. Denne kontrollen i fire deler dekker oppstart, persistens, gjenoppretting og feilhåndtering.

Start HedgeDoc uten å skjule de viktige delene

En minimal kommando er nyttig når den viser hva plattformen senere skal håndtere.

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 forblir port 3000 privat for verten, og alle nødvendige baner er eksplisitte. Legg til de gjennomgåtte tilkoblingsinnstillingene for Postgres samt valgfrie OAuth- og SMTP-leverandører; bruk private navn for private tjenester. Bekreft oppstart med både logger og det applikasjonsspesifikke beviset: Opprett et notat, rediger det samtidig i to nettlesere, last opp et bilde og autentiser via den valgte leverandøren. Når dette er bekreftet, låser du image-versjonen slik at et vanlig skifte ikke endrer oppførselen i det skjulte.

Ikke gi HedgeDoc tilgang til hele verten

For HedgeDoc er det verdifulle angrepsområdet ikke nødvendigvis landingssiden. Den vanligste feilen er å bruke et eksempel på en session secret eller utilsiktet tillate at anonyme brukere oppretter notater. Motvirk dette bevisst: Bruk en stabil session secret, avgjør om anonyme notater er akseptable, og begrens tilgangen til private notater.

Generer CMD_SESSION_SECRET som en lang, tilfeldig verdi. Når den roteres, blir sesjoner eller tokens normalt ugyldige, så planlegg konsekvensene for brukerne i stedet for å omtale dette som en krypteringsmigrering. Bruk en containerbruker uten privilegier når imaget støtter det, og monter ingen uvedkommende legitimasjoner. Bruk rate- eller størrelsesbegrensninger ved ingressen, der arbeid fra brukere du ikke stoler på kan forbruke WebSocket-tilkoblinger, databaseskrivinger, opplastede medier og dokumenthistorikk.

Test HedgeDoc utenfra serveren

Velg det endelige vertsnavnet for HedgeDoc før brukerne lagrer callbacks eller klientinnstillinger, og angi deretter CMD_DOMAIN og CMD_PROTOCOL_USESSL for den offentlige URL-en. Plattformruten bør terminere TLS én gang og videresende til den private porten 3000.

Kjør akseptansetransaksjonen eksternt. Hvis klienten aldri når HedgeDoc, kan du bruke sjekklisten for SSL-validering til kontroller av DNS og sertifikat. Hvis forespørselen når HedgeDoc, men redigering i sanntid ikke fungerer fordi WebSockets eller domeneinnstillingene er feil, må du slutte å endre proxy-redirects og heller undersøke den applikasjonsspesifikke grensen.

Drift HedgeDoc med utgangspunkt i det reelle flaskehalsen

Bruk oppretting av et notat, samtidig redigering i to nettlesere, bildeopplasting og autentisering via den valgte leverandøren som HedgeDocs smoke-test etter hver distribusjon. Støttemetrikkene er WebSocket-tilkoblinger, databaseskrivinger, opplastede medier og dokumenthistorikk. Sett varsler der disse ressursene nærmer seg et nivå som forringer brukerhandlingen.

Den største endringsrisikoen er at databasemigreringer i HedgeDoc, OAuth-innstillinger og endringer i plugins eller renderere krever en trinnvis release. En trygg release starter med et gjenopprettbart snapshot og validerer alle irreversible tilstandsendringer før trafikken flyttes. Når redigering i sanntid ikke fungerer fordi WebSockets eller domeneinnstillingene er feil, bør du beholde den mislykkede containeren lenge nok til å lese konfigurasjonen og den første feilen.

Slik fjerner Dockup arbeid for HedgeDoc

Dockup kan håndtere de utskiftbare plattformdelene: rute trafikk til port 3000, utstede domenet og sertifikatet, injisere secrets, koble til persistent lagring og koble HedgeDoc til administrerte eller privat tilkoblede tjenester. Dette kan gjøres på Dockup-infrastruktur eller på en server du kobler til.

Akseptansearbeidet for HedgeDoc må fortsatt være eksplisitt. Etter distribusjon med ett klikk angir du CMD_DOMAIN og CMD_PROTOCOL_USESSL for den offentlige URL-en, kobler til og tester Postgres samt valgfrie OAuth- og SMTP-leverandører, og kjører dette scenarioet: Opprett et notat, rediger det samtidig i to nettlesere, last opp et bilde og autentiser via den valgte leverandøren. Denne arbeidsdelingen er tilsiktet: Dockup fjerner repetitivt infrastrukturoppsett uten å late som om applikasjonsroller, leverandørlegitimasjon eller gjenopprettingspolicy velger seg selv.

Vanlige spørsmål

Hva trenger HedgeDoc for en produksjonsdistribusjon?

Rute HedgeDoc-containeren på port 3000 gjennom én HTTPS-origin. Det støttende nettverkskravet er Postgres samt valgfrie OAuth- og SMTP-leverandører. Ikke erklær HedgeDoc som klar før du kan opprette et notat, redigere det samtidig i to nettlesere, laste opp et bilde og autentisere via den valgte leverandøren.

Hvilke HedgeDoc-data bør inngå i en sikkerhetskopi?

Gjør /hedgedoc/public/uploads persistent, og inkluder database, opplastede filer og autentiseringskonfigurasjon i det samme gjenopprettingsmanifestet. En ren HedgeDoc-gjenoppretting er først godkjent når notater, revisjoner, brukere og opplastinger kommer tilbake, og to nettlesere kan samarbeide om det gjenopprettede notatet.

Krever HedgeDoc HTTPS bak en reverse proxy?

Bruk HTTPS for den offentlige HedgeDoc-originen, og behold port 3000 på den interne ruten. Bruk HedgeDoc-innstillingen riktig: Angi CMD_DOMAIN og CMD_PROTOCOL_USESSL for den offentlige URL-en. For HedgeDoc beskytter HTTPS legitimasjon eller brukerinnhold under overføring og sørger for at klientoppførsel som avhenger av origin, forblir konsistent.

Hvordan bør en HedgeDoc-oppgradering testes?

Gjenopprett den aktuelle HedgeDoc-tilstanden i en isolert distribusjon, bruk kandidatversjonen og gjenta akseptansetransaksjonen. Vær spesielt oppmerksom på dette, fordi databasemigreringer i HedgeDoc, OAuth-innstillinger og endringer i plugins eller renderere krever en trinnvis release. Behold det forrige HedgeDoc-imaget til grensen for datamigrering og rollback er forstått.