Come eseguire il self-hosting di Etherpad nel 2026: pad, plugin e backup del database

Se hai già provato a eseguire il self-hosting di Etherpad, probabilmente conosci bene questa situazione frustrante: l'interfaccia compare, ma le sessioni si disconnettono perché i timeout del proxy sono troppo brevi. Ricreare il container risolve raramente un'incompatibilità tra URL, stato e dipendenze.

Questa procedura utilizza un unico criterio concreto di completamento: aprire un pad in due browser, modificarlo contemporaneamente, esaminare le revisioni ed esportare il risultato nel formato richiesto. Ogni scelta di configurazione viene valutata rispetto a questo criterio, non in base alla presenza di un badge verde del container.

Scegli la topologia Etherpad più semplice che funziona

La topologia Etherpad più semplice e responsabile comprende un unico listener privato sulla porta 9001, una route di ingress e un confine di stato documentato. Il contratto di rete per Etherpad prevede Postgres o un altro database supportato per un uso multiutente persistente. Mantieni gli endpoint privati sul DNS interno, autorizza solo le chiamate in uscita necessarie e assegna a Etherpad una credenziale di servizio con ambito limitato.

Valida la topologia chiedendo a un client pulito di aprire un pad in due browser, modificarlo contemporaneamente, esaminare le revisioni ed esportare il risultato nel formato richiesto. Durante l'esecuzione, monitora le sessioni WebSocket, il conteggio delle revisioni, le scritture sul database e l'esecuzione dei plugin. Il risultato indica se il miglioramento successivo deve riguardare memoria, storage, rete o un worker separato, invece di incoraggiare un dimensionamento arbitrario del container.

Crea un container Etherpad sostituibile

Usa il container come runtime sostituibile, non come fonte dei dati.

docker run -d \
  --name etherpad \
  --restart unless-stopped \
  -p 127.0.0.1:9001:9001 \
  -v etherpad-data:/opt/etherpad-lite/var \
  -e ADMIN_PASSWORD=replace-with-a-long-random-value \
  etherpad/etherpad:latest

Aggiungi le impostazioni di connessione verificate per Postgres o un altro database supportato per un uso multiutente persistente; usa nomi privati per i servizi privati. Controlla l'utente del container, i percorsi scrivibili e il listener associato prima di esporlo. Esegui l'azione completa — aprire un pad in due browser, modificarlo contemporaneamente, esaminare le revisioni ed esportare il risultato nel formato richiesto — e salva il riferimento esatto all'immagine che ha prodotto il risultato.

Evita che il successo del proxy nasconda un problema dell'applicazione

Browser, client API ed Etherpad devono concordare su un'unica origin. Per ottenere questo risultato, imposta l'URL pubblico e il supporto WebSocket del proxy. Mantieni l'host e il protocollo originali, lasciando però la porta 9001 non disponibile come indirizzo pubblico alternativo.

La guida alla risoluzione dei problemi dei siti non raggiungibili aiuta a distinguere una route irraggiungibile da un'applicazione che risponde. Questa distinzione è importante: le sessioni si disconnettono perché i timeout del proxy sono troppo brevi. Solo il primo problema si risolve modificando l'ingress; il secondo richiede l'analisi dei log di Etherpad, dello stato o del carico di lavoro.

Progetta il ripristino di Etherpad prima del lancio

Proteggi lo stato di Etherpad prima di ottimizzare il container. L'insieme necessario comprende database, plugin caricati e impostazioni. Monta /opt/etherpad-lite/var prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso è effettivamente persistente. Se più storage devono rimanere coerenti, documenta l'ordine in cui mettere in pausa le scritture ed eseguire i backup.

Conserva copie al di fuori del server di deployment e cifra il materiale che contiene credenziali o contenuti privati. Il ripristino ha esito positivo quando pad, autori, revisioni e plugin vengono recuperati e le modifiche concorrenti continuano a convergere. La differenza tra un mount persistente e una copia indipendente è trattata in storage persistente e snapshot.

Scegli il confine di attendibilità di Etherpad

Chiudi la finestra di bootstrap non appena esiste il primo amministratore affidabile. Il problema concreto di Etherpad consiste nel distribuire una password amministratore nota o nel lasciare i pad scrivibili da chiunque; il confine più sicuro consiste nell'impostare una password amministratore reale, decidere chi può creare pad e non presumere che un URL di pad difficile da indovinare sia privato.

Sostituisci immediatamente l'ADMIN_PASSWORD di esempio, conservala al di fuori dell'immagine e ruotala come una credenziale amministrativa se viene esposta. La rete privata dovrebbe trasportare le credenziali delle dipendenze, mentre i ruoli all'interno di Etherpad dovrebbero concedere l'azione utile minima. Evita di inserire nei log ordinari i body delle richieste sensibili e le risposte dei provider.

