Exportar Mastodon para Arquivo HTML Estático: Backup Auto-Hospedado

Você quer criar um backup permanente e auto-hospedado dos seus posts do Mastodon que funcione mesmo se a instância ficar offline. O Mastodon oferece uma ferramenta de exportação que gera arquivos CSV e JSON, mas esses formatos exigem software especializado para leitura. Um arquivo HTML estático converte seus posts públicos em um site navegável que você pode hospedar em qualquer servidor web básico ou até mesmo no seu computador local. Este artigo explica como gerar esse arquivo usando a API do Mastodon e ferramentas de código aberto, e como hospedar o resultado sem precisar de banco de dados ou scripts no servidor.

Como Funciona a Exportação do Mastodon e o Arquivo HTML Estático

O Mastodon oferece um recurso de exportação que empacota os dados da sua conta em um único arquivo ZIP. Esse arquivo contém arquivos JSON separados para seus status, anexos de mídia, favoritos, listas e seguidores. O formato JSON é legível por máquina, mas não é amigável para navegação humana. Uma ferramenta de arquivo HTML estático lê esses arquivos JSON e gera uma pasta de páginas HTML, folhas de estilo CSS e JavaScript que recria sua linha do tempo como um site navegável.

O processo de arquivamento não requer componentes no servidor. A saída é um conjunto de arquivos estáticos que qualquer servidor web pode servir. Isso significa que seu backup permanece acessível mesmo se a instância original do Mastodon for desativada. O arquivo inclui apenas seus posts públicos e não listados. Mensagens diretas e posts privados não são incluídos na exportação padrão por questões de privacidade.

Pré-requisitos Antes de Começar

Você precisa dos seguintes itens antes de gerar o arquivo:

• Uma conta no Mastodon com acesso à página Preferências > Exportar.
• Python 3.8 ou posterior instalado no seu computador para executar a ferramenta de conversão.
• Um destino de hospedagem web como GitHub Pages, Netlify ou uma pasta de servidor web básica.
• Pelo menos 500 MB de espaço livre em disco para a exportação e o arquivo gerado, se você tiver muitos posts e arquivos de mídia.

Passos para Exportar seus Dados do Mastodon e Criar um Arquivo HTML Estático

Siga estes passos em ordem para criar seu backup auto-hospedado.

1. Solicite a exportação dos seus dados do Mastodon
   Faça login na sua instância do Mastodon. Vá em Preferências > Exportar. Clique no botão “Solicitar seu arquivo”. A instância gerará um arquivo ZIP com todos os seus dados exportados. Esse processo pode levar vários minutos, dependendo do tamanho da sua conta. Você receberá uma notificação quando o arquivo estiver pronto para download.
2. Baixe o arquivo ZIP
   Volte a Preferências > Exportar após receber a notificação. Clique no link de download ao lado de “Seu arquivo está pronto”. Salve o arquivo ZIP em uma pasta no seu computador. Não renomeie o arquivo, pois a ferramenta de conversão espera a estrutura de nome padrão.
3. Instale a ferramenta Python mastodon-archive
   Abra um terminal ou prompt de comando. Execute o comando: pip install mastodon-archive. Isso instala a ferramenta e todas as suas dependências. Se você usa ambientes virtuais Python, ative o ambiente antes de executar o comando de instalação.
4. Extraia o arquivo ZIP baixado
   Use o utilitário de arquivamento do seu sistema operacional para extrair o arquivo ZIP em uma pasta dedicada. Por exemplo, extraia para C:\mastodon-backup\export no Windows ou ~/mastodon-backup/export no macOS ou Linux. A extração cria uma estrutura de pastas contendo outbox.json, likes.json, media_attachments e outros arquivos.
5. Execute a ferramenta mastodon-archive para gerar o HTML
   No terminal, navegue até a pasta que contém a exportação extraída. Execute o comando: mastodon-archive generate --input outbox.json --output ./archive. Substitua ./archive pelo caminho da pasta de saída desejada. A ferramenta lê os dados JSON e cria um site estático dentro da pasta de saída especificada.
