Så självhostar du HedgeDoc 2026: WebSockets, OAuth och uppladdade filer

Det finns två versioner av att ”köra HedgeDoc”: en container existerar, eller så utför tjänsten faktiskt sitt jobb. Det är bara det senare som spelar roll. Här är beviset att skapa en anteckning, redigera den samtidigt från två webbläsare, ladda upp en bild och autentisera via den valda providern.

HedgeDoc är till för detta: Markdown-anteckningar för samarbete i realtid. Distributionen måste bevara delarna bakom detta beteende; en port, en volym och ett certifikat är förutsättningar, inte resultatet.

Säkerhetskopiera det tillstånd som HedgeDoc inte kan återskapa

Definiera återställningspunkt och återställningstid för HedgeDoc utifrån databas, uppladdade filer och autentiseringskonfiguration. Montera /hedgedoc/public/uploads före bootstrap, skriv ofarliga exempeldata och ersätt containern för att bevisa att sökvägen faktiskt är persistent. En namngiven volym löser persistens vid redeploy; den löser inte intrång eller förlust av servern.

Bygg en ren återställningsmiljö, använd samma låsta applikationsversion och bevisa att anteckningar, revisioner, användare och uppladdningar återkommer och att två webbläsare kan samarbeta i den återställda anteckningen. Dokumentera kommandon, korrigeringar av ägarskap och tidsåtgång. Guiden för säkerhetskopiering är en användbar standard: en säkerhetskopia är tillförlitlig efter återställning, inte efter uppladdning.

Separera HedgeDoc från dess beroenden

Processhälsa och produkthälsa är separata för HedgeDoc. Port 3000 kan svara medan den användarvända transaktionen fortfarande misslyckas. Nätverkskontraktet för HedgeDoc är Postgres samt valfria OAuth- och SMTP-providers. Håll privata endpoints på intern DNS, tillåt endast nödvändiga utgående anslutningar och ge HedgeDoc en avgränsad service credential.

Använd detta readiness-test efter meningsfulla konfigurationsändringar: skapa en anteckning, redigera den samtidigt från två webbläsare, ladda upp en bild och autentisera via den valda providern. Håll kostsamma externa kontroller borta från liveness probes så att ett avbrott hos en provider inte orsakar en restart loop. Kapacitetsarbetet bör följa WebSocket-anslutningar, databasskrivningar, uppladdade medier och dokumenthistorik, vilket ligger närmare HedgeDocs verkliga belastning än sidförfrågningar.

Fem kontroller som är starkare än container health

Gör HedgeDocs smoke test till ett repeterbart release-kommando eller en kort runbook. Resultatet måste visa detta: skapa en anteckning, redigera den samtidigt från två webbläsare, ladda upp en bild och autentisera via den valda providern. Registrera applikationsversion, container digest, route-hostnamn och testdataidentifierare tillsammans med resultatet.

Kör samma kontroll efter ett vanligt containerbyte och efter att databas, uppladdade filer och autentiseringskonfiguration har återställts någon annanstans. Återställningen är lyckad när anteckningar, revisioner, användare och uppladdningar återkommer och två webbläsare kan samarbeta i den återställda anteckningen. Jämför tidsåtgång och förbrukning kopplad till WebSocket-anslutningar, databasskrivningar, uppladdade medier och dokumenthistorik; en stor förändring är värd att undersöka även när den sista åtgärden fortfarande lyckas.

Testa sedan ett säkert fel: neka tillfälligt testidentiteten åtkomst till Postgres samt valfria OAuth- och SMTP-providers. Bekräfta att HedgeDoc visar felet och återgår till normalt läge utan destruktiva manuella ändringar. Spara endast det nödvändiga, redigerade loggutdraget. Denna fyrdelade grind täcker uppstart, persistens, återställning och felhantering.

Starta HedgeDoc utan att dölja de rörliga delarna

Ett minimalt kommando är användbart när det visar vad plattformen senare kommer att hantera.

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

Här förblir port 3000 privat på värden och alla nödvändiga sökvägar är explicita. Lägg till de granskade anslutningsinställningarna för Postgres samt valfria OAuth- och SMTP-providers; använd privata namn för privata tjänster. Verifiera uppstarten med både loggar och det applikationsspecifika beviset: skapa en anteckning, redigera den samtidigt från två webbläsare, ladda upp en bild och autentisera via den valda providern. När allt är verifierat låser du image-versionen så att ett vanligt byte inte i tysthet ändrar beteendet.

Ge inte HedgeDoc tillgång till hela värden

För HedgeDoc är den värdefulla attackytan inte nödvändigtvis landningssidan. Det vanligaste misstaget är att använda ett exempelvärde för session secret eller oavsiktligt tillåta att anonyma användare skapar anteckningar. Motverka detta medvetet: använd en stabil session secret, avgör om anonymt skapande av anteckningar är acceptabelt och begränsa åtkomsten till privata anteckningar.

