Como fazer self-hosting do Meilisearch em 2026: master keys, índices e dumps

O self-hosting do Meilisearch se torna interessante no primeiro redeploy, não no primeiro docker run. Se MEILI_ENV permanecer como development ou o volume de dados for perdido durante um redeploy, o Docker ainda poderá reportar um processo perfeitamente saudável. A implantação abaixo é organizada em torno de um comportamento observável: criar um índice, importar documentos, configurar atributos filtráveis e comprovar que uma consulta tolerante a erros de digitação e um filtro retornam os registros esperados.

A finalidade do Meilisearch é clara: pesquisa full-text tolerante a erros de digitação, com uma API HTTP rápida. Essa descrição mostra o que precisa permanecer público, o que deve continuar privado e o que um backup precisa reconstruir.

Mapeie o Meilisearch antes de mexer no Docker

Separe quatro aspectos do Meilisearch: ingress, o listener na porta 7700, o estado persistente e os serviços de suporte ou a capacidade local. O requisito de runtime local é ter disco suficiente para os índices, com margem para rebuilds e dumps. Mantenha o ciclo de vida explícito para que mover o Meilisearch entre hosts não altere o comportamento silenciosamente.

Execute a transação validada — criar um índice, importar documentos, configurar atributos filtráveis e comprovar que uma consulta tolerante a erros de digitação e um filtro retornam os registros esperados — antes de considerar essa separação concluída. Meça a memória usada pela indexação em lote, o espaço temporário em disco durante a criação de índices, a quantidade de documentos e o tráfego de pesquisa concorrente, 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.

Torne a inicialização do Meilisearch reproduzível

Use um comando que exponha todas as escolhas importantes. Esta configuração base vincula o Meilisearch ao loopback do host, adiciona os mounts de dados conhecidos e fornece a primeira configuração obrigatória. Confirme o requisito local antes de expor o serviço: disco suficiente para os índices, com margem para rebuilds e dumps.

docker run -d \
  --name meilisearch \
  --restart unless-stopped \
  -p 127.0.0.1:7700:7700 \
  -v meilisearch-data:/meili_data \
  -e MEILI_MASTER_KEY=replace-with-a-long-random-value \
  getmeili/meilisearch:latest

Substitua tags flutuantes por uma versão ou digest testado. Depois da inicialização, verifique docker logs --tail 200 meilisearch e confirme que o processo está escutando na porta 7700. Em seguida, execute a ação de aceitação do Meilisearch; uma resposta da página raiz não comprova que o cenário completo funciona: criar um índice, importar documentos, configurar atributos filtráveis e comprovar que uma consulta tolerante a erros de digitação e um filtro retornam os registros esperados.

Dê ao Meilisearch um endereço canônico

Trate a URL externa do Meilisearch como uma configuração que permanece válida após redeploys. Primeiro, disponibilize a API HTTP por meio de uma única origem HTTPS autenticada; depois, encaminhe o hostname para a porta 7700, mantendo intactos o host e o scheme originais.

O checklist de reachability da implantação pode comprovar que as requisições entram no container. A partir desse ponto, a falha conhecida — MEILI_ENV permanece como development ou o volume de dados é perdido durante um redeploy — deve ser investigada no Meilisearch, no estado dele ou na carga de trabalho, e não na automação de certificados.

Restaure o Meilisearch em um host vazio

O conjunto durável de recuperação é formado por dumps ou snapshots agendados e pelo diretório de dados persistente. Monte /meili_data antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Um volume protege os dados contra a substituição do container, mas não contra a perda do host, a exclusão acidental ou a corrupção no nível da aplicação.

Faça backups que entendam a fonte de dados: use dumps lógicos para bancos de dados ativos quando necessário e copie arquivos somente a partir de um estado consistente. Mantenha uma cópia criptografada fora do host do Meilisearch. O critério de aceitação de um restore deve ser específico — um dump deve ser importado em um servidor limpo com as mesmas configurações, a mesma quantidade de documentos e um ranking representativo. O guia de backups com restore testado explica por que o simples sucesso do job não é suficiente.

Proteja a parte valiosa do Meilisearch

Não herde pressupostos de segurança de um tutorial local. A preocupação específica do Meilisearch é iniciar um ambiente de produção sem uma master key. Por isso, a produção deve reservar a master key para a administração e fornecer aos clientes de pesquisa no navegador search keys com permissões restritas.

Trate MEILI_MASTER_KEY de acordo com a função que desempenha no Meilisearch: mantenha valores sensíveis fora do Git, documente os efeitos da rotação e nunca substitua um exemplo público em produção. Restrinja o acesso ao sistema de arquivos e à rede, proteja os endpoints de configuração e defina limites de upload, requisições ou execução em torno da memória usada pela indexação em lote, do espaço temporário em disco durante a criação de índices, da quantidade de documentos e do tráfego de pesquisa concorrente.

