Come eseguire il self-hosting di Excalidraw nel 2026: collaborazione, TLS e confini dei dati

Se hai già provato a eseguire Excalidraw in self-hosting, probabilmente conosci bene questa situazione frustrante: l'interfaccia viene visualizzata, ma la collaborazione non funziona perché il suo endpoint WebSocket è errato. Ricreare il container risolve raramente un'incompatibilità tra URL, stato e dipendenze.

Questa guida utilizza un unico criterio concreto di completamento: disegnare ed esportare un diagramma, condividere un link di collaborazione tramite il room service configurato e riconnettere un secondo browser. Ogni scelta di configurazione viene valutata rispetto a questo criterio, non in base a un badge verde del container.

Ripristinare Excalidraw su un host vuoto

Per il deployment di base di Excalidraw, il livello container è usa e getta e non è richiesto alcun volume dati. Il manifest di ripristino non contiene dati del server nell'immagine di base; esegui il backup di qualsiasi servizio di collaborazione separato. Mantieni sotto controllo delle modifiche il digest dell'immagine, la configurazione e tutti gli asset gestiti separatamente.

Elimina e ricrea il servizio in un ambiente pulito, quindi verifica che il client venga ricostruito a partire dall'immagine fissata e che il room service separato ripristini qualsiasi stato di collaborazione che promette di conservare. La guida dal repository Git al deployment in produzione è il modello pertinente: ricostruisci l'artefatto ed esegui il backup solo dello stato esterno che esiste realmente.

Non definire persistente una directory se Excalidraw non vi scrive dati significativi. Mount vuoti o inutilizzati creano un falso senso di sicurezza e inducono gli operatori successivi a cercare lo stato nel posto sbagliato.

Mappare Excalidraw prima di intervenire su Docker

Il processo HTTP di Excalidraw è in ascolto sulla porta 80; mantieni quella porta sulla rete dell'applicazione e pubblica solo la route della piattaforma. Il requisito runtime locale è costituito da un room server separato e da un livello di storage per la collaborazione persistente. Mantieni esplicito il suo ciclo di vita, così spostare Excalidraw tra host non modifica il comportamento senza che nessuno se ne accorga.

Metti per iscritto il confine sotto forma di un breve contratto: chi è responsabile del requisito, quale credenziale viene utilizzata, quale timeout è accettabile e come viene visualizzato l'errore. Esegui quindi questa transazione: disegna ed esporta un diagramma, condividi un link di collaborazione tramite il room service configurato e riconnetti un secondo browser. Durante l'esecuzione osserva la distribuzione degli asset statici per l'immagine di base, mentre le connessioni WebSocket e lo stato delle room appartengono al servizio di collaborazione separato, perché questo carico di lavoro fornisce una dimensione iniziale più utile rispetto a un container inattivo.

Un test di accettazione in produzione per Excalidraw

Un release candidate di Excalidraw si guadagna il traffico completando uno scenario fisso: disegnare ed esportare un diagramma, condividere un link di collaborazione tramite il room service configurato e riconnettere un secondo browser. Acquisisci il digest dell'immagine, la configurazione effettiva non segreta, l'origine pubblica e i timestamp relativi a quello scenario. I dati di test devono essere usa e getta, ma abbastanza realistici da esercitare lo stesso percorso degli utenti.

Esegui il test dopo aver sostituito il runtime, quindi ricostruisci il servizio senza dati del server nell'immagine di base; esegui il backup di qualsiasi servizio di collaborazione separato. Il ripristino ha esito positivo quando il client viene ricostruito a partire dall'immagine fissata e il room service separato ripristina qualsiasi stato di collaborazione che promette di conservare. Confronta le misurazioni delle risorse per la distribuzione degli asset statici dell'immagine di base, mentre le connessioni WebSocket e lo stato delle room appartengono al servizio di collaborazione separato, con la release precedente e analizza ogni variazione significativa prima della promozione.

Infine, esegui questo test di errore controllato: invia un input innocuo vicino al limite di risorse o di formato associato a questo confine: l'interfaccia viene caricata, ma la collaborazione non funziona perché il suo endpoint WebSocket è errato. Verifica che Excalidraw spieghi l'errore, non danneggi lo stato esistente e riprenda a funzionare quando la condizione valida viene ripristinata. Salva un estratto del log redatto e il tempo di ripristino. Nel complesso, questi controlli coprono comportamento, durabilità e operatività, non soltanto l'uptime del processo.

Trasformare il comando locale in un servizio ispezionabile

Un avvio con caratteristiche da produzione è volutamente noioso: stato nominato, porta esplicita e nessun segreto nell'immagine.

docker run -d \
  --name excalidraw \
  --restart unless-stopped \
  -p 127.0.0.1:80:80 \
  excalidraw/excalidraw:latest

L'esempio è una baseline, non uno stack di supporto completo. Conferma il requisito locale prima dell'esposizione: un room server separato e un livello di storage per la collaborazione persistente. Controlla i mount effettivi e il listener, quindi prova a disegnare ed esportare un diagramma, condividere un link di collaborazione tramite il room service configurato e riconnettere un secondo browser. Fissa l'immagine funzionante prima del riavvio successivo.

Decisioni di sicurezza specifiche per Excalidraw

