Jak hostovat HedgeDoc na vlastním serveru v roce 2026: WebSockets, OAuth a nahrané soubory

„Spuštění HedgeDoc“ může znamenat dvě různé věci: kontejner existuje, nebo služba skutečně plní svůj účel. Důležitá je pouze druhá možnost. Ověřením je vytvoření poznámky, její současná úprava ve dvou prohlížečích, nahrání obrázku a autentizace přes vybraného poskytovatele.

HedgeDoc slouží k tomuto účelu: ke společné práci na Markdown poznámkách v reálném čase. Nasazení musí zachovat všechny součásti, které toto chování zajišťují; port, volume a certifikát jsou vstupy, nikoli výsledek.

Zálohujte stav, který HedgeDoc nedokáže znovu vytvořit

Definujte pro HedgeDoc požadovaný bod obnovy a dobu obnovy s ohledem na databázi, nahrané soubory a konfiguraci autentizace. Před bootstrapem připojte /hedgedoc/public/uploads, zapište neškodná testovací data a nahraďte kontejner, abyste ověřili, že je tato cesta skutečně persistentní. Named volume řeší zachování dat při redeployi, neřeší však kompromitaci ani ztrátu serveru.

Připravte čisté prostředí pro obnovu, použijte stejnou zamčenou verzi aplikace a ověřte, že se vrátí poznámky, revize, uživatelé i nahrané soubory a že dva prohlížeče mohou spolupracovat na obnovené poznámce. Zaznamenejte příkazy, opravy vlastníka a uplynulý čas. Příručka k zálohování představuje užitečný standard: záloze lze důvěřovat až po obnově, nikoli po nahrání.

Oddělte HedgeDoc od jeho závislostí

Stav procesu a stav produktu jsou u HedgeDocu dvě odlišné věci. Port 3000 může odpovídat, přesto může transakce z pohledu uživatele stále selhávat. Síťový kontrakt HedgeDocu tvoří Postgres a volitelní poskytovatelé OAuth a SMTP. Soukromé endpointy ponechte v interním DNS, povolte pouze potřebná odchozí spojení a přidělte HedgeDocu omezené oprávnění servisního účtu.

Tuto kontrolu připravenosti použijte po významných změnách konfigurace: vytvořte poznámku, upravte ji současně ve dvou prohlížečích, nahrajte obrázek a autentizujte se přes vybraného poskytovatele. Nákladné externí kontroly nepřidávejte do liveness probes, aby výpadek poskytovatele nezpůsobil restartovací smyčku. Při plánování kapacity sledujte WebSocket connections, zápisy do databáze, nahraná média a historii dokumentů; ty lépe vystihují skutečné zatížení HedgeDocu než požadavky na stránky.

Pět kontrol důkladnějších než stav kontejneru

Převeďte smoke test HedgeDocu na opakovatelný release příkaz nebo stručný runbook. Jeho výstup musí prokázat tento výsledek: vytvoření poznámky, její současnou úpravu ve dvou prohlížečích, nahrání obrázku a autentizaci přes vybraného poskytovatele. K výsledku zaznamenejte verzi aplikace, digest kontejneru, hostname routy a identifikátor testovacích dat.

Stejnou kontrolu spusťte po běžné výměně kontejneru i po obnově databáze, nahraných souborů a konfigurace autentizace na jiném místě. Obnova byla úspěšná, pokud se vrátí poznámky, revize, uživatelé i nahrané soubory a dva prohlížeče mohou spolupracovat na obnovené poznámce. Porovnejte časování a spotřebu související s WebSocket connections, zápisy do databáze, nahranými médii a historií dokumentů; výrazná změna stojí za prošetření, i když poslední akce stále projde.

Poté vyzkoušejte bezpečné selhání: dočasně odeberte testovací identitě přístup k Postgresu a volitelným poskytovatelům OAuth a SMTP. Ověřte, že HedgeDoc chybu zobrazí a vrátí se do normálního stavu bez destruktivních ručních úprav. Uchovejte pouze nezbytný, redigovaný výňatek z logu. Tato čtyřdílná kontrola pokrývá spuštění, persistenci, obnovu a zpracování selhání.

Spusťte HedgeDoc, aniž byste skryli důležité součásti

Minimální příkaz je užitečný, pokud odhalí, co bude platforma později spravovat.

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

Port 3000 zde zůstává privátní pro hostitele a každá potřebná cesta je uvedena explicitně. Přidejte ověřené connection settings pro Postgres a volitelné poskytovatele OAuth a SMTP; pro privátní služby používejte privátní názvy. Spuštění ověřte pomocí logů i kontroly specifické pro aplikaci: vytvořte poznámku, upravte ji současně ve dvou prohlížečích, nahrajte obrázek a autentizujte se přes vybraného poskytovatele. Po ověření image version zamkněte, aby běžná výměna kontejneru potají nezměnila chování.

Nedávejte HedgeDocu celý hostitel

U HedgeDocu není cennou částí surface nutně landing page. Nejčastější chybou je použití ukázkového session secretu nebo neúmyslné povolení anonymního vytváření poznámek. Této chybě předcházejte záměrně: použijte stabilní session secret, rozhodněte, zda je anonymní vytváření poznámek přijatelné, a omezte přístup k privátním poznámkám.

