Como auto-hospedar o Etherpad em 2026: pads, plugins e backups do banco de dados

Se você já tentou auto-hospedar o Etherpad, provavelmente conhece bem o estado frustrante: a interface aparece, mas as sessões são desconectadas porque os timeouts do proxy são curtos demais. Recriar o container raramente corrige uma inconsistência entre URLs, estado e dependências.

Este passo a passo usa um critério concreto de conclusão: abrir um pad em dois navegadores, editar simultaneamente, inspecionar as revisões e exportar o resultado no formato exigido. Cada decisão de configuração é avaliada com base nesse critério, e não em um indicador verde do container.

Escolha a menor topologia viável para o Etherpad

A menor topologia responsável para o Etherpad contém um listener privado na porta 9001, uma rota de ingresso e um limite de estado documentado. O contrato de rede do Etherpad é o Postgres ou outro banco de dados compatível para uso durável por vários usuários. Mantenha os endpoints privados no DNS interno, permita apenas as chamadas de saída necessárias e forneça ao Etherpad uma credencial de serviço com escopo limitado.

Valide a topologia solicitando que um cliente limpo abra um pad em dois navegadores, edite simultaneamente, inspecione as revisões e exporte o resultado no formato exigido. Monitore as sessões WebSocket, a quantidade de revisões, as gravações no banco de dados e a execução dos plugins durante o processo. O resultado mostra se a próxima melhoria deve ser feita na memória, no armazenamento, na rede ou em um worker separado, em vez de incentivar o dimensionamento arbitrário do container.

Crie um container substituível para o Etherpad

Use o container como um runtime substituível, não como o local onde a verdade fica armazenada.

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

Adicione as configurações de conexão revisadas para o Postgres ou outro banco de dados compatível para uso durável por vários usuários; use nomes privados para serviços privados. Inspecione o usuário do container, os caminhos com permissão de escrita e o listener associado antes de expô-lo. Execute a ação completa — abrir um pad em dois navegadores, editar simultaneamente, inspecionar as revisões e exportar o resultado no formato exigido — e salve a referência exata da imagem que produziu o resultado.

Evite que o sucesso do proxy mascare uma falha da aplicação

O navegador, o cliente da API e o Etherpad precisam concordar com uma única origem. Para garantir isso, defina a URL pública e o suporte a WebSocket no proxy. Preserve o host e o protocolo originais, mantendo a porta 9001 indisponível como um endereço público concorrente.

O guia de troubleshooting para sites indisponíveis ajuda a distinguir uma rota inacessível de uma aplicação que está respondendo. Essa distinção é importante aqui: as sessões são desconectadas porque os timeouts do proxy são curtos demais. Somente o primeiro problema é corrigido com alterações no ingresso; o segundo exige a inspeção dos logs, do estado ou da carga de trabalho do Etherpad.

Planeje a restauração do Etherpad antes do lançamento

Proteja o estado do Etherpad antes de otimizar o container. O conjunto necessário inclui o banco de dados, os plugins enviados e as configurações. Monte /opt/etherpad-lite/var antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Se vários armazenamentos precisarem permanecer consistentes, documente a ordem em que as gravações são pausadas e os backups são feitos.

Mantenha cópias fora do servidor de deployment e criptografe o material que contenha credenciais ou conteúdo privado. A recuperação é bem-sucedida quando pads, autores, revisões e plugins retornam e as edições simultâneas continuam convergindo. A diferença entre um mount persistente e uma cópia independente é explicada em armazenamento persistente e snapshots.

Defina o limite de confiança do Etherpad

Feche a janela de bootstrap assim que existir o primeiro administrador confiável. A armadilha concreta do Etherpad é distribuir uma senha de administrador conhecida ou deixar os pads editáveis por qualquer pessoa; o limite mais seguro é definir uma senha de administrador real, decidir quem pode criar pads e não presumir que uma URL de pad difícil de adivinhar seja privada.

Substitua imediatamente o ADMIN_PASSWORD de exemplo, armazene-o fora da imagem e faça sua rotação como faria com uma credencial de administrador caso ela seja exposta. A rede privada deve transportar as credenciais das dependências, e as funções dentro do Etherpad devem conceder apenas a ação útil mínima. Mantenha corpos de requisições sensíveis e respostas de provedores fora dos logs de rotina.

