Como Atualizar uma Instância Mastodon Auto-Hospedada com Segurança

Atualizar uma instância Mastodon auto-hospedada garante patches de segurança, novos recursos e melhorias de desempenho. Mas uma atualização mal-sucedida pode causar downtime, perda de dados ou problemas de federação. O principal risco são alterações no esquema do banco de dados que não podem ser revertidas de forma limpa se o processo parar no meio. Este artigo explica as etapas exatas para preparar, executar e verificar uma atualização da instância Mastodon sem perder dados ou conectividade.

Entendendo os Riscos e Requisitos da Atualização do Mastodon

O Mastodon é construído com Ruby on Rails e usa PostgreSQL como banco de dados. As atualizações geralmente envolvem a atualização da versão do Ruby, Node.js, Yarn e do próprio código-fonte do Mastodon. A etapa mais perigosa é a migração do banco de dados, que modifica o esquema. Se a migração falhar no meio, o banco de dados pode ficar em um estado inconsistente difícil de reverter manualmente.

Um segundo risco é a incompatibilidade de versão. O Mastodon requer versões específicas de Ruby, Node.js e PostgreSQL. Atualizar apenas o Mastodon sem atualizar essas dependências pode fazer com que a aplicação falhe ao iniciar. O repositório oficial do Mastodon fornece um arquivo docker-compose.yml para implantações baseadas em Docker e guias de instalação para configurações manuais. Sempre atenda aos requisitos de versão listados nas notas de lançamento.

O terceiro ponto comum de falha é a fila de jobs em segundo plano do Sidekiq. Durante uma atualização, jobs antigos podem permanecer na fila e falhar ao serem processados com o novo código. Isso pode levar a notificações travadas, timelines quebradas ou pushes de federação com falha. Drenar a fila antes da atualização evita esses problemas.

Passos para Atualizar uma Instância Mastodon Auto-Hospedada com Segurança

Os passos a seguir assumem que você tem acesso SSH ao servidor e está usando uma instalação manual com serviços systemd. Se você usa Docker, adapte os comandos para sua configuração de contêiner. Sempre teste a atualização em um ambiente de staging primeiro, se possível.

1. Faça backup do banco de dados e dos arquivos de configuração
   Execute pg_dump -Fc mastodon_production > /tmp/mastodon_backup.dump para criar um backup compactado do PostgreSQL. Copie o arquivo .env.production e o diretório public/system para um local seguro fora do servidor. Eles contêm todas as mídias enviadas pelos usuários.
2. Ative o modo de manutenção no painel administrativo do Mastodon
   Faça login na interface administrativa do Mastodon. Vá em Administração > Configurações do Servidor > Manutenção. Ative o modo de manutenção. Isso exibe uma página estática para os visitantes e impede novas postagens, seguidores ou chamadas de API durante a atualização.
3. Drene a fila de jobs do Sidekiq
   Pare o serviço Sidekiq com systemctl stop mastodon-sidekiq. Em seguida, execute cd /home/mastodon/live && RAILS_ENV=production bin/tootctl sidekiq killall para remover todos os jobs pendentes. Isso evita que jobs antigos falhem após a atualização.
4. Pare os serviços web e de streaming do Mastodon
   Execute systemctl stop mastodon-web e systemctl stop mastodon-streaming. Isso garante que nenhuma nova requisição chegue à aplicação enquanto você atualiza o código.
5. Atualize as dependências do sistema
   Verifique as notas de lançamento para as versões necessárias de Ruby e Node.js. Por exemplo, se o Mastodon v4.2 requer Ruby 3.2, atualize com rbenv install 3.2.2 && rbenv global 3.2.2. Atualize o Node.js usando nvm install 20 ou seu gerenciador de pacotes.
6. Baixe o código-fonte mais recente do Mastodon
   Mude para o usuário mastodon: su - mastodon. Navegue até o diretório live: cd /home/mastodon/live. Baixe o lançamento mais recente: git fetch origin && git checkout v4.2.1 (substitua a tag pela versão desejada).