CMD_SESSION_SECRET vygenerujte jako dlouhou náhodnou hodnotu; její běžná rotace zneplatní sessions nebo tokeny, proto si naplánujte dopad na uživatele a nenazývejte ji migrací šifrování. Pokud to image podporuje, použijte neprivilegovaného uživatele kontejneru a nepřipojujte nesouvisející credentials. Na ingressu nastavte limity rychlosti nebo velikosti tam, kde může nedůvěryhodná práce spotřebovávat WebSocket connections, zápisy do databáze, nahraná média a historii dokumentů.

Otestujte HedgeDoc z vnější sítě

Finální hostname HedgeDocu zvolte ještě předtím, než si uživatelé uloží callbacky nebo nastavení klienta, a poté nastavte CMD_DOMAIN a CMD_PROTOCOL_USESSL pro veřejnou URL. Platform route by měla ukončit TLS jednou a směrovat na privátní port 3000.

Acceptance transaction spusťte externě. Pokud se klient k HedgeDocu nikdy nepřipojí, použijte checklist pro ověření SSL určený ke kontrolám DNS a certifikátu. Pokud požadavek dorazí k HedgeDocu, ale úpravy v reálném čase selhávají kvůli nesprávnému nastavení WebSockets nebo domény, přestaňte měnit proxy redirects a zkontrolujte hranici specifickou pro aplikaci.

Provozujte HedgeDoc s ohledem na skutečné úzké hrdlo

Po každém nasazení použijte jako smoke test HedgeDocu vytvoření poznámky, její současnou úpravu ve dvou prohlížečích, nahrání obrázku a autentizaci přes vybraného poskytovatele. Související metriky tvoří WebSocket connections, zápisy do databáze, nahraná média a historie dokumentů; upozornění nastavte tam, kde se tyto zdroje blíží bodu, v němž zhorší uživatelskou akci.

Hlavní riziko změn spočívá v tom, že migrace databáze HedgeDocu, nastavení OAuth a změny pluginů nebo rendereru vyžadují staged release. Bezpečný release začíná obnovitelným snapshotem a před přesunem provozu ověří každou jednosměrnou změnu stavu. Když úpravy v reálném čase selhávají kvůli nesprávnému nastavení WebSockets nebo domény, ponechte vadný kontejner dostatečně dlouho spuštěný, abyste mohli přečíst jeho konfiguraci a první chybu.

Kde Dockup odstraňuje práci s HedgeDocem

Dockup může převzít nahraditelné části platformy: směrovat provoz na port 3000, vystavit doménu a certifikát, vkládat secrets, připojit persistentní storage a propojit HedgeDoc se spravovanými nebo privátně připojenými službami. Může to provést na infrastruktuře Dockupu nebo na serveru, který připojíte.

Acceptance práce pro HedgeDoc zůstává explicitní. Po one-click nasazení nastavte CMD_DOMAIN a CMD_PROTOCOL_USESSL pro veřejnou URL, připojte a otestujte Postgres a volitelné poskytovatele OAuth a SMTP a spusťte tento scénář: vytvořte poznámku, upravte ji současně ve dvou prohlížečích, nahrajte obrázek a autentizujte se přes vybraného poskytovatele. Toto rozdělení je záměrné: Dockup odstraňuje opakované nastavování infrastruktury, aniž by předstíral, že role aplikace, credentials poskytovatelů nebo pravidla obnovy se nastaví samy.

Často kladené otázky

Co HedgeDoc potřebuje pro produkční nasazení?

Směrujte kontejner HedgeDocu na portu 3000 přes jeden HTTPS origin. Síťový požadavek tvoří Postgres a volitelní poskytovatelé OAuth a SMTP. HedgeDoc nepovažujte za připravený, dokud nemůžete vytvořit poznámku, upravit ji současně ve dvou prohlížečích, nahrát obrázek a autentizovat se přes vybraného poskytovatele.

Která data HedgeDocu patří do zálohy?

Zachovejte /hedgedoc/public/uploads a do stejného manifestu obnovy zahrňte databázi, nahrané soubory a konfiguraci autentizace. Čistá obnova HedgeDocu je úspěšná pouze tehdy, když se vrátí poznámky, revize, uživatelé i nahrané soubory a dva prohlížeče mohou spolupracovat na obnovené poznámce.

Vyžaduje HedgeDoc HTTPS za reverse proxy?

Pro veřejný origin HedgeDocu použijte HTTPS a port 3000 ponechte na interní routě. Nastavení HedgeDocu aplikujte správně: nastavte CMD_DOMAIN a CMD_PROTOCOL_USESSL pro veřejnou URL. U HedgeDocu HTTPS chrání credentials nebo obsah uživatelů při přenosu a udržuje konzistentní chování klienta závislé na originu.

Jak testovat upgrade HedgeDocu?

Obnovte aktuální stav HedgeDocu do izolovaného nasazení, aplikujte kandidátní verzi a zopakujte jeho acceptance transaction. Věnujte tomu zvláštní pozornost, protože migrace databáze HedgeDocu, nastavení OAuth a změny pluginů nebo rendereru vyžadují staged release. Předchozí HedgeDoc image si ponechte, dokud nebudete rozumět hranici migrace dat a rollbacku.