Cum să găzduiești HedgeDoc pe cont propriu în 2026: WebSockets, OAuth și fișiere încărcate

Există două versiuni ale „rulării HedgeDoc”: există un container sau serviciul își îndeplinește efectiv rolul. Doar a doua contează. Dovada constă în crearea unei note, editarea ei simultană din două browsere, încărcarea unei imagini și autentificarea prin furnizorul selectat.

HedgeDoc este destinat acestui scop: note Markdown colaborative, în timp real. Implementarea trebuie să păstreze componentele din spatele acestui comportament; un port, un volum și un certificat sunt elemente de intrare, nu rezultatul final.

Fă backup pentru starea pe care HedgeDoc nu o poate recrea

Definește obiectivul de recuperare și timpul de recuperare pentru HedgeDoc în funcție de baza de date, fișierele încărcate și configurația de autentificare. Montează /hedgedoc/public/uploads înainte de bootstrap, scrie date de test inofensive și înlocuiește containerul pentru a demonstra că acea cale este într-adevăr persistentă. Un volum denumit rezolvă persistența la redeploy; nu rezolvă însă compromiterea sau pierderea serverului.

Construiește un mediu curat de restaurare, folosește aceeași versiune fixată a aplicației și demonstrează că notele, reviziile, utilizatorii și fișierele încărcate reapar și că două browsere pot colabora la nota restaurată. Notează comenzile, ajustările de ownership și durata. Ghidul pentru backupuri este un standard util: un backup este considerat de încredere după restaurare, nu după încărcare.

Separă HedgeDoc de dependențele sale

Starea procesului și starea produsului sunt lucruri diferite pentru HedgeDoc. Portul 3000 poate răspunde, în timp ce tranzacția vizibilă pentru utilizator eșuează în continuare. Contractul de rețea pentru HedgeDoc constă în Postgres, plus furnizorii opționali OAuth și SMTP. Păstrează endpointurile private în DNS intern, permite doar apelurile outbound necesare și oferă-i lui HedgeDoc un service credential cu permisiuni limitate.

Folosește acest exercițiu de verificare a disponibilității după modificări importante de configurație: creează o notă, editeaz-o simultan din două browsere, încarcă o imagine și autentifică-te prin furnizorul selectat. Nu include verificări externe costisitoare în probele de liveness, pentru ca o întrerupere a furnizorului să nu provoace o buclă de restarturi. Lucrările de capacity planning ar trebui să urmărească conexiunile WebSocket, operațiile de scriere în baza de date, media încărcată și istoricul documentelor — indicatori mai apropiați de presiunea reală asupra HedgeDoc decât cererile pentru pagini.

Cinci verificări mai solide decât starea de sănătate a containerului

Transformă smoke test-ul pentru HedgeDoc într-o comandă repetabilă de release sau într-un runbook scurt. Rezultatul trebuie să demonstreze următorul scenariu: creează o notă, editeaz-o simultan din două browsere, încarcă o imagine și autentifică-te prin furnizorul selectat. Înregistrează versiunea aplicației, digestul containerului, hostname-ul rutei și identificatorul datelor de test împreună cu rezultatul.

Rulează aceeași verificare după un înlocuitor obișnuit al containerului și după restaurarea bazei de date, a fișierelor încărcate și a configurației de autentificare într-un alt loc. Restaurarea a reușit atunci când notele, reviziile, utilizatorii și fișierele încărcate reapar, iar două browsere pot colabora la nota restaurată. Compară durata și consumul asociate conexiunilor WebSocket, operațiilor de scriere în baza de date, conținutului media încărcat și istoricului documentelor; o schimbare mare merită investigată chiar dacă acțiunea finală trece în continuare.

Apoi simulează o defecțiune sigură: refuză temporar identității de test accesul la Postgres, precum și la furnizorii opționali OAuth și SMTP. Confirmă că HedgeDoc semnalează problema și revine la normal fără modificări manuale distructive. Păstrează doar fragmentul de log necesar, cu datele sensibile eliminate. Această verificare în patru părți acoperă pornirea, persistența, recuperarea și gestionarea defecțiunilor.

Pornește HedgeDoc fără să ascunzi componentele importante

O comandă minimală este utilă atunci când arată clar ce va administra ulterior platforma.

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

Aici, portul 3000 rămâne privat la nivelul hostului, iar fiecare cale necesară este explicită. Adaugă setările de conexiune verificate pentru Postgres, precum și pentru furnizorii opționali OAuth și SMTP; folosește nume private pentru serviciile private. Verifică pornirea atât prin loguri, cât și prin dovada specifică aplicației: creează o notă, editeaz-o simultan din două browsere, încarcă o imagine și autentifică-te prin furnizorul selectat. După verificare, fixează versiunea imaginii pentru ca o înlocuire obișnuită să nu schimbe comportamentul în mod silențios.

Nu-i oferi lui HedgeDoc acces la întregul host

Pentru HedgeDoc, suprafața importantă nu este neapărat pagina de pornire. Greșeala principală este folosirea unui session secret din exemplu sau permiterea neintenționată a creării anonime de note. Contracarează aceste riscuri în mod deliberat: folosește un session secret stabil, decide dacă este acceptabilă crearea anonimă de note și restricționează accesul la notele private.

