Backup e restauração

O backup de um Nodaro self-hosted é feito com um comando, e a restauração, com outro. O arquivo de backup guarda tudo o que a stack não consegue gerar de novo: o banco de dados, a sua mídia, a chave de criptografia da instância e o seu .env. A restauração também é a única forma de fazer downgrade, porque as migrações do banco de dados só avançam. Voltar a uma versão anterior significa restaurar o backup que você fez antes da atualização.

O que um backup contém

tools/community-backup.sh grava um único arquivo tar.gz:

O Redis fica de fora de propósito: ele só guarda o estado de curta duração dos jobs.

Fazer um backup

No diretório da instalação, onde fica o docker-compose.community.yml, com a stack rodando:

tools/community-backup.sh
# -> ./backups/nodaro-backup-<date>-v<version>.tar.gz

O script mostra o que entrou no arquivo de backup. Se a chave de criptografia estiver faltando, ele avisa isso em destaque e sai com um erro, para que um job agendado perceba. Esse arquivo de backup não consegue restaurar as suas chaves de provedor.

O dump do banco de dados é sempre consistente. A mídia gravada enquanto o backup roda pode ficar fora do arquivo. Para um snapshot da mídia com consistência garantida, pare o app primeiro:

docker compose -f docker-compose.community.yml stop nodaro

No Windows, execute os scripts no Git Bash, o shell que o Git for Windows instala. O PowerShell e o bash do WSL quebram os caminhos do contêiner.

Quando fazer backup

Antes de toda atualização de versão major, em que o primeiro número muda, e com a frequência que os seus dados merecem. Uma linha de cron funciona do jeito que está:

0 3 * * * cd /path/to/install && tools/community-backup.sh >> backup.log 2>&1

Restaurar um backup

tools/community-restore.sh backups/nodaro-backup-<date>-v<version>.tar.gz

A restauração substitui o banco de dados e a mídia pelo conteúdo do arquivo de backup, então ela pede que você digite RESTORE antes de mexer em qualquer coisa. Depois, ela:

1. Para o app e os clientes do banco de dados, auth e rest, porque as conexões abertas deles bloqueariam a restauração.
2. Restaura o Postgres e verifica se ele funciona, em vez de confiar nos códigos de saída. Algumas mensagens inofensivas da imagem do Supabase são esperadas e aparecem na saída.
3. Restaura a mídia e verifica se os buckets voltaram e se o MinIO está saudável. Em seguida, restaura a chave de criptografia e verifica o tamanho dela no volume. Por fim, restaura o seu .env, guardando antes à parte qualquer .env existente. Uma verificação que falha interrompe o script antes de o app iniciar: iniciar sem a chave certa criaria uma chave nova e deixaria todas as chaves de provedor restauradas ilegíveis para sempre.
4. Inicia tudo de novo e espera pela verificação de integridade do próprio app. O script só informa sucesso depois que o app está no ar e, caso contrário, sai com um erro.

Quando ela terminar, abra http://localhost:3000/setup. Todos os cartões devem estar verdes.

Fazer downgrade de versão

Não existe reversão de migrações. Para voltar a uma versão anterior:

1. Restaure o backup feito antes da atualização, como descrito acima.
2. Fixe a imagem mais antiga, por exemplo ghcr.io/nodaroai/nodaro-community:v1.25.1, em NODARO_IMAGE ou no docker-compose.community.yml. As tags exatas vX.Y.Z nunca são movidas.
3. Rode docker compose -f docker-compose.community.yml up -d nodaro.

Veja Atualização para as tags.

Fazer backup de uma implantação gerenciada

Fora da stack do Compose, quatro coisas guardam estado:

Se o Postgres cair durante uma migração ou uma recuperação, a API reinicia em loop até conseguir acessar o banco de dados. Quando o Postgres voltar, reinicie o contêiner do Nodaro.

Solução de problemas

• the db service is not running. Inicie a stack primeiro: docker compose -f docker-compose.community.yml up -d.
• As chaves de provedor aparecem como missing (ausente) depois de uma restauração. O banco de dados foi restaurado sem a encryption-key correspondente, ou com outra. Restaure a partir de um arquivo de backup que tenha a chave, ou digite as chaves de novo em /setup.
• A verificação da restauração falhou. O script se recusa a deixar um banco de dados restaurado pela metade em silêncio. Rode a restauração de novo. Se ela falhar repetidamente, o arquivo de backup pode estar truncado: compare o tamanho dele com o do original.
• could not read the encryption key durante um backup no Windows. Você não está no Git Bash, ou o contêiner do app não está rodando. Rode o backup de novo no Git Bash, com a stack no ar. O arquivo de backup sobre o qual o script avisou não é um backup utilizável.
• media restore verification FAILED ou encryption key verification FAILED. O script parou de propósito e não iniciou o app. Verifique o volume que ele indica, corrija a causa, normalmente um contêiner parado ou um disco cheio, e rode a restauração de novo. É seguro repetir.