Atualize o Etherpad sem fazer suposições

Observe o trabalho realizado pelo Etherpad: sessões WebSocket, quantidade de revisões, gravações no banco de dados e execução dos plugins. Defina limites com margem para esse trabalho e evite um liveness probe que concorra com ele. A verificação operacional ainda deve tentar abrir um pad em dois navegadores, editar simultaneamente, inspecionar as revisões e exportar o resultado no formato exigido conforme uma programação definida.

Para atualizações, lembre-se de que as versões dos plugins do Etherpad, a sintaxe das configurações e as migrações do banco de dados devem ser testadas em conjunto. Faça o deployment do candidato contra uma cópia recuperada e repita o teste conhecido. Se as sessões forem desconectadas porque os timeouts do proxy são curtos demais, use os logs do runtime e a requisição de rede real para descobrir qual suposição mudou.

O que precisa passar antes de os dados reais do Etherpad chegarem

Para o Etherpad, defina uma transação conhecida como válida antes do lançamento: abrir um pad em dois navegadores, editar simultaneamente, inspecionar as revisões e exportar o resultado no formato exigido. Coloque seus pré-requisitos, a resposta esperada e as etapas de limpeza no controle de versão, sem valores secretos. Fixe a imagem usada para estabelecer essa referência.

Use a transação para validar uma substituição e uma restauração independente. O serviço restaurado só é aceitável quando pads, autores, revisões e plugins retornam e as edições simultâneas continuam convergindo. Ao mesmo tempo, observe as sessões WebSocket, a quantidade de revisões, as gravações no banco de dados e a execução dos plugins, transformando a parte mais lenta ou mais limitada em um alerta de nível de serviço.

O gate também precisa de um caso negativo: negue temporariamente à identidade de teste o acesso ao Postgres ou a outro banco de dados compatível para uso durável por vários usuários. Confirme que o Etherpad produz um erro acionável preservando os dados, restaure a condição válida e repita a transação conhecida como válida. Manter os dois resultados impede que um endpoint de health superficial se torne a única evidência de produção.

Faça o deployment do Etherpad no Dockup sem perder seus limites

Para o Etherpad, o Dockup é mais útil no limite entre uma imagem e um serviço durável. Ele mantém a rota para a porta 9001, o TLS, os valores secretos e o armazenamento associados durante as substituições de containers, independentemente de a computação pertencer ao Dockup ou ao seu servidor conectado.

Finalize com conhecimento da aplicação: defina a URL pública e o suporte a WebSocket no proxy; conecte e teste o Postgres ou outro banco de dados compatível para uso durável por vários usuários; e execute esta verificação: abra um pad em dois navegadores, edite simultaneamente, inspecione as revisões e exporte o resultado no formato exigido. Mantenha o resultado como uma verificação de deployment para que a próxima atualização da imagem seja avaliada pelo comportamento, e não pelo status do container.

Perguntas frequentes

Do que o Etherpad precisa para um deployment em produção?

Encaminhe o container do Etherpad na porta 9001 por meio de uma única origem HTTPS. O requisito de rede de suporte é o Postgres ou outro banco de dados compatível para uso durável por vários usuários. Não considere o Etherpad pronto até conseguir abrir um pad em dois navegadores, editar simultaneamente, inspecionar as revisões e exportar o resultado no formato exigido.

Quais dados do Etherpad devem fazer parte de um backup?

Mantenha /opt/etherpad-lite/var persistente e inclua o banco de dados, os plugins enviados e as configurações no mesmo manifesto de recuperação. Uma restauração limpa do Etherpad só passa quando pads, autores, revisões e plugins retornam e as edições simultâneas continuam convergindo.

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

Use HTTPS para a origem pública do Etherpad e mantenha a porta 9001 na rota interna. Aplique corretamente a configuração do Etherpad: defina a URL pública e o suporte a WebSocket no proxy. Para o Etherpad, o HTTPS protege credenciais ou conteúdo de usuários durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como uma atualização do Etherpad deve ser testada?

Restaure o estado atual do Etherpad em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial, pois as versões dos plugins do Etherpad, a sintaxe das configurações e as migrações do banco de dados devem ser testadas em conjunto. Mantenha a imagem anterior do Etherpad até entender os limites de migração de dados e rollback.