Como fazer self-hosting do Memos em 2026: notas, acesso à API e backups

Trate o Memos como um sistema pequeno, não como uma imagem Docker. O objetivo do Memos para o usuário é claro: notas rápidas em Markdown com uma API; a implantação só é aceitável quando você consegue criar uma nota privada e um anexo, recuperá-los pela API, editá-los e confirmar que continuam disponíveis após a substituição do container.

Essa distinção revela a falha que os operadores encontram depois dos testes locais: o arquivo do banco de dados está na camada do container e desaparece após a substituição. Ela também torna o plano de backup e atualização específico o suficiente para ser testado.

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

O primeiro container deve ser fácil de excluir e recriar. Mantenha os dados fora da camada gravável, faça o bind da porta 5230 apenas onde o proxy consiga alcançá-la e passe a configuração em runtime.

docker run -d \
  --name memos \
  --restart unless-stopped \
  -p 127.0.0.1:5230:5230 \
  -v memos-data:/var/opt/memos \
  neosmemo/memos:stable --mode prod --port 5230

Fixe a versão da imagem após o teste inicial. Leia o primeiro erro de inicialização, em vez da mensagem final de reinicialização, verifique cada montagem com docker inspect e acompanhe os logs enquanto cria uma nota privada e um anexo, recupera-os pela API, edita-os e confirma que continuam disponíveis após a substituição do container. Essa sequência diferencia um comando de imagem incorreto de um problema de dependência ou permissão.

Defina primeiro o que significa sucesso para o Memos

Separe quatro aspectos do Memos: entrada, o listener na porta 5230, estado durável e serviços de suporte ou capacidade local. O requisito de runtime local é um volume durável para o banco de dados incorporado e os assets. Teste esse limite antes da publicação e novamente após a substituição de um container.

Execute a transação conhecida — criar uma nota privada e um anexo, recuperá-los pela API, editá-los e confirmar que continuam disponíveis após a substituição do container — antes de considerar essa separação concluída. Meça as gravações do SQLite, o crescimento dos anexos, o tráfego da API e as pesquisas nas notas acumuladas e mantenha o resultado junto ao registro da implantação. Isso fornece tanto um critério de aceitação quanto a primeira referência de capacidade.

Não dê ao Memos acesso ao host inteiro

No Memos, a superfície valiosa não é necessariamente a página inicial. O principal erro é deixar o cadastro aberto por mais tempo do que o planejado. Enfrente isso deliberadamente: feche o cadastro quando for apropriado e mantenha as notas privadas protegidas por uma conta forte e HTTPS.

O Memos não exige um secret de bootstrap neste baseline; proteja a conta de administrador propriamente dita ou a autenticação upstream. Use um usuário de container sem privilégios quando a imagem oferecer suporte e não monte credenciais que não tenham relação com o serviço. Aplique limites de taxa ou tamanho na entrada, onde operações não confiáveis podem consumir gravações do SQLite, crescimento dos anexos, tráfego da API e pesquisas nas notas acumuladas.

TLS é fácil; URLs geradas, não

Evite origens públicas temporárias e permanentes para o Memos. Em vez disso, use uma origem HTTPS estável para clientes de navegador e da API, aponte o nome DNS escolhido para a rota da plataforma e faça proxy apenas para a porta 5230.

Execute esta ação de fora do host: crie uma nota privada e um anexo, recupere-os pela API, edite-os e confirme que continuam disponíveis após a substituição do container. Se a entrada falhar, o guia de troubleshooting de 502 aborda erros de porta e listener. Se o Memos receber a solicitação, mas o arquivo do banco de dados estiver na camada do container e desaparecer após a substituição, as evidências agora apontam para além do proxy.

Comprove que o Memos sobrevive à substituição

Uma imagem de container pode ser baixada novamente; o banco de dados do Memos e os recursos enviados não podem. Monte /var/opt/memos antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Inspecione a montagem efetiva em vez de confiar no nome de um arquivo do Compose e verifique se o usuário do runtime consegue gravar no local esperado pelo Memos.

Escolha uma política de retenção e um destino fora do host e ensaie a recuperação sem tocar na produção. O exercício só passa quando usuários, notas, tags e recursos retornam e a API recupera a nota privada conhecida. Para estados baseados em banco de dados, combine snapshots de armazenamento com exports consistentes com a aplicação, conforme descrito em recuperação point-in-time versus snapshots.

