Atualização de versão (on-premise)

Visão geral e pré-requisitos

A atualização baixa as imagens mais recentes do II no registro da Selbetti e recria os containers, preservando dados e configurações. O II fica indisponível por alguns minutos durante a recriação, então programe uma janela de manutenção.

Antes de começar, confirme:

Acesso ao servidor com permissão para executar comandos Docker (usuário no grupo docker ou com sudo).
Docker Compose v2 instalado (comando docker compose, sem hífen). Verifique com docker compose version.
Usuário e senha do registro selbii.azurecr.io, fornecidos pela Selbetti. Se não os tiver, solicite pelo portal de suporte.
Espaço livre em disco para as novas imagens e para o backup do banco de dados.
Terminal aberto no diretório de instalação do II, onde ficam o docker-compose.yml e o .env. Todos os comandos deste guia partem desse diretório.

Os serviços do II usam profiles do Docker Compose (backend, frontend e db). Sem eles, o Compose ignora os serviços. Defina os profiles uma vez na sessão do terminal, antes de qualquer outro comando:

export COMPOSE_PROFILES=backend,frontend,db

Se a sua instalação usa apenas parte dos serviços (por exemplo, banco de dados externo), mantenha somente os profiles em uso.

1. Antes de começar: backup

Faça os três passos abaixo antes de toda atualização. Eles permitem voltar à versão anterior caso algo dê errado.

Backup do banco de dados. Substitua <usuario> pelo valor da variável POSTGRES_USER do arquivo .env:
```
docker compose exec -T db pg_dump -U <usuario> -d qm3_api -Fc > backup_ii_$(date +%Y%m%d_%H%M).dump
```
Confira se o arquivo foi gerado e não está vazio com ls -lh backup_ii_*.dump.

Backup dos arquivos de configuração:

tar czf config_ii_$(date +%Y%m%d_%H%M).tar.gz docker-compose.yml .env postgresql.conf keystore.p12 autenticacao-speech-to-text-google.json database-init

Esse pacote contém senhas e certificados. Guarde-o em local seguro, com acesso restrito.

Marcação das imagens atuais para rollback. O comando cria uma cópia local (tag -anterior) de cada imagem em uso:

for img in backend frontend db-pg15; do
  docker tag selbii.azurecr.io/md2ii-app:${img}-latest selbii.azurecr.io/md2ii-app:${img}-anterior
done

2. Atualizar o II

Autentique-se no registro da Selbetti e informe o usuário e a senha quando solicitado:
```
docker login selbii.azurecr.io
```
Baixe as novas imagens:
```
docker compose pull
```
O comando deve listar o download de back-intelligence, front-intelligence e db.
Recrie os containers com as novas imagens:
```
docker compose up -d
```
O Compose recria apenas os containers cuja imagem mudou. Os dados do banco, em ./postgres, são preservados.
Encerre a sessão no registro (recomendado):
```
docker logout selbii.azurecr.io
```

Na primeira subida após a atualização, o back-end aplica automaticamente as migrações do banco de dados e pode levar alguns minutos a mais para ficar disponível. Não interrompa os containers nesse intervalo.

Os scripts da pasta database-init rodam somente na criação inicial do banco. Não é necessário alterá-los nem executá-los durante uma atualização.

3. Validar a atualização

Verifique o estado dos containers:
```
docker compose ps
```
Os três serviços devem aparecer como running (ou Up). Um serviço em Restarting indica falha na inicialização.
Confira os logs do back-end em busca de erros na inicialização:
```
docker compose logs --tail 200 back-intelligence
```
Para acompanhar em tempo real, use docker compose logs -f back-intelligence e encerre com Ctrl+C.
Teste pelo navegador: acesse o II no endereço habitual (por padrão, porta 4200 do servidor), confirme a nova versão exibida na tela de login, faça login, abra um chat e envie uma pergunta. A versão também aparece no topo da página após o login.

Se algum desses passos falhar e o problema não for resolvido em poucos minutos, faça o rollback (seção 4) e abra um chamado.

4. Voltar à versão anterior (rollback)

O rollback usa as imagens marcadas com -anterior no passo 3 do backup. Não execute docker compose pull durante o rollback, pois ele sobrescreveria as imagens restauradas.

Restaure as imagens anteriores e recrie os containers:

for img in backend frontend db-pg15; do
  docker tag selbii.azurecr.io/md2ii-app:${img}-anterior selbii.azurecr.io/md2ii-app:${img}-latest
done
docker compose up -d

Valide seguindo a seção 3.
Restaure o banco somente se necessário, quando a versão anterior não funcionar com o banco atual (as migrações aplicadas automaticamente pela nova versão podem ser incompatíveis com a anterior). Recomendamos abrir um chamado antes deste passo:
```
docker compose stop back-intelligence front-intelligence
docker compose exec -T db pg_restore -U <usuario> -d qm3_api --clean --if-exists < backup_ii_AAAAMMDD_HHMM.dump
docker compose start back-intelligence front-intelligence
```
Substitua o nome do arquivo pelo backup gerado antes da atualização. Dados registrados após a atualização serão perdidos.

5. Limpeza, problemas comuns e suporte

Mantenha as imagens -anterior por alguns dias após a atualização. Quando a nova versão estiver estável, libere espaço em disco:

for img in backend frontend db-pg15; do
  docker rmi selbii.azurecr.io/md2ii-app:${img}-anterior
done
docker image prune -f

Sintoma	Causa provável	O que fazer
`docker compose pull` não baixa nada ou retorna `no service selected`	Profiles não definidos na sessão	Execute `export COMPOSE_PROFILES=backend,frontend,db` e repita o comando
`unauthorized` ou `authentication required` no download	Sessão não autenticada ou credencial expirada	Execute `docker login selbii.azurecr.io`; se persistir, solicite nova credencial ao suporte
`docker-compose: command not found` ou erro de sintaxe no Compose	Docker Compose v1 instalado	Instale o plugin Docker Compose v2 e use `docker compose`
Container em `Restarting` após a atualização	Falha na inicialização do serviço	Verifique `docker compose logs <serviço>`; se não resolver, faça o rollback

Para abrir um chamado, acesse o portal de suporte do II e anexe os logs gerados com:

docker compose logs --tail 1000 > logs_ii_$(date +%Y%m%d_%H%M).txt