Con Excalidraw, la rotazione degli account non è l'attività di hardening principale, perché l'immagine standard non dispone di un account store. Concentrati sull'evitare di presumere che la sola immagine statica fornisca uno storage persistente per le room condivise; proteggi le room di collaborazione private e non dichiarare persistente la collaborazione quando è stata eseguita solo l'immagine web di Excalidraw.

Usa HTTPS, l'autenticazione opzionale della piattaforma e un digest dell'immagine verificato. Non montare dati dell'host non correlati e limita il carico rappresentato dalla distribuzione degli asset statici dell'immagine di base, mentre le connessioni WebSocket e lo stato delle room appartengono al servizio di collaborazione separato. Un client esterno pulito dovrebbe visualizzare la build prevista, mentre un client non autorizzato dovrebbe essere rifiutato prima di raggiungere il container quando l'accesso è limitato.

Instradare Excalidraw senza dichiarare il falso su HTTPS

L'emissione del certificato TLS è solo metà della route di Excalidraw. Servi il client tramite HTTPS e configura separatamente gli endpoint di collaborazione. Invia il traffico internamente alla porta 80 e inoltra lo schema esterno, così gli URL generati e i cookie sicuri rimangono coerenti.

Esegui lo scenario completo di Excalidraw da una rete pulita, non limitarti alla pagina root. Un errore 502 o un errore del certificato può essere isolato con la configurazione automatica del dominio e del TLS. Se il traffico raggiunge il processo e l'interfaccia viene caricata, ma la collaborazione non funziona perché il suo endpoint WebSocket è errato, diagnostica la condizione nel punto in cui si verifica invece di aggiungere ulteriori redirect.

Aggiornare Excalidraw senza procedere per tentativi

L'indicatore di servizio utile per Excalidraw è il completamento corretto di “disegnare ed esportare un diagramma, condividere un link di collaborazione tramite il room service configurato e riconnettere un secondo browser”. Associa questo risultato alla distribuzione degli asset statici dell'immagine di base, mentre le connessioni WebSocket e lo stato delle room appartengono al servizio di collaborazione separato; una pagina root visualizzata correttamente non dice nulla sulla compatibilità dell'output o sull'esaurimento delle risorse.

Prima di sostituire l'immagine, considera questo rischio: le versioni di frontend, room server e storage devono essere testate insieme, invece di presumere che il client statico sia proprietario dei dati condivisi. Testa input rappresentativi e input ai limiti su entrambe le versioni e conserva il digest precedente finché il candidato non supera i test. Se l'interfaccia viene caricata, ma la collaborazione non funziona perché il suo endpoint WebSocket è errato, analizza il formato della richiesta, il comportamento del client e i log del runtime prima di modificare le impostazioni di route o storage.

Usare Dockup per il livello della piattaforma

Un template Excalidraw one-click dovrebbe codificare il digest dell'immagine, la porta 80, le tempistiche dell'health check, il dominio e il TLS. Poiché il servizio di base è stateless, Dockup può ricrearlo direttamente sul compute di Dockup o su una macchina collegata, senza fingere che un volume vuoto sia un backup.

Dopo l'avvio, servi il client tramite HTTPS e configura separatamente gli endpoint di collaborazione. Dockup dovrebbe conservare le impostazioni runtime di Excalidraw, mentre l'operatore conferma questo requisito locale: un room server separato e un livello di storage per la collaborazione persistente. Verifica questo risultato: disegna ed esporta un diagramma, condividi un link di collaborazione tramite il room service configurato e riconnetti un secondo browser. Qualsiasi estensione stateful successiva deve dichiarare il proprio mount, secret e test di ripristino, senza modificare in modo implicito il significato del template di base.

Domande frequenti

Di cosa ha bisogno Excalidraw per un deployment in produzione?

Instrada il container Excalidraw sulla porta 80 attraverso un'unica origine HTTPS. Il requisito runtime locale è costituito da un room server separato e da un livello di storage per la collaborazione persistente. Non considerare Excalidraw pronto finché non puoi disegnare ed esportare un diagramma, condividere un link di collaborazione tramite il room service configurato e riconnettere un secondo browser.

Quali dati di Excalidraw devono essere inclusi in un backup?

L'immagine standard di Excalidraw non richiede alcun mount per i dati dell'applicazione. Conserva la configurazione del deployment ed esegui separatamente il backup di qualsiasi stato collegato; il ripristino ha esito positivo quando il client viene ricostruito a partire dall'immagine fissata e il room service separato ripristina qualsiasi stato di collaborazione che promette di conservare.

Excalidraw richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Excalidraw e mantieni la porta 80 sulla route interna. Applica correttamente l'impostazione di Excalidraw: servi il client tramite HTTPS e configura separatamente gli endpoint di collaborazione. Per Excalidraw, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origine.

Come deve essere testato un aggiornamento di Excalidraw?

Esegui il deployment dell'immagine candidata di Excalidraw accanto a quella corrente e ripeti la transazione di accettazione con input noti. Presta particolare attenzione, perché le versioni di frontend, room server e storage devono essere testate insieme, invece di presumere che il client statico sia proprietario dei dati condivisi. Il container standard non prevede migrazioni dei dati, quindi conserva il digest precedente finché i controlli sull'output e sulla compatibilità non hanno dato esito positivo.