Come fare self-hosting di HedgeDoc nel 2026: WebSocket, OAuth e file caricati

Esistono due versioni del “mettere in esecuzione HedgeDoc”: il container esiste oppure il servizio svolge effettivamente il proprio lavoro. Solo la seconda è importante. In questo caso, la verifica consiste nel creare una nota, modificarla contemporaneamente da due browser, caricare un'immagine e autenticarsi tramite il provider selezionato.

HedgeDoc è progettato proprio per questo: note Markdown collaborative in tempo reale. Il deployment deve preservare gli elementi alla base di questo comportamento; una porta, un volume e un certificato sono prerequisiti, non il risultato.

Esegui il backup dello stato che HedgeDoc non può ricreare

Definisci il recovery point e il recovery time di HedgeDoc in relazione al database, ai file caricati e alla configurazione dell'autenticazione. Monta /hedgedoc/public/uploads prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per verificare che il percorso sia effettivamente persistente. Un volume denominato risolve la persistenza durante i redeploy; non risolve un compromesso o la perdita del server.

Prepara un ambiente di ripristino pulito, usa la stessa versione applicativa fissata e verifica che note, revisioni, utenti e file caricati vengano ripristinati e che due browser possano collaborare sulla nota recuperata. Documenta i comandi, le correzioni dei permessi e il tempo trascorso. La guida ai backup è uno standard utile: un backup è affidabile dopo il ripristino, non dopo il caricamento.

Separa HedgeDoc dalle sue dipendenze

Per HedgeDoc, lo stato del processo e quello del prodotto sono due aspetti distinti. La porta 3000 può rispondere mentre la transazione lato utente continua a non funzionare. Il contratto di rete di HedgeDoc prevede Postgres, oltre a provider OAuth e SMTP opzionali. Mantieni gli endpoint privati su DNS interno, consenti solo le chiamate in uscita necessarie e assegna a HedgeDoc credenziali di servizio con scope limitato.

Usa questa procedura di readiness dopo modifiche significative alla configurazione: crea una nota, modificala contemporaneamente da due browser, carica un'immagine e autenticati tramite il provider selezionato. Evita controlli esterni costosi nelle probe di liveness, così un'interruzione del provider non causerà un restart loop. Il capacity planning dovrebbe monitorare le connessioni WebSocket, le scritture sul database, i contenuti multimediali caricati e la cronologia dei documenti: questi indicatori riflettono meglio la pressione reale su HedgeDoc rispetto alle richieste delle pagine.

Cinque controlli più affidabili dell'health check del container

Trasforma lo smoke test di HedgeDoc in un comando di release ripetibile o in una breve runbook. Il suo output deve dimostrare questo risultato: crea una nota, modificala contemporaneamente da due browser, carica un'immagine e autenticati tramite il provider selezionato. Registra insieme al risultato la versione dell'applicazione, il digest del container, l'hostname della route e l'identificativo dei dati di test.

Esegui lo stesso controllo dopo la sostituzione ordinaria del container e dopo aver ripristinato altrove il database, i file caricati e la configurazione dell'autenticazione. Il ripristino è riuscito quando note, revisioni, utenti e file caricati tornano disponibili e due browser possono collaborare sulla nota recuperata. Confronta tempi e consumi relativi alle connessioni WebSocket, alle scritture sul database, ai contenuti multimediali caricati e alla cronologia dei documenti; una variazione significativa merita un'analisi anche quando l'azione finale continua ad avere esito positivo.

Poi simula un errore sicuro: nega temporaneamente all'identità di test l'accesso a Postgres, oltre che ai provider OAuth e SMTP opzionali. Verifica che HedgeDoc mostri il problema e torni alla normalità senza modifiche manuali distruttive. Conserva solo l'estratto di log necessario, dopo averlo anonimizzato. Questo controllo in quattro parti copre avvio, persistenza, ripristino e gestione degli errori.

Avvia HedgeDoc senza nascondere i componenti in movimento

Un comando minimale è utile quando mostra ciò che la piattaforma gestirà in seguito.

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

Qui la porta 3000 rimane privata sull'host e ogni percorso necessario è esplicito. Aggiungi le impostazioni di connessione verificate per Postgres, oltre ai provider OAuth e SMTP opzionali; usa nomi privati per i servizi privati. Verifica l'avvio sia tramite i log sia con la verifica specifica dell'applicazione: crea una nota, modificala contemporaneamente da due browser, carica un'immagine e autenticati tramite il provider selezionato. Dopo la verifica, blocca la versione dell'immagine per evitare che una sostituzione ordinaria modifichi il comportamento senza preavviso.

Non concedere a HedgeDoc l'accesso all'intero host

Per HedgeDoc, la superficie più importante non coincide necessariamente con la landing page. L'errore principale consiste nell'usare un session secret di esempio o nel consentire involontariamente la creazione anonima di note. Contrastalo intenzionalmente: usa un session secret stabile, decidi se la creazione anonima di note è accettabile e limita l'accesso alle note private.

