Como Ativar a Pesquisa de Texto Completo em uma Instância do Mastodon com Elasticsearch

A pesquisa padrão do Mastodon encontra apenas nomes de usuário e hashtags exatas. Essa limitação frustra usuários avançados e moderadores que precisam localizar postagens por palavras-chave ou frases na linha do tempo federada. A causa é que o Mastodon armazena postagens em um banco de dados PostgreSQL sem um índice de texto completo por padrão. Este artigo explica como instalar e configurar o Elasticsearch no seu servidor Mastodon para habilitar a pesquisa de texto completo em postagens, incluindo postagens privadas e não listadas visíveis para o pesquisador.

O que a Pesquisa de Texto Completo Faz e o que Você Precisa Antes de Começar

A pesquisa de texto completo no Mastodon indexa o conteúdo textual dos status, incluindo postagens públicas, não listadas e privadas que o usuário pesquisador pode ver. Também indexa nomes de usuário, nomes de exibição e hashtags. Quando um usuário digita uma consulta na barra de pesquisa, o Mastodon envia a solicitação para o Elasticsearch em vez de escanear o banco de dados PostgreSQL. Isso retorna resultados em menos de um segundo, mesmo em instâncias com milhões de postagens.

Antes de começar, você precisa dos seguintes pré-requisitos:

• Uma instância do Mastodon rodando em um servidor Linux com Docker e Docker Compose instalados.
• Acesso root ou sudo ao servidor.
• Pelo menos 2 GB de RAM livre no servidor. O Elasticsearch requer no mínimo 1 GB de memória heap.
• Elasticsearch 7.17.x. Não use a versão 8.x — o Mastodon não a suporta.

Passos para Instalar e Configurar o Elasticsearch para o Mastodon

Estes passos assumem que você está usando a configuração oficial do Mastodon com Docker. Se você executa o Mastodon sem Docker, ajuste os caminhos e nomes de serviços conforme necessário.

Passo 1: Adicionar o Serviço Elasticsearch ao Docker Compose

1. Abra seu arquivo docker-compose.yml
   Navegue até o diretório do Mastodon e abra o docker-compose.yml em um editor de texto com privilégios root.
2. Adicione o bloco de serviço Elasticsearch
   Na seção services:, adicione o seguinte bloco:

     es:
       image: docker.elastic.co/elasticsearch/elasticsearch:7.17.24
       environment:
         - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
         - "discovery.type=single-node"
         - "xpack.security.enabled=false"
       volumes:
         - ./elasticsearch:/usr/share/elasticsearch/data
       ports:
         - "127.0.0.1:9200:9200"

   Ajuste os valores de memória em ES_JAVA_OPTS com base na capacidade do seu servidor. O exemplo usa 512 MB de heap.

3. Adicione o volume Elasticsearch à seção de volumes
   No final do arquivo, em volumes:, adicione:

     elasticsearch:

4. Adicione variáveis de ambiente ao serviço web
   No bloco do serviço web, em environment:, adicione estas linhas:

         ES_ENABLED=true
         ES_HOST=es
         ES_PORT=9200

5. Adicione as mesmas variáveis de ambiente ao serviço sidekiq
   Repita o passo anterior para o bloco do serviço sidekiq.
6. Salve e feche o arquivo
   Escreva as alterações e saia do editor.

Passo 2: Iniciar o Elasticsearch e Recriar os Contêineres do Mastodon

1. Crie o diretório de dados do Elasticsearch
   Execute mkdir -p ./elasticsearch no diretório do Mastodon para armazenar os dados do índice de forma persistente.
2. Defina as permissões adequadas para o diretório de dados
   Execute chown -R 1000:1000 ./elasticsearch para corresponder ao ID do usuário do contêiner Elasticsearch.
3. Recrie os contêineres do Mastodon
   Execute docker-compose up -d para iniciar o novo contêiner Elasticsearch e reiniciar os serviços existentes com as novas variáveis de ambiente.