Monitore a carga de trabalho, não apenas o container

Os testes de capacidade devem exercitar a memória usada pela indexação em lote, o espaço temporário em disco durante a criação de índices, a quantidade de documentos e o tráfego de pesquisa concorrente, e não repetir uma requisição a /. Execute o cenário “criar um índice, importar documentos, configurar atributos filtráveis e comprovar que uma consulta tolerante a erros de digitação e um filtro retornam os registros esperados” com concorrência realista e registre latência, taxa de erros e crescimento do armazenamento.

O planejamento de upgrades precisa considerar este risco: a compatibilidade dos dumps do Meilisearch e os requisitos de rebuild dos índices devem ser verificados antes da alteração de versões. Teste a nova release com dados representativos, depois repita a transação de aceitação e compare o resultado. Se MEILI_ENV permanecer como development ou o volume de dados for perdido durante um redeploy, registre a transação que falhou e inspecione o primeiro ponto de fronteira envolvido, em vez de presumir que o ingress é o responsável.

Transforme o smoke test do Meilisearch em uma verificação de release

Para o Meilisearch, defina uma transação validada antes do lançamento: criar um índice, importar documentos, configurar atributos filtráveis e comprovar que uma consulta tolerante a erros de digitação e um filtro retornam os registros esperados. Mantenha no controle de versão os pré-requisitos, a resposta esperada e as etapas de limpeza, sem valores secretos. Fixe a imagem usada para estabelecer essa referência.

Use a transação para validar uma substituição e um restore independente. O serviço restaurado só será aceitável quando um dump puder ser importado em um servidor limpo com as mesmas configurações, a mesma quantidade de documentos e um ranking representativo. Ao mesmo tempo, observe a memória usada pela indexação em lote, o espaço temporário em disco durante a criação de índices, a quantidade de documentos e o tráfego de pesquisa concorrente, e transforme 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: envie uma entrada inofensiva próxima do limite de recurso ou formato associado a esta fronteira: MEILI_ENV permanece como development ou o volume de dados é perdido durante um redeploy. Confirme que o Meilisearch produz um erro acionável sem corromper os dados, restaure a condição válida e repita a transação validada. Manter os dois resultados evita que um endpoint de health superficial se torne a única evidência em produção.

Mantenha o Meilisearch explícito enquanto o Dockup cuida do roteamento

A implantação do Meilisearch com um clique do Dockup deve tornar a substituição segura: a rota continua apontando para a porta 7700, os secrets não são incorporados à imagem e os caminhos persistentes retornam no novo container. A mesma implantação pode ser executada no compute do Dockup ou em uma máquina anexada.

Conclua o trabalho específico da aplicação confirmando o requisito local — disco suficiente para os índices, com margem para rebuilds e dumps —, aplicando o endereço público canônico e executando esta verificação de aceitação: criar um índice, importar documentos, configurar atributos filtráveis e comprovar que uma consulta tolerante a erros de digitação e um filtro retornam os registros esperados. Adicione o resultado do restore ao runbook antes da chegada dos usuários reais.

Perguntas frequentes

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

Encaminhe o container do Meilisearch na porta 7700 por meio de uma única origem HTTPS. O requisito de runtime local é ter disco suficiente para os índices, com margem para rebuilds e dumps. Não considere o Meilisearch pronto até conseguir criar um índice, importar documentos, configurar atributos filtráveis e comprovar que uma consulta tolerante a erros de digitação e um filtro retornam os registros esperados.

Quais dados do Meilisearch devem fazer parte de um backup?

Persista /meili_data e inclua dumps ou snapshots agendados e o diretório de dados persistente no mesmo manifesto de recuperação. Um restore limpo do Meilisearch só será aprovado quando um dump puder ser importado em um servidor limpo com as mesmas configurações, a mesma quantidade de documentos e um ranking representativo.

O Meilisearch precisa de HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Meilisearch e mantenha a porta 7700 na rota interna. Aplique corretamente a configuração do Meilisearch: disponibilize a API HTTP por meio de uma única origem HTTPS autenticada. No Meilisearch, o HTTPS protege credenciais ou conteúdo de usuários durante o trânsito e mantém consistente o comportamento dos clientes que depende da origem.

Como testar um upgrade do Meilisearch?

Restaure o estado atual do Meilisearch em uma implantação isolada, aplique a versão candidata e repita a transação de aceitação. Dê atenção especial a este ponto, pois a compatibilidade dos dumps do Meilisearch e os requisitos de rebuild dos índices devem ser verificados antes da alteração de versões. Mantenha a imagem anterior do Meilisearch até entender os limites de migração dos dados e de rollback.