Como fazer self-hosting do Excalidraw em 2026: colaboração, TLS e limites de dados

Se você já tentou fazer self-hosting do Excalidraw, provavelmente conhece este estado frustrante: a interface aparece, mas a colaboração falha porque o endpoint WebSocket está incorreto. Recriar o container raramente resolve uma divergência entre URLs, estado e dependências.

Este guia usa um critério concreto de conclusão: desenhar e exportar um diagrama, compartilhar um link de colaboração pelo room service configurado e reconectar um segundo navegador. Cada escolha de configuração é avaliada com base nesse critério, e não apenas em um indicador verde do container.

Restaurar o Excalidraw em um host vazio

Na implantação básica do Excalidraw, a camada do container é descartável e não é necessário nenhum volume de dados. No recovery manifest, não há dados de servidor na imagem básica; faça backup de qualquer serviço de colaboração separado. Mantenha o digest da imagem, a configuração e quaisquer assets mantidos separadamente sob controle de mudanças.

Exclua e recrie o serviço em um ambiente limpo. Em seguida, comprove que o cliente é recriado a partir da imagem fixada e que o room service separado restaura qualquer estado de colaboração que prometa manter. O guia do repositório Git à produção é o modelo relevante aqui: recrie o artifact e faça backup apenas do estado externo que realmente existe.

Não classifique um diretório como persistente a menos que o Excalidraw grave dados relevantes nele. Mounts vazios ou não utilizados criam uma falsa sensação de segurança e fazem com que os operadores procurem o estado no lugar errado.

Mapear o Excalidraw antes de tocar no Docker

O processo HTTP do Excalidraw escuta na porta 80; mantenha essa porta na rede da aplicação e publique apenas a rota da plataforma. O requisito do runtime local é um room server separado e uma camada de storage para colaboração persistente. Mantenha o ciclo de vida desses componentes explícito para que mover o Excalidraw entre hosts não altere o comportamento silenciosamente.

Registre o boundary em um contrato curto: quem é responsável pelo requisito, qual credential é usada, qual timeout é aceitável e como a falha se manifesta. Em seguida, execute esta transação: desenhe e exporte um diagrama, compartilhe um link de colaboração pelo room service configurado e reconecte um segundo navegador. Durante a execução, observe a entrega de static assets da imagem básica, enquanto as conexões WebSocket e o estado das salas pertencem ao serviço de colaboração separado, pois essa carga fornece um ponto de partida mais útil do que um container ocioso.

Um teste de aceitação de produção para o Excalidraw

Um release candidate do Excalidraw conquista tráfego ao concluir um cenário fixo: desenhar e exportar um diagrama, compartilhar um link de colaboração pelo room service configurado e reconectar um segundo navegador. Capture o digest da imagem, a configuração efetiva não secreta, a origem pública e os timestamps desse cenário. Os dados de teste devem ser descartáveis, mas realistas o suficiente para exercitar o mesmo caminho usado pelos usuários.

Execute o teste após substituir o runtime. Em seguida, recrie o serviço sem dados de servidor na imagem básica; faça backup de qualquer serviço de colaboração separado. A recuperação será aprovada quando o cliente for recriado a partir da imagem fixada e o room service separado restaurar qualquer estado de colaboração que prometa manter. Compare as medições de recursos da entrega de static assets da imagem básica, com as conexões WebSocket e o estado das salas pertencendo ao serviço de colaboração separado, com a versão anterior e investigue desvios relevantes antes da promoção.

Por fim, exercite esta falha controlada: envie uma entrada inofensiva próxima do limite de recurso ou formato associado a este boundary: a interface carrega, mas a colaboração falha porque o endpoint WebSocket está incorreto. Verifique se o Excalidraw explica a falha, não danifica o estado existente e retoma o funcionamento quando a condição válida retorna. Salve um trecho de log com dados sensíveis removidos e o tempo de recuperação. Juntos, esses testes cobrem comportamento, durabilidade e operabilidade, em vez de apenas a disponibilidade do processo.

Transformar o comando local em um serviço inspecionável

Um launch com formato de produção é intencionalmente simples: estado nomeado, porta explícita e nenhum secret dentro da imagem.

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

O exemplo é um baseline, não uma stack de suporte completa. Confirme o requisito local antes da exposição: um room server separado e uma camada de storage para colaboração persistente. Verifique os mounts efetivos e o listener. Em seguida, tente desenhar e exportar um diagrama, compartilhar um link de colaboração pelo room service configurado e reconectar um segundo navegador. Fixe a imagem que está funcionando antes do próximo restart.

Decisões de segurança específicas do Excalidraw

No Excalidraw, a rotação de contas não é a tarefa de hardening, porque a imagem padrão não tem um account store. Concentre-se em não presumir que a imagem estática sozinha fornece storage durável para salas compartilhadas. Proteja as salas privadas de colaboração e não alegue colaboração durável quando apenas a imagem web do Excalidraw estiver implantada.

