Como Migrar uma Instância do Mastodon do Bare Metal para Docker

Executar uma instância do Mastodon em bare metal oferece controle total, mas frequentemente leva a conflitos de dependência e procedimentos de atualização manuais. Migrar para a conteinerização com Docker padroniza o ambiente, simplifica as atualizações e reduz o risco de desvios de configuração. Este guia mostra as etapas exatas para exportar seus dados existentes do Mastodon, configurar uma instância baseada em Docker e importar seu banco de dados e arquivos sem perder postagens ou contas de usuário.

Entendendo o Processo de Migração do Bare Metal para Docker

O Mastodon armazena seus dados em dois locais principais: um banco de dados PostgreSQL e um diretório do sistema de arquivos para mídias enviadas. O banco de dados contém tudo, desde contas de usuário e postagens até relacionamentos de seguidores e denúncias. O sistema de arquivos contém avatares, cabeçalhos, emojis personalizados e anexos de mídia. Migrar para Docker significa que você deve transferir ambos os componentes mantendo o mesmo nome de domínio e chaves secretas.

A instalação em bare metal normalmente usa um gerenciador de pacotes do sistema como apt ou yum, com o Mastodon rodando diretamente no servidor. Uma instalação Docker usa contêineres definidos em um arquivo docker-compose.yml. O aplicativo principal do Mastodon, os workers background do Sidekiq e a API de streaming rodam em contêineres separados. A migração não altera o formato subjacente dos dados, portanto uma exportação e importação diretas funcionam.

Antes de começar, confirme que seu novo host Docker atende aos requisitos mínimos: pelo menos 2 núcleos de CPU, 4 GB de RAM e espaço em disco suficiente para armazenar seus arquivos de mídia. Você também precisa ter o Docker Engine e o Docker Compose instalados na máquina de destino. Se você usa um proxy reverso como Nginx ou Caddy no servidor bare metal, planeje reconfigurá-lo para a configuração Docker ou execute o proxy dentro de um contêiner separado.

Passos para Migrar o Mastodon do Bare Metal para Docker

1. Pare os serviços do Mastodon no servidor bare metal
   Execute systemctl stop mastodon- para parar os serviços web, sidekiq e streaming. Isso impede que novos dados sejam gravados durante a exportação. Verifique se todos os processos foram parados com systemctl status mastodon-.
2. Exporte o banco de dados PostgreSQL
   Use pg_dump -Fc mastodon_production > mastodon_production.dump como o usuário do banco de dados do Mastodon. O formato customizado (-Fc) compacta o dump e permite restauração paralela posteriormente. Transfira o arquivo de dump para o host Docker usando scp ou rsync.
3. Copie os arquivos de mídia e sistema
   No servidor bare metal, localize o diretório system do Mastodon (geralmente /home/mastodon/live/public/system). Execute rsync -avz /home/mastodon/live/public/system/ usuario@novo-servidor:/caminho/para/volume-docker/system/. Inclua o arquivo .env.production do servidor bare metal para chaves secretas e variáveis de ambiente.
4. Configure o ambiente Docker
   No novo servidor, crie um diretório para o Mastodon e coloque o docker-compose.yml oficial do repositório do Mastodon. Copie seu arquivo .env.production para este diretório. Edite o docker-compose.yml para mapear o volume de mídia para o caminho onde você colocou os arquivos sincronizados. Por exemplo, adicione ./system:/mastodon/public/system nos serviços web e sidekiq.
5. Inicie apenas o contêiner do banco de dados
   Execute docker compose up -d db para iniciar apenas o contêiner PostgreSQL. Aguarde 10 segundos para o banco de dados inicializar. Em seguida, restaure o dump usando docker compose exec -T db pg_restore -U postgres -d mastodon_production < mastodon_production.dump. A flag -T suprime a saída de progresso e acelera a operação.
6. Execute as migrações do banco de dados
   Após a restauração ser concluída, inicie todos os contêineres com docker compose up -d. Execute docker compose exec web bundle exec rails db:migrate para aplicar quaisquer alterações de esquema que a versão Docker espera. Esta etapa garante que a estrutura do banco de dados corresponda ao código atual do Mastodon.