4. Verifique se o Elasticsearch está rodando
   Execute curl http://localhost:9200. Você deve ver uma resposta JSON contendo "name" : "es" e "version" : {"number" : "7.17.24"}.

Passo 3: Criar o Índice de Busca no Mastodon

1. Execute a tarefa de indexação de busca
   Execute o seguinte comando dentro do contêiner web do Mastodon:
   docker-compose run --rm web rails mastodon:search:deploy
   Isso cria o índice Elasticsearch e o popula com postagens existentes. O processo pode levar vários minutos dependendo do tamanho do seu banco de dados.
2. Reinicie o Sidekiq para aplicar o novo índice
   Execute docker-compose restart sidekiq para que os jobs em segundo plano comecem a enviar novas postagens para o índice.
3. Teste a pesquisa
   Abra sua instância do Mastodon em um navegador. Faça login com qualquer conta. Digite uma palavra de uma postagem conhecida na barra de pesquisa. Você deve ver resultados correspondentes abaixo dos resultados de usuários e hashtags.

Problemas Comuns Após Ativar a Pesquisa de Texto Completo

A Pesquisa Não Retorna Resultados para Postagens Conhecidas

Se você pesquisar uma palavra que existe em uma postagem pública e nada aparecer, o índice pode não ter sido construído ainda. Aguarde alguns minutos para o Sidekiq processar a fila de indexação. Você pode verificar o painel do Sidekiq em /sidekiq na sua instância para ver o número de jobs pendentes na fila default. Se a fila permanecer travada, reinicie o Sidekiq novamente com docker-compose restart sidekiq.

O Contêiner Elasticsearch Falha ao Iniciar com Erro de Memória

Se o contêiner sair com um erro sobre bloqueio de memória ou heap insuficiente, aumente os valores de ES_JAVA_OPTS no docker-compose.yml. Para um servidor com 4 GB de RAM, defina -Xms1g -Xmx1g. Além disso, certifique-se de que vm.max_map_count esteja definido como pelo menos 262144 no host. Execute sysctl -w vm.max_map_count=262144 e torne a alteração permanente adicionando vm.max_map_count=262144 ao /etc/sysctl.conf.

A Pesquisa Funciona, mas Postagens Privadas Estão Ausentes dos Resultados

Isso é esperado. O Mastodon indexa apenas postagens privadas e diretas para o autor dessas postagens. Outros usuários não podem pesquisar conteúdo em postagens privadas ou diretas. Se você é administrador e precisa pesquisar todas as postagens, deve usar o banco de dados diretamente via psql ou o painel de administração do Mastodon. Não há configuração no Elasticsearch para substituir esse limite de permissão.

Item	Elasticsearch 7.17.x	Pesquisa de Texto Completo no PostgreSQL
Velocidade de busca para instâncias grandes	Menos de 1 segundo para milhões de postagens	Vários segundos a minutos
Latência de atualização do índice	Quase em tempo real (segundos)	Requer VACUUM ANALYZE manual
Tipos de conteúdo suportados	Texto, nomes de usuário, nomes de exibição, hashtags	Apenas texto com stemming limitado
Requisito de memória	Mínimo de 1 GB de heap	Nenhum além do PostgreSQL
Compatibilidade com Mastodon	Oficial e estável	Não suportado

Após ativar o Elasticsearch, sua instância do Mastodon agora retorna resultados de busca por palavras-chave em tempo real. Os usuários podem encontrar postagens por tópico, frase ou nome de usuário sem depender apenas de hashtags. Como próximo passo, revise as configurações de administração do Mastodon em Preferências > Administração > Configurações do Servidor > Descoberta para ajustar a visibilidade de busca para postagens não listadas. Para ajustes avançados, defina o tamanho do heap ES_JAVA_OPTS para 50% da RAM do servidor, mas nunca exceda 31 GB devido ao limite de ponteiros de objetos compactados do Elasticsearch.