# Atualização

> Atualize o Nodaro self-hosted com uma imagem mais nova, fixe uma tag de versão, faça um backup antes de uma versão major e reverta restaurando esse backup.

Source: https://nodaro.ai/pt-BR/docs/self-hosting/updating

**Atualizar** um Nodaro self-hosted significa baixar uma imagem mais nova do app e reiniciar o app. Na stack incluída, as novas migrações do banco de dados são aplicadas sozinhas na inicialização, então não há mais nada para rodar. Antes de uma versão **major**, leia as notas da versão e faça um backup, porque não existe caminho de downgrade.

## Tags de imagem
Toda build da branch `main` publica a imagem do app, `ghcr.io/nodaroai/nodaro-community`, como `latest` e com a tag do commit dela. Cada versão lançada acrescenta três tags de versão.

| Tag | O que significa |
| --- | --- |
| `vX.Y.Z`, por exemplo `v2.0.0` | Exatamente uma build; a tag nunca é movida. Fixe-a para ter uma instalação estável byte a byte. |
| `vX.Y` | Avança pelos patches de uma versão minor. |
| `vX` | Avança por uma versão major inteira: recursos e correções chegam, mudanças incompatíveis nunca. |
| `latest` | Acompanha a `main`: toda mudança mesclada, lançada ou não, inclusive as versões major. |
| `<sha>` | Um commit; a tag nunca é movida. A outra forma de reproduzir exatamente uma build. |

Escolha a tag com `NODARO_IMAGE` no `.env`, por exemplo `NODARO_IMAGE=ghcr.io/nodaroai/nodaro-community:v1.23.0`.

## Atualizar a instalação
Para atualizar só o app:

```bash
docker compose -f docker-compose.community.yml pull nodaro
docker compose -f docker-compose.community.yml up -d nodaro
```

Para atualizar também o arquivo do Compose, os scripts de `tools/` e os serviços incluídos:

```bash
git pull
docker compose -f docker-compose.community.yml pull
docker compose -f docker-compose.community.yml up -d
```

Se você compila a imagem a partir do código-fonte, por exemplo para a Business edition, troque `pull` por `build`. Um `pull` baixaria a imagem Community publicada.

As migrações mantêm a compatibilidade com as versões seguintes: elas criam tabelas novas e adicionam colunas. Uma mudança destrutiva é destacada nas notas da versão. Fixe uma tag ou um commit se você precisar de cautela.

## Antes de uma versão major
Uma versão major muda o primeiro número, por exemplo de `v1` para `v2`. As versões major são as únicas que podem mudar variáveis de ambiente, a topologia do Compose ou comportamentos dos quais você possa depender.

