Como hospedar o HedgeDoc por conta própria em 2026: WebSockets, OAuth e arquivos enviados

Existem duas versões de “executar o HedgeDoc”: existe um container ou o serviço cumpre sua função de verdade. Apenas a segunda importa. Aqui, a comprovação consiste em criar uma nota, editá-la simultaneamente em dois browsers, enviar uma imagem e autenticar-se pelo provedor selecionado.

O HedgeDoc serve para isso: notas Markdown colaborativas em tempo real. A implantação precisa preservar os componentes por trás desse comportamento; uma porta, um volume e um certificado são insumos, não o resultado.

Faça backup do estado que o HedgeDoc não consegue recriar

Defina o ponto e o tempo de recuperação do HedgeDoc considerando o banco de dados, os arquivos enviados e a configuração de autenticação. Monte /hedgedoc/public/uploads antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Um volume nomeado resolve a persistência entre redeploys; ele não resolve casos de comprometimento nem a perda do servidor.

Crie um ambiente de restauração limpo, use a mesma versão fixada da aplicação e comprove que notas, revisões, usuários e uploads retornam e que dois browsers conseguem colaborar na nota restaurada. Registre comandos, ajustes de propriedade e o tempo decorrido. O guia de backup é um padrão útil: um backup só é confiável depois da restauração, não depois do upload.

Separe o HedgeDoc das dependências

A saúde do processo e a saúde do produto são coisas distintas no HedgeDoc. A porta 3000 pode responder enquanto a transação voltada ao usuário ainda falha. O contrato de rede do HedgeDoc é o Postgres, além de provedores opcionais de OAuth e SMTP. Mantenha endpoints privados em DNS interno, permita apenas as chamadas de saída necessárias e forneça ao HedgeDoc uma credencial de serviço com escopo limitado.

Use este exercício de readiness após mudanças relevantes de configuração: crie uma nota, edite-a simultaneamente em dois browsers, envie uma imagem e autentique-se pelo provedor selecionado. Mantenha verificações externas dispendiosas fora dos probes de liveness para que uma indisponibilidade do provedor não provoque um loop de reinicialização. O trabalho de capacidade deve acompanhar conexões WebSocket, gravações no banco de dados, mídia enviada e histórico de documentos, que representam melhor a pressão real sobre o HedgeDoc do que as solicitações de página.

Cinco verificações mais fortes que a saúde do container

Transforme o smoke test do HedgeDoc em um comando de release repetível ou em um runbook curto. A saída deve demonstrar o seguinte resultado: criar uma nota, editá-la simultaneamente em dois browsers, enviar uma imagem e autenticar-se pelo provedor selecionado. Registre com o resultado a versão da aplicação, o digest do container, o hostname da rota e o identificador dos dados de teste.

Execute a mesma verificação após uma troca rotineira de container e depois de restaurar o banco de dados, os arquivos enviados e a configuração de autenticação em outro local. A restauração foi bem-sucedida quando as notas, revisões, usuários e uploads retornam e dois browsers conseguem colaborar na nota restaurada. Compare o tempo e o consumo relacionados a conexões WebSocket, gravações no banco de dados, mídia enviada e histórico de documentos; uma mudança significativa merece investigação mesmo quando a ação final continua passando.

Em seguida, simule uma falha segura: negue temporariamente à identidade de teste o acesso ao Postgres, além dos provedores opcionais de OAuth e SMTP. Confirme que o HedgeDoc exibe a falha e retorna ao normal sem alterações manuais destrutivas. Preserve apenas o trecho de log necessário e com dados redigidos. Esse gate de quatro partes abrange inicialização, persistência, recuperação e tratamento de falhas.

Inicie o HedgeDoc sem ocultar as partes móveis

Um comando mínimo é útil quando revela o que a plataforma gerenciará mais tarde.

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

Aqui, a porta 3000 permanece privada no host e todos os caminhos necessários são explícitos. Adicione as configurações de conexão revisadas para o Postgres, além dos provedores opcionais de OAuth e SMTP; use nomes privados para serviços privados. Verifique a inicialização tanto pelos logs quanto pela comprovação específica da aplicação: crie uma nota, edite-a simultaneamente em dois browsers, envie uma imagem e autentique-se pelo provedor selecionado. Depois de verificar, fixe a versão da imagem para que uma substituição rotineira não altere o comportamento silenciosamente.

Não dê ao HedgeDoc acesso ao host inteiro

No caso do HedgeDoc, a superfície valiosa não é necessariamente a landing page. O principal erro é usar um session secret de exemplo ou permitir involuntariamente a criação anônima de notas. Enfrente isso de forma deliberada: use um session secret estável, decida se a criação anônima de notas é aceitável e restrinja o acesso a notas privadas.