Use HTTPS, autenticação opcional da plataforma e um digest de imagem revisado. Não monte dados não relacionados do host e limite a carga representada pela entrega de static assets da imagem básica, enquanto as conexões WebSocket e o estado das salas pertencem ao serviço de colaboração separado. Um cliente externo limpo deve receber o build pretendido, enquanto um cliente não autorizado deve ser rejeitado antes de alcançar o container quando o acesso estiver restrito.

Roteie o Excalidraw sem criar uma falsa impressão de HTTPS

A emissão de TLS é apenas metade da rota do Excalidraw. Sirva o cliente por HTTPS e configure os endpoints de colaboração separadamente. Envie o tráfego internamente para a porta 80 e encaminhe o scheme externo para que as URLs geradas e os secure cookies permaneçam consistentes.

Use o cenário completo do Excalidraw a partir de uma rede limpa, não apenas a página inicial. Um erro 502 ou uma falha de certificado pode ser isolado com a configuração automática de domínio e TLS. Se o tráfego alcançar o processo e a interface carregar, mas a colaboração falhar porque o endpoint WebSocket está incorreto, diagnostique essa condição no ponto em que ela ocorre, em vez de acumular redirects.

Atualizar o Excalidraw sem fazer suposições

O indicador de serviço útil para o Excalidraw é a conclusão bem-sucedida de “desenhar e exportar um diagrama, compartilhar um link de colaboração pelo room service configurado e reconectar um segundo navegador”. Combine esse resultado com a entrega de static assets da imagem básica, enquanto as conexões WebSocket e o estado das salas pertencem ao serviço de colaboração separado; uma página inicial carregada não diz nada sobre compatibilidade da saída ou exaustão de recursos.

Antes de substituir a imagem, considere este risco: as versões do frontend, do room server e do storage devem ser testadas em conjunto, em vez de presumir que o cliente estático é responsável pelos dados compartilhados. Teste entradas representativas e de limite nas duas versões e mantenha o digest antigo até que o candidato seja aprovado. Se a interface carregar, mas a colaboração falhar porque o endpoint WebSocket está incorreto, inspecione o formato da requisição, o comportamento do cliente e os logs do runtime antes de alterar as configurações de rota ou storage.

Usar o Dockup para a camada da plataforma

Um template de Excalidraw de um clique deve incluir o digest da imagem, a porta 80, o timing de health check, o domínio e o TLS. Como o serviço básico é stateless, o Dockup pode recriá-lo diretamente no compute do Dockup ou em uma máquina conectada, sem fingir que um volume vazio é um backup.

Após o lançamento, sirva o cliente por HTTPS e configure os endpoints de colaboração separadamente. O Dockup deve preservar as configurações de runtime do Excalidraw enquanto o operador confirma este requisito local: um room server separado e uma camada de storage para colaboração persistente. Verifique este resultado: desenhe e exporte um diagrama, compartilhe um link de colaboração pelo room service configurado e reconecte um segundo navegador. Qualquer extensão stateful posterior deve declarar seu próprio mount, secret e teste de restauração, em vez de alterar silenciosamente o significado do template básico.

Perguntas frequentes

Do que o Excalidraw precisa para uma implantação em produção?

Roteie o container do Excalidraw na porta 80 por meio de uma única origem HTTPS. O requisito do runtime local é um room server separado e uma camada de storage para colaboração persistente. Não considere o Excalidraw pronto até conseguir desenhar e exportar um diagrama, compartilhar um link de colaboração pelo room service configurado e reconectar um segundo navegador.

Quais dados do Excalidraw devem fazer parte de um backup?

A imagem padrão do Excalidraw não tem um mount obrigatório de dados da aplicação. Preserve a configuração da implantação e faça backup de qualquer estado conectado separadamente; a recuperação será aprovada quando o cliente for recriado a partir da imagem fixada e o room service separado restaurar qualquer estado de colaboração que prometa manter.

O Excalidraw exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Excalidraw e mantenha a porta 80 na rota interna. Aplique corretamente a configuração do Excalidraw: sirva o cliente por HTTPS e configure os endpoints de colaboração separadamente. No Excalidraw, o HTTPS protege credentials ou conteúdo do usuário durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar uma atualização do Excalidraw?

Implante a imagem candidata do Excalidraw ao lado da versão atual e repita a transação de aceitação com uma entrada conhecida. Preste atenção especial porque as versões do frontend, do room server e do storage devem ser testadas em conjunto, em vez de presumir que o cliente estático é responsável pelos dados compartilhados. O container padrão não tem migração de dados; portanto, mantenha o digest anterior até que as verificações de saída e compatibilidade sejam aprovadas.