7. Instale as gems Ruby e pacotes JavaScript atualizados
   Execute bundle install --deployment --without development test para instalar novas gems. Em seguida, execute yarn install --frozen-lockfile para instalar dependências JavaScript. Esses comandos podem levar vários minutos.
8. Execute as migrações do banco de dados
   Execute RAILS_ENV=production bin/rails db:migrate. Isso aplica quaisquer alterações no esquema. Fique atento a erros na saída. Se uma migração falhar, restaure o backup e investigue a causa antes de tentar novamente.
9. Pré-compile os assets
   Execute RAILS_ENV=production bin/rails assets:precompile. Isso gera arquivos CSS e JavaScript atualizados. Pular esta etapa pode causar layouts quebrados ou ícones ausentes.
10. Reinicie os serviços do Mastodon
    Saia da sessão do usuário mastodon. Inicie todos os serviços: systemctl start mastodon-web mastodon-streaming mastodon-sidekiq. Verifique o status com systemctl status mastodon-web para confirmar que estão ativos.
11. Desative o modo de manutenção
    Volte ao painel administrativo e desative o modo de manutenção. A instância agora está online com a nova versão.
12. Verifique a federação e as funções básicas
    Publique um status público e verifique se ele aparece na timeline federada. Envie uma mensagem direta para um usuário em outra instância. Confirme se a interface web carrega sem erros. Verifique os logs do servidor com journalctl -u mastodon-web -f para quaisquer avisos.

Falhas Comuns na Atualização e Como Lidar com Elas

A migração do banco de dados falha com erro de sintaxe

Isso geralmente acontece quando as versões das gems Ruby não correspondem ao lançamento do Mastodon. Restaure o banco de dados a partir do backup usando pg_restore -d mastodon_production /tmp/mastodon_backup.dump. Em seguida, verifique se você executou bundle install com sucesso e se o arquivo Gemfile.lock está atualizado. Tente a migração novamente.

Workers do Sidekiq travam após a atualização

Se você não drenou a fila antes da atualização, jobs antigos podem referenciar classes ou métodos removidos. Pare o Sidekiq novamente e execute bin/tootctl sidekiq killall. Em seguida, reinicie o Sidekiq. Se os travamentos persistirem, verifique os logs do Sidekiq em /home/mastodon/live/log/sidekiq.log para mensagens de erro específicas.

A interface web mostra uma página em branco ou erros 500

Isso geralmente é causado por assets pré-compilados ausentes. Execute RAILS_ENV=production bin/rails assets:precompile novamente e reinicie o serviço web. Se o problema continuar, verifique se o diretório public/assets contém os arquivos compilados e se o servidor web está apontando para o caminho correto.

A federação para de funcionar após a atualização

Problemas de federação geralmente decorrem de uma versão desatualizada do Node.js ou de um serviço de streaming ausente. Confirme se o mastodon-streaming está em execução e se a porta 4000 está aberta no firewall. Reinicie o serviço de streaming com systemctl restart mastodon-streaming e teste a federação seguindo uma conta remota.

Item	Instalação Manual	Instalação Docker
Método de backup	pg_dump, cp para arquivos	docker exec pg_dump, docker cp
Parar serviços	systemctl stop mastodon-*	docker-compose down
Atualizar código	git checkout tag	docker-compose pull
Instalar dependências	bundle install, yarn install	docker-compose build
Comando de migração	RAILS_ENV=production bin/rails db:migrate	docker-compose run web rails db:migrate
Iniciar serviços	systemctl start mastodon-*	docker-compose up -d

Agora você pode atualizar sua instância Mastodon com confiança. Antes de cada atualização futura, sempre revise o changelog no repositório oficial do Mastodon no GitHub. Como dica avançada, configure um cron job que execute um pg_dump noturno para /var/backups para que você sempre tenha um backup recente antes de qualquer manutenção.