1. Leia as notas da versão no [GitHub](https://github.com/nodaroai/app.nodaro.ai/releases).
2. Faça um backup com `tools/community-backup.sh`. Veja [Backup e restauração](https://nodaro.ai/docs/self-hosting/backups).
3. Atualize e depois verifique `/setup`: todos os cartões devem estar verdes.

## Reverter
Não existe reversão de migrações: o banco de dados só avança. Para voltar a uma versão anterior:

1. Restaure o backup que você fez **antes** da atualização: `tools/community-restore.sh <archive>`.
2. Fixe a imagem mais antiga, por exemplo `NODARO_IMAGE=ghcr.io/nodaroai/nodaro-community:v1.25.1`. As tags exatas `vX.Y.Z` nunca são movidas.
3. Inicie-a com `docker compose -f docker-compose.community.yml up -d nodaro`.

## Com um projeto gerenciado no Supabase
Quando o executor de migrações está desativado, aplique os novos arquivos de `supabase/migrations/` na ordem dos nomes **antes** de reiniciar com a nova imagem. Uma migração que falta normalmente não impede a API de rodar, mas os recursos que dependem dela respondem `500` até as tabelas deles existirem. Veja [Banco de dados](https://nodaro.ai/docs/self-hosting/database#apply-the-migrations-to-a-managed-project).

## Qual versão você está rodando
A versão em execução aparece na barra lateral do app e em `/health`. Clique na versão para ver as notas da versão que você está rodando. Quando existe uma versão mais nova, um ponto vermelho aparece ao lado da versão. A mesma caixa de diálogo mostra, então, as notas da versão mais recente e os comandos exatos de atualização, com a etapa de backup primeiro.

A verificação de atualizações envia uma requisição anônima por dia à API do GitHub. Uma verificação que falha é tentada de novo depois de 5 minutos, e depois com cada vez menos frequência, até uma dar certo.

| Variável | Padrão | O que faz |
| --- | --- | --- |
| `NODARO_UPDATE_CHECK` | ativada | `off` desativa a verificação por completo. Nenhuma requisição sai da instalação, `GET /v1/version` responde só com a versão em execução, e a barra lateral mostra a versão como texto simples. Para instalações isoladas da internet (air-gapped). |
| `NODARO_UPDATE_CHECK_TOKEN` | vazia (anônima) | Um token do GitHub para as leituras da lista pública de versões que a verificação faz. Ele **não precisa de escopos**. |

O GitHub permite 60 requisições anônimas por hora para cada endereço de saída. Uma instalação com endereço próprio nunca precisa de um token. Uma instalação que compartilha o endereço com outras pode encontrar essa cota gasta por terceiros. O rótulo da versão volta, então, ao valor embutido na build, e as notas da versão ficam vazias até uma nova tentativa dar certo. A linha de log `[update-check] … read failed: HTTP 403 (rate limit: 0 of 60 left…)` é o sinal. O token só é enviado para `api.github.com` e nunca é registrado no log.

O arquivo do Compose não repassa essas duas variáveis do `.env`. Adicione-as em `environment:` do serviço `nodaro`:

```yaml
nodaro:
environment:
# ...the variables already listed...
NODARO_UPDATE_CHECK: "off"
```

Reinicie para aplicar.

## Atualizar um servidor pelo GitHub Actions
O repositório traz um workflow de exemplo, `examples/deploy-host.yml`, que atualiza um servidor do Nodaro por SSH:

1. Copie-o para o seu próprio repositório, em `.github/workflows/`.
2. Defina os segredos do repositório `DEPLOY_HOST`, `DEPLOY_USER` e `DEPLOY_SSH_KEY`.
3. Ajuste o diretório de instalação e o comando do Compose no script dele para que correspondam ao seu servidor.
4. Execute-o manualmente pela aba **Actions** e escolha a tag de imagem a implantar.

O workflow se conecta ao servidor, roda `docker compose pull` e `docker compose up -d`, espera até 90 segundos que `/health` responda e depois remove as camadas antigas da imagem. Nunca dispare uma implantação de produção a partir de um push em uma branch, e use nomes de segredos separados para cada ambiente.

## Frequently asked questions

### Como atualizo um Nodaro self-hosted?

Rode docker compose -f docker-compose.community.yml pull nodaro e depois docker compose -f docker-compose.community.yml up -d nodaro. Na stack incluída, as migrações do banco de dados são aplicadas sozinhas na inicialização.

### Qual tag de imagem devo fixar?

Fixe uma tag exata vX.Y.Z para ter uma instalação estável byte a byte. vX.Y recebe os patches de uma versão minor, vX recebe recursos e correções sem mudanças incompatíveis, e latest acompanha toda mudança mesclada, inclusive as versões major.

### Posso fazer downgrade para uma versão anterior?

Não diretamente, porque as migrações do banco de dados só avançam. Restaure o backup que você fez antes da atualização e depois fixe a tag da imagem mais antiga. Faça um backup antes de toda versão major.

### Como sei que há uma atualização disponível?

A versão na barra lateral do app mostra um ponto vermelho quando existe uma versão mais nova. Clique nela para ver as notas da versão e os comandos exatos de atualização. A verificação é uma requisição anônima por dia ao GitHub.

### Posso desativar a verificação de atualizações em uma instalação isolada da internet?

Sim. Adicione NODARO_UPDATE_CHECK com o valor off no bloco environment do serviço nodaro, no docker-compose.community.yml. Assim, nenhuma requisição sai da instalação, e a versão aparece como texto simples.