Generează CMD_SESSION_SECRET ca valoare aleatorie lungă; rotirea acesteia invalidează de obicei sesiunile sau tokenurile, așa că planifică impactul asupra utilizatorilor în loc să o tratezi ca pe o migrare de criptare. Folosește un utilizator de container fără privilegii atunci când imaginea permite acest lucru și nu monta credentiale fără legătură cu aplicația. Aplică limite de rată sau de dimensiune la ingress, acolo unde activitatea neîncrezătoare poate consuma conexiuni WebSocket, operații de scriere în baza de date, media încărcată și istoricul documentelor.

Testează HedgeDoc din afara serverului

Alege hostname-ul final pentru HedgeDoc înainte ca utilizatorii să salveze callback-uri sau setări de client, apoi setează CMD_DOMAIN și CMD_PROTOCOL_USESSL pentru URL-ul public. Ruta platformei ar trebui să încheie conexiunea TLS o singură dată și să trimită traficul către portul privat 3000.

Rulează tranzacția de acceptanță din exterior. Dacă clientul nu ajunge niciodată la HedgeDoc, folosește checklistul de validare SSL pentru verificările DNS și ale certificatului. Dacă cererea ajunge la HedgeDoc, dar editarea în timp real eșuează din cauza WebSockets sau a setărilor de domeniu, nu mai modifica redirecturile proxy și verifică în schimb limita specifică aplicației.

Administrează HedgeDoc în funcție de blocajul său real

Folosește scenariul „creează o notă, editeaz-o simultan din două browsere, încarcă o imagine și autentifică-te prin furnizorul selectat” ca smoke test pentru HedgeDoc după fiecare deployment. Indicatorii asociați sunt conexiunile WebSocket, operațiile de scriere în baza de date, media încărcată și istoricul documentelor; configurează alerte atunci când aceste resurse se apropie de un nivel care degradează acțiunea utilizatorului.

Principalul risc la schimbări este că migrările bazei de date HedgeDoc, setările OAuth și modificările pluginurilor sau ale rendererului necesită un release staged. Un release sigur pornește de la un snapshot care poate fi restaurat și validează orice schimbare de stare într-un singur sens înainte de mutarea traficului. Atunci când editarea în timp real eșuează din cauza WebSockets sau a setărilor de domeniu, păstrează containerul defect suficient timp pentru a-i citi configurația și prima eroare.

Unde elimină Dockup munca repetitivă pentru HedgeDoc

Dockup poate administra componentele înlocuibile ale platformei: poate direcționa traficul către portul 3000, poate emite domeniul și certificatul, poate injecta secrete, poate atașa stocare persistentă și poate conecta HedgeDoc la servicii gestionate sau atașate privat. Acest lucru se poate face pe infrastructura Dockup sau pe un server pe care îl conectezi.

Activitățile de acceptanță pentru HedgeDoc rămân explicite. După deployment-ul one-click, setează CMD_DOMAIN și CMD_PROTOCOL_USESSL pentru URL-ul public, conectează și testează Postgres, precum și furnizorii opționali OAuth și SMTP, apoi rulează acest scenariu: creează o notă, editeaz-o simultan din două browsere, încarcă o imagine și autentifică-te prin furnizorul selectat. Această împărțire este intenționată: Dockup elimină configurarea repetitivă a infrastructurii fără să pretindă că rolurile aplicației, credentialele furnizorilor sau politica de restaurare se stabilesc singure.

Întrebări frecvente

De ce are nevoie HedgeDoc pentru un deployment în producție?

Direcționează containerul HedgeDoc de pe portul 3000 printr-un singur origin HTTPS. Cerința de rețea asociată este Postgres, plus furnizorii opționali OAuth și SMTP. Nu considera HedgeDoc pregătit până când nu poți crea o notă, edita-o simultan din două browsere, încărca o imagine și te autentifica prin furnizorul selectat.

Ce date HedgeDoc trebuie incluse într-un backup?

Păstrează /hedgedoc/public/uploads și include baza de date, fișierele încărcate și configurația de autentificare în același manifest de recuperare. O restaurare HedgeDoc curată este reușită doar atunci când notele, reviziile, utilizatorii și fișierele încărcate reapar, iar două browsere pot colabora la nota restaurată.

Are HedgeDoc nevoie de HTTPS în spatele unui reverse proxy?

Folosește HTTPS pentru origin-ul public HedgeDoc și păstrează portul 3000 pe ruta internă. Aplică corect setarea HedgeDoc: setează CMD_DOMAIN și CMD_PROTOCOL_USESSL pentru URL-ul public. Pentru HedgeDoc, HTTPS protejează credentialele sau conținutul utilizatorilor în tranzit și menține consecvent comportamentul clientului dependent de origin.

Cum ar trebui testat un upgrade HedgeDoc?

Restaurează starea curentă HedgeDoc într-un deployment izolat, aplică versiunea candidată și repetă tranzacția de acceptanță. Acordă o atenție deosebită acestui aspect, deoarece migrările bazei de date HedgeDoc, setările OAuth și modificările pluginurilor sau ale rendererului necesită un release staged. Păstrează imaginea HedgeDoc anterioară până când înțelegi limita de migrare a datelor și de rollback.