Cinco verificações mais fortes que a health check do container

Não use o tráfego do primeiro usuário como teste de aceitação do Memos. Prepare um estado de exemplo inofensivo e execute a ação completa: “criar uma nota privada e um anexo, recuperá-los pela API, editá-los e confirmar que continuam disponíveis após a substituição do container”. Registre a URL pública exata, o resultado, a referência da imagem e o intervalo de logs associados à execução.

Substitua o container e repita sem recriar os dados. Em seguida, faça a recuperação em um host vazio; a condição de recuperação é que usuários, notas, tags e recursos retornem e que a API recupere a nota privada conhecida. Observe as gravações do SQLite, o crescimento dos anexos, o tráfego da API e as pesquisas nas notas acumuladas em cada execução e defina um alerta para a degradação da transação, não para métricas de container ocioso.

Uma verificação final deve falhar de propósito: envie uma entrada inofensiva próxima do limite de recurso ou formato associado a esta fronteira: o arquivo do banco de dados está na camada do container e desaparece após a substituição. Verifique se a mensagem resultante do Memos identifica a fronteira relevante, em vez de disparar a exclusão de dados ou uma reinicialização sem fim. Restaure a condição válida e confirme que a mesma transação de exemplo é concluída com sucesso. Mantenha este exercício curto na checklist de release.

Logs que respondem à próxima pergunta

Use “criar uma nota privada e um anexo, recuperá-los pela API, editá-los e confirmar que continuam disponíveis após a substituição do container” como smoke test do Memos depois de cada implantação. As métricas de apoio são as gravações do SQLite, o crescimento dos anexos, o tráfego da API e as pesquisas nas notas acumuladas; gere 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 migrations do banco de dados do Memos devem ser ensaiadas em uma cópia, pois todo o estado do serviço vive em um único caminho compacto. Um release seguro começa com um snapshot recuperável e valida qualquer alteração de estado irreversível antes de transferir o tráfego. Quando o arquivo do banco de dados está na camada do container e desaparece após a substituição, mantenha o container com falha tempo suficiente para ler sua configuração e o primeiro erro.

Use o Dockup para a camada da plataforma

O Dockup elimina o trabalho manual de reverse proxy e gerenciamento do ciclo de vida em torno do Memos. O serviço recebe uma rota HTTPS estável para a porta 5230, configuração injetada e armazenamento persistente durante as substituições. Um servidor de cliente conectado segue o mesmo modelo do compute hospedado pelo Dockup.

Após o lançamento, cumpra o contrato da aplicação: use uma origem HTTPS estável para clientes de navegador e da API, confirme o requisito local — um volume durável para o banco de dados incorporado e os assets — e execute esta comprovação: crie uma nota privada e um anexo, recupere-os pela API, edite-os e confirme que continuam disponíveis após a substituição do container. Isso mantém a experiência de um clique útil sem simplificar excessivamente os detalhes que tornam o Memos recuperável e seguro.

Perguntas frequentes

O que o Memos precisa para uma implantação em produção?

Encaminhe o container do Memos na porta 5230 por meio de uma única origem HTTPS. O requisito de runtime local é um volume durável para o banco de dados incorporado e os assets. Não considere o Memos pronto até conseguir criar uma nota privada e um anexo, recuperá-los pela API, editá-los e confirmar que continuam disponíveis após a substituição do container.

Quais dados do Memos devem fazer parte de um backup?

Persista /var/opt/memos e inclua o banco de dados do Memos e os recursos enviados no mesmo manifesto de recuperação. Uma restauração limpa do Memos só passa quando usuários, notas, tags e recursos retornam e a API recupera a nota privada conhecida.

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

Use HTTPS para a origem pública do Memos e mantenha a porta 5230 na rota interna. Aplique corretamente a configuração do Memos: use uma origem HTTPS estável para clientes de navegador e da API. No Memos, o HTTPS protege credenciais ou conteúdo do usuário durante o trânsito e mantém consistente o comportamento dos clientes sensível à origem.

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

Restaure o estado atual do Memos em uma implantação isolada, aplique a versão candidata e repita sua transação de aceitação. Dê atenção especial a isso, pois as migrations do banco de dados do Memos devem ser ensaiadas em uma cópia, já que todo o estado do serviço vive em um único caminho compacto. Mantenha a imagem anterior do Memos até entender os limites da migração de dados e do rollback.