6. Verifique o arquivo gerado
   Abra a pasta de saída e clique duas vezes no arquivo index.html. Seu navegador deve exibir sua linha do tempo com páginas individuais de posts. Verifique se os anexos de mídia, como imagens e vídeos, aparecem corretamente. Se a mídia estiver faltando, certifique-se de que a pasta media_attachments da exportação esteja no mesmo diretório que outbox.json quando você executou a ferramenta.
7. Envie o arquivo para seu host web
   Copie toda a pasta de saída para seu destino de hospedagem web. Para GitHub Pages, crie um novo repositório, envie o conteúdo da pasta e ative o Pages nas configurações do repositório. Para Netlify, arraste e solte a pasta no painel do Netlify. Para um servidor web básico, copie a pasta para o diretório público HTML do servidor.

Problemas Comuns e Limitações ao Auto-Hospedar um Arquivo do Mastodon

Anexos de mídia estão faltando no HTML gerado

A ferramenta mastodon-archive incorpora mídia vinculando à pasta local media_attachments. Se você extraiu o ZIP em um local separado do arquivo outbox.json, a ferramenta não consegue encontrar a mídia. Coloque a pasta media_attachments no mesmo diretório que outbox.json antes de executar o comando generate. Alternativamente, use a flag --media-dir para especificar o caminho exato para a pasta de mídia.

O arquivo não inclui respostas ou menções de outros usuários

A exportação do Mastodon inclui apenas seus próprios posts. Respostas de outros usuários aos seus posts não são incluídas porque pertencem à conta do outro usuário. O arquivo mostra seus posts em ordem cronológica, mas não exibe as conversas completas. Esta é uma limitação dos dados exportados, não da ferramenta de arquivamento.

Arquivos grandes falham ao gerar ou demoram muito

Se você tem milhares de posts, a ferramenta Python pode ficar sem memória. Reduza o uso de memória gerando o arquivo em uma máquina com pelo menos 4 GB de RAM. Alternativamente, use a flag --limit para restringir o número de posts incluídos. Por exemplo, --limit 500 gera um arquivo dos 500 posts mais recentes.

O arquivo não é exibido corretamente em dispositivos móveis

A saída padrão do mastodon-archive inclui CSS responsivo, mas versões antigas da ferramenta podem produzir layouts que não se adaptam a telas pequenas. Atualize a ferramenta para a versão mais recente executando pip install --upgrade mastodon-archive. Se o problema persistir, adicione um arquivo CSS personalizado à pasta static do arquivo com estilos compatíveis com dispositivos móveis.

Formatos de Exportação do Mastodon: JSON vs Arquivo HTML Estático

Item	Exportação JSON	Arquivo HTML Estático
Formato do arquivo	JSON (legível por máquina)	HTML, CSS, JavaScript (legível por humanos)
Requisito de visualização	Editor de texto ou script	Qualquer navegador web
Incorporação de mídia	Pasta media_attachments separada	Imagens e players de vídeo embutidos
Funcionalidade de busca	Requer grep ou script personalizado	Busca do navegador (Ctrl+F) funciona em cada página
Complexidade de hospedagem	N/A (não projetado para hospedagem)	Enviar pasta para qualquer host web estático
Privacidade	Inclui apenas posts públicos e não listados	Mesma limitação da exportação JSON

O arquivo HTML estático é a melhor escolha para backup pessoal de longo prazo porque permanece legível sem software especializado. A exportação JSON é mais adequada para análise de dados ou migração para outro serviço.

Agora você pode criar um backup auto-hospedado em HTML estático dos seus posts do Mastodon usando o recurso de exportação e a ferramenta Python mastodon-archive. O site gerado preserva sua linha do tempo em um formato que qualquer servidor web pode hospedar. Para backups contínuos, defina um lembrete para solicitar uma nova exportação a cada mês e regenerar o arquivo. Para estender o arquivo, adicione uma página de busca incluindo uma biblioteca de busca no lado do cliente, como Lunr.js, na pasta estática.