7. Regenere o pipeline de assets e o cache
   Execute docker compose exec web bundle exec rails assets:precompile para compilar CSS e JavaScript. Em seguida, execute docker compose exec web bundle exec rails tmp:cache:clear para limpar quaisquer dados em cache que referenciem os caminhos de arquivo antigos.
8. Atualize o DNS e o proxy reverso
   Aponte seu nome de domínio para o endereço IP do novo servidor. Configure seu proxy reverso para encaminhar o tráfego para o contêiner web do Mastodon (porta 3000 por padrão). Se você usa Nginx, a documentação oficial do Mastodon fornece uma configuração de exemplo. Aguarde a propagação do DNS (geralmente de 5 a 30 minutos).
9. Verifique a migração
   Abra sua instância do Mastodon em um navegador. Faça login com uma conta existente e verifique se sua foto de perfil, postagens e seguidores aparecem corretamente. Publique um novo toot e confirme se ele aparece na linha do tempo pública. Monitore os logs do Docker com docker compose logs -f para quaisquer erros.

Problemas Comuns Após Migrar o Mastodon para Docker

A restauração do banco de dados falha com role does not exist

O comando pg_restore pode falhar se o contêiner PostgreSQL usar um usuário de banco de dados diferente do servidor bare metal. Crie a role correta manualmente antes de restaurar. Conecte-se ao contêiner do banco de dados com docker compose exec db psql -U postgres e execute CREATE ROLE mastodon WITH LOGIN SUPERUSER;. Em seguida, tente a restauração novamente.

Arquivos de mídia aparecem quebrados ou ausentes

Se avatares ou anexos aparecerem como imagens quebradas, o caminho do volume no docker-compose.yml provavelmente não corresponde ao destino do rsync. Verifique se o diretório system está montado em /mastodon/public/system dentro dos contêineres web e sidekiq. Execute docker compose exec web ls /mastodon/public/system para confirmar que os arquivos estão visíveis.

Workers do Sidekiq acumulam e nunca processam

Quando o Sidekiq não consegue se conectar ao Redis ou ao banco de dados, os jobs se acumulam. Verifique se o contêiner Redis está em execução com docker compose ps. Confirme se as variáveis de ambiente REDIS_URL e DB_HOST em seu arquivo .env.production apontam para os nomes dos serviços Docker (por exemplo, redis e db) em vez de endereços IP ou localhost.

O login falha com chave secreta inválida

As chaves SECRET_KEY_BASE, OTP_SECRET e VAPID_PRIVATE_KEY devem corresponder aos valores originais do bare metal. Copie o arquivo .env.production inteiro do servidor antigo. Se alguma chave estiver faltando, gere novas com docker compose exec web bundle exec rake secret, mas isso invalidará todas as sessões de usuário existentes.

Item	Bare Metal	Docker
Gerenciamento de dependências	Instalação manual de pacotes via apt ou yum	Imagens de contêiner automáticas com versões fixas
Método de backup do banco de dados	pg_dump e script cron manual	docker compose exec db pg_dump ou snapshots de volume automatizados
Procedimento de atualização	Parar serviços, puxar git, bundle install, executar migrações	docker compose pull && docker compose up -d
Localização do sistema de arquivos	/home/mastodon/live/public/system	Volume Docker montado em /mastodon/public/system
Arquivo de configuração	.env.production no diretório home do usuário Mastodon	.env.production no diretório do projeto, lido pelos contêineres

Após concluir a migração, sua instância do Mastodon roda inteiramente em contêineres Docker. As atualizações agora exigem apenas puxar novas imagens e reiniciar os serviços. Agende backups regulares do banco de dados usando docker compose exec db pg_dump -U postgres mastodon_production e armazene o dump fora do servidor. Para maior segurança, teste a migração em um servidor de staging primeiro para identificar quaisquer problemas específicos do ambiente antes de tocar na instância de produção.