Gere CMD_SESSION_SECRET como um valor longo e aleatório; a rotação normalmente invalida sessões ou tokens, portanto planeje o impacto para os usuários em vez de tratá-la como uma migração de criptografia. Use um usuário de container sem privilégios quando a imagem oferecer suporte e não monte credenciais sem relação com o serviço. Aplique limites de taxa ou tamanho no ingress, onde trabalhos não confiáveis podem consumir conexões WebSocket, gravações no banco de dados, mídia enviada e histórico de documentos.

Teste o HedgeDoc de fora do servidor

Escolha o hostname final do HedgeDoc antes que os usuários salvem callbacks ou configurações do cliente e, em seguida, defina CMD_DOMAIN e CMD_PROTOCOL_USESSL para a URL pública. A rota da plataforma deve encerrar o TLS uma vez e direcionar para a porta privada 3000.

Execute a transação de aceitação externamente. Se o cliente nunca alcançar o HedgeDoc, use o checklist de validação de SSL para verificar DNS e certificados. Se a solicitação chegar ao HedgeDoc, mas as edições em tempo real falharem porque os WebSockets ou as configurações de domínio estão incorretos, pare de alterar redirects do proxy e inspecione o limite específico da aplicação.

Opere o HedgeDoc considerando seu gargalo real

Use criar uma nota, editá-la simultaneamente em dois browsers, enviar uma imagem e autenticar-se pelo provedor selecionado como smoke test do HedgeDoc após cada deployment. As métricas de suporte são conexões WebSocket, gravações no banco de dados, mídia enviada e histórico de documentos; crie alertas quando esses recursos se aproximarem de um ponto que degrade a ação do usuário.

O principal risco de mudança é que as migrações de banco de dados do HedgeDoc, as configurações de OAuth e as mudanças em plugins ou renderizadores exigem um release gradual. Um release seguro começa com um snapshot restaurável e valida qualquer mudança de estado irreversível antes de direcionar o tráfego. Quando as edições em tempo real falharem porque os WebSockets ou as configurações de domínio estão incorretos, mantenha o container com falha tempo suficiente para ler sua configuração e o primeiro erro.

Onde o Dockup reduz o trabalho com o HedgeDoc

O Dockup pode assumir as partes substituíveis da plataforma: direcionar o tráfego para a porta 3000, emitir o domínio e o certificado, injetar secrets, anexar armazenamento persistente e conectar o HedgeDoc a serviços gerenciados ou anexados de forma privada. Isso pode ser feito na infraestrutura do Dockup ou em um servidor conectado por você.

O trabalho de aceitação do HedgeDoc continua explícito. Depois do deployment com um clique, defina CMD_DOMAIN e CMD_PROTOCOL_USESSL para a URL pública, conecte e teste o Postgres, além dos provedores opcionais de OAuth e SMTP, e execute este cenário: crie uma nota, edite-a simultaneamente em dois browsers, envie uma imagem e autentique-se pelo provedor selecionado. Essa divisão é intencional: o Dockup elimina a configuração repetitiva de infraestrutura sem fingir que as funções da aplicação, as credenciais dos provedores ou a política de restauração se definem sozinhas.

Perguntas frequentes

O que o HedgeDoc precisa para um deployment em produção?

Direcione o container do HedgeDoc na porta 3000 por meio de uma única origem HTTPS. O requisito de rede de suporte é o Postgres, além dos provedores opcionais de OAuth e SMTP. Não considere o HedgeDoc pronto até conseguir criar uma nota, editá-la simultaneamente em dois browsers, enviar uma imagem e autenticar-se pelo provedor selecionado.

Quais dados do HedgeDoc devem fazer parte de um backup?

Mantenha /hedgedoc/public/uploads persistente e inclua o banco de dados, os arquivos enviados e a configuração de autenticação no mesmo manifesto de recuperação. Uma restauração limpa do HedgeDoc só é aprovada quando as notas, revisões, usuários e uploads retornam e dois browsers conseguem colaborar na nota restaurada.

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

Use HTTPS para a origem pública do HedgeDoc e mantenha a porta 3000 na rota interna. Aplique corretamente a configuração do HedgeDoc: defina CMD_DOMAIN e CMD_PROTOCOL_USESSL para a URL pública. No HedgeDoc, o HTTPS protege credenciais ou conteúdo dos usuários durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do HedgeDoc?

Restaure o estado atual do HedgeDoc em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Dê atenção especial ao fato de que as migrações de banco de dados do HedgeDoc, as configurações de OAuth e as mudanças em plugins ou renderizadores exigem um release gradual. Mantenha a imagem anterior do HedgeDoc até entender os limites da migração de dados e do rollback.