Genera CMD_SESSION_SECRET come valore lungo e casuale; in genere la sua rotazione invalida sessioni o token, quindi pianifica l'impatto sugli utenti invece di considerarla una migrazione della cifratura. Usa un utente non privilegiato nel container quando l'immagine lo supporta e non montare credenziali non pertinenti. Applica limiti di frequenza o dimensione all'ingress, dove il lavoro non attendibile può consumare connessioni WebSocket, scritture sul database, contenuti multimediali caricati e cronologia dei documenti.

Testa HedgeDoc dall'esterno del server

Scegli l'hostname definitivo di HedgeDoc prima che gli utenti salvino callback o impostazioni client, quindi configura CMD_DOMAIN e CMD_PROTOCOL_USESSL per l'URL pubblico. La route della piattaforma dovrebbe terminare TLS una sola volta e indirizzare alla porta privata 3000.

Esegui la transazione di acceptance dall'esterno. Se il client non raggiunge mai HedgeDoc, usa la checklist di validazione SSL per i controlli DNS e del certificato. Se la richiesta raggiunge HedgeDoc ma le modifiche in tempo reale non funzionano perché i WebSocket o le impostazioni del dominio sono errati, smetti di modificare i redirect del proxy e analizza invece il confine specifico dell'applicazione.

Gestisci HedgeDoc in base al suo vero collo di bottiglia

Usa la procedura “crea una nota, modificala contemporaneamente da due browser, carica un'immagine e autenticati tramite il provider selezionato” come smoke test di HedgeDoc dopo ogni deployment. Le metriche di supporto sono le connessioni WebSocket, le scritture sul database, i contenuti multimediali caricati e la cronologia dei documenti; configura gli alert quando queste risorse si avvicinano a un livello in grado di compromettere l'azione dell'utente.

Il principale rischio di modifica è che le migrazioni del database di HedgeDoc, le impostazioni OAuth e i cambiamenti a plugin o renderer richiedano una release graduale. Una release sicura parte da uno snapshot ripristinabile e valida qualsiasi modifica di stato unidirezionale prima di spostare il traffico. Quando le modifiche in tempo reale non funzionano perché i WebSocket o le impostazioni del dominio sono errati, conserva il container difettoso abbastanza a lungo da leggerne la configurazione e il primo errore.

Dove Dockup riduce il lavoro per HedgeDoc

Dockup può gestire i componenti sostituibili della piattaforma: instradare il traffico verso la porta 3000, emettere il dominio e il certificato, iniettare i secret, collegare lo storage persistente e connettere HedgeDoc a servizi gestiti o collegati privatamente. Può farlo sull'infrastruttura Dockup o su un server che colleghi.

La verifica di acceptance di HedgeDoc rimane esplicita. Dopo il deployment one-click, configura CMD_DOMAIN e CMD_PROTOCOL_USESSL per l'URL pubblico, collega e testa Postgres, oltre ai provider OAuth e SMTP opzionali, quindi esegui questo scenario: crea una nota, modificala contemporaneamente da due browser, carica un'immagine e autenticati tramite il provider selezionato. Questa suddivisione è intenzionale: Dockup elimina la configurazione ripetitiva dell'infrastruttura senza fingere che ruoli applicativi, credenziali dei provider o policy di ripristino si scelgano da soli.

Domande frequenti

Di cosa ha bisogno HedgeDoc per un deployment in produzione?

Instrada il container HedgeDoc sulla porta 3000 attraverso un'unica origine HTTPS. Il requisito di rete aggiuntivo è Postgres, oltre ai provider OAuth e SMTP opzionali. Non considerare HedgeDoc pronto finché non puoi creare una nota, modificarla contemporaneamente da due browser, caricare un'immagine e autenticarti tramite il provider selezionato.

Quali dati di HedgeDoc devono essere inclusi in un backup?

Rendi persistente /hedgedoc/public/uploads e includi database, file caricati e configurazione dell'autenticazione nello stesso manifest di ripristino. Un ripristino pulito di HedgeDoc è riuscito solo quando note, revisioni, utenti e file caricati tornano disponibili e due browser possono collaborare sulla nota recuperata.

HedgeDoc richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di HedgeDoc e mantieni la porta 3000 sulla route interna. Applica correttamente l'impostazione di HedgeDoc: configura CMD_DOMAIN e CMD_PROTOCOL_USESSL per l'URL pubblico. Per HedgeDoc, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento client sensibile all'origine.

Come si deve testare un upgrade di HedgeDoc?

Ripristina lo stato corrente di HedgeDoc in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di acceptance. Presta particolare attenzione perché le migrazioni del database di HedgeDoc, le impostazioni OAuth e i cambiamenti a plugin o renderer richiedono una release graduale. Conserva l'immagine precedente di HedgeDoc finché non avrai compreso i confini della migrazione dei dati e del rollback.