Aggiorna Etherpad senza procedere per tentativi

Osserva le attività eseguite da Etherpad: sessioni WebSocket, conteggio delle revisioni, scritture sul database ed esecuzione dei plugin. Imposta i limiti lasciando margine per queste attività ed evita un liveness probe che entri in competizione con esse. Il controllo dell'operatore dovrebbe comunque tentare, secondo una pianificazione, di aprire un pad in due browser, modificarlo contemporaneamente, esaminare le revisioni ed esportare il risultato nel formato richiesto.

Per gli aggiornamenti, ricorda che versioni dei plugin Etherpad, sintassi delle impostazioni e migrazioni del database devono essere testate insieme. Esegui il deployment del candidato su una copia ripristinata e ripeti il test noto. Se le sessioni si disconnettono perché i timeout del proxy sono troppo brevi, usa i log di runtime e la richiesta di rete effettiva per individuare quale ipotesi è cambiata.

Cosa deve superare i controlli prima che arrivino dati Etherpad reali

Per Etherpad, definisci una transazione di riferimento funzionante prima del lancio: aprire un pad in due browser, modificarlo contemporaneamente, esaminare le revisioni ed esportare il risultato nel formato richiesto. Inserisci in version control i prerequisiti, la risposta prevista e i passaggi di pulizia, senza valori segreti. Fissa l'immagine utilizzata per stabilire questo riferimento.

Usa la transazione per validare una sostituzione e un ripristino indipendente. Il servizio ripristinato è accettabile solo quando pad, autori, revisioni e plugin vengono recuperati e le modifiche concorrenti continuano a convergere. Allo stesso tempo, osserva le sessioni WebSocket, il conteggio delle revisioni, le scritture sul database e l'esecuzione dei plugin, trasformando la parte più lenta o più vincolata in un alert a livello di servizio.

Il gate deve includere anche un caso negativo: nega temporaneamente all'identità di test l'accesso a Postgres o a un altro database supportato per un uso multiutente persistente. Verifica che Etherpad produca un errore utile mantenendo integri i dati, ripristina la condizione valida e ripeti la transazione di riferimento funzionante. Conservare entrambi i risultati impedisce che un endpoint di health superficiale diventi l'unica prova disponibile in produzione.

Esegui il deployment di Etherpad su Dockup senza perdere i suoi confini

Per Etherpad, Dockup è particolarmente utile al confine tra un'immagine e un servizio persistente. Mantiene associati la route verso la porta 9001, TLS, i valori segreti e lo storage durante le sostituzioni dei container, indipendentemente dal fatto che il compute appartenga a Dockup o al tuo server collegato.

Concludi con la conoscenza dell'applicazione: imposta l'URL pubblico e il supporto WebSocket del proxy; connetti e testa Postgres o un altro database supportato per un uso multiutente persistente; quindi esegui questa verifica: aprire un pad in due browser, modificarlo contemporaneamente, esaminare le revisioni ed esportare il risultato nel formato richiesto. Conserva il risultato come controllo del deployment, così il successivo aggiornamento dell'immagine verrà valutato in base al comportamento e non allo stato del container.

Domande frequenti

Di cosa ha bisogno Etherpad per un deployment in produzione?

Instrada il container Etherpad sulla porta 9001 attraverso un'unica origin HTTPS. Il requisito di rete di supporto è Postgres o un altro database supportato per un uso multiutente persistente. Non considerare Etherpad pronto finché non puoi aprire un pad in due browser, modificarlo contemporaneamente, esaminare le revisioni ed esportare il risultato nel formato richiesto.

Quali dati di Etherpad devono essere inclusi in un backup?

Rendi persistente /opt/etherpad-lite/var e includi database, plugin caricati e impostazioni nello stesso manifest di ripristino. Un ripristino pulito di Etherpad supera il controllo solo quando pad, autori, revisioni e plugin vengono recuperati e le modifiche concorrenti continuano a convergere.

Etherpad richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origin pubblico di Etherpad e mantieni la porta 9001 sulla route interna. Applica correttamente l'impostazione di Etherpad: configura l'URL pubblico e il supporto WebSocket del proxy. Per Etherpad, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origin.

Come deve essere testato un aggiornamento di Etherpad?

Ripristina lo stato attuale di Etherpad in un deployment isolato, applica la versione candidata e ripeti la transazione di accettazione. Presta particolare attenzione, perché versioni dei plugin Etherpad, sintassi delle impostazioni e migrazioni del database devono essere testate insieme. Conserva l'immagine Etherpad precedente finché non sono chiari i confini della migrazione dei dati e del rollback.