Generera CMD_SESSION_SECRET som ett långt slumpmässigt värde; en rotation gör normalt sessioner eller tokens ogiltiga, så planera användarpåverkan i stället för att kalla det en krypteringsmigrering. Använd en oprivilegierad containeranvändare när imagen stöder det och montera inga orelaterade credentials. Tillämpa rate- eller storleksbegränsningar vid ingress där otillförlitligt arbete kan förbruka WebSocket-anslutningar, databasskrivningar, uppladdade medier och dokumenthistorik.

Testa HedgeDoc utifrån servern

Välj det slutliga HedgeDoc-värdnamnet innan användare sparar callbacks eller klientinställningar, och ställ sedan in CMD_DOMAIN och CMD_PROTOCOL_USESSL för den publika URL:en. Plattformens route bör terminera TLS en gång och vidarebefordra till den privata porten 3000.

Kör acceptanstestet externt. Om klienten aldrig når HedgeDoc använder du checklistan för SSL-validering för DNS- och certifikatkontroller. Om förfrågan når HedgeDoc men realtidsredigering misslyckas på grund av att WebSockets eller domäninställningarna är fel, sluta ändra proxy-redirects och granska i stället den applikationsspecifika gränsen.

Drifta HedgeDoc utifrån dess verkliga flaskhals

Använd skapa en anteckning, redigera den samtidigt från två webbläsare, ladda upp en bild och autentisera via den valda providern som HedgeDocs smoke test efter varje deployment. De stödjande mätvärdena är WebSocket-anslutningar, databasskrivningar, uppladdade medier och dokumenthistorik; larma där dessa resurser närmar sig en nivå som försämrar användaråtgärden.

Den största förändringsrisken är att HedgeDocs databas­migreringar, OAuth-inställningar och ändringar av plugin eller renderer kräver en staged release. En säker release börjar med en återställningsbar snapshot och validerar alla enkelriktade tillståndsändringar innan trafik flyttas. När realtidsredigering misslyckas på grund av att WebSockets eller domäninställningarna är fel ska du behålla den felande containern tillräckligt länge för att läsa konfigurationen och det första felet.

Där Dockup minskar arbetet med HedgeDoc

Dockup kan hantera de utbytbara plattformsdelarna: routa trafik till port 3000, utfärda domän och certifikat, injicera secrets, ansluta persistent lagring och koppla HedgeDoc till managed eller privat anslutna tjänster. Detta kan göras på Dockup-infrastruktur eller på en server som du ansluter.

Acceptansarbetet för HedgeDoc är fortfarande explicit. Efter one-click-deploymenten ställer du in CMD_DOMAIN och CMD_PROTOCOL_USESSL för den publika URL:en, ansluter och testar Postgres samt valfria OAuth- och SMTP-providers och kör detta scenario: skapa en anteckning, redigera den samtidigt från två webbläsare, ladda upp en bild och autentisera via den valda providern. Den uppdelningen är avsiktlig: Dockup tar bort repetitiv infrastrukturkonfiguration utan att låtsas att applikationsroller, provider-credentials eller återställningspolicy väljer sig själva.

Vanliga frågor

Vad behöver HedgeDoc för en produktionsdeployment?

Routa HedgeDoc-containern på port 3000 via ett enda HTTPS-origin. Det stödjande nätverkskravet är Postgres samt valfria OAuth- och SMTP-providers. Kalla inte HedgeDoc redo förrän du kan skapa en anteckning, redigera den samtidigt från två webbläsare, ladda upp en bild och autentisera via den valda providern.

Vilka HedgeDoc-data ska ingå i en säkerhetskopia?

Gör /hedgedoc/public/uploads persistent och inkludera databas, uppladdade filer och autentiseringskonfiguration i samma återställningsmanifest. En ren HedgeDoc-återställning är godkänd först när anteckningar, revisioner, användare och uppladdningar återkommer och två webbläsare kan samarbeta i den återställda anteckningen.

Kräver HedgeDoc HTTPS bakom en reverse proxy?

Använd HTTPS för det publika HedgeDoc-originet och behåll port 3000 på den interna routen. Tillämpa HedgeDoc-inställningen korrekt: ställ in CMD_DOMAIN och CMD_PROTOCOL_USESSL för den publika URL:en. För HedgeDoc skyddar HTTPS credentials eller användarinnehåll under överföring och ser till att originskänsligt klientbeteende förblir konsekvent.

Hur bör en HedgeDoc-uppgradering testas?

Återställ aktuellt HedgeDoc-tillstånd till en isolerad deployment, tillämpa kandidatversionen och upprepa dess acceptanstransaktion. Var särskilt uppmärksam eftersom HedgeDocs databas­migreringar, OAuth-inställningar och ändringar av plugin eller renderer kräver en staged release. Behåll den tidigare HedgeDoc-imagen tills dess datamigrerings- och rollback-gräns är förstådd.