# Atualizador local do Zynklog

Copie o arquivo **zynklog** para a mesma pasta do Compose da instalação existente. Não substitua o Compose da sua instalação pelo de outra pasta. Requer Docker Desktop/Engine com Compose v2 atualizado e Bash (macOS/Linux; no Windows, WSL com acesso ao Docker). Não precisa de Node, Python, conta no GitHub nem token para imagens públicas.

```bash
chmod +x zynklog
./zynklog status
./zynklog update v1.1.0 --dry-run
./zynklog update v1.1.0
```

**v1.1.0 é um exemplo:** escolha uma tag já publicada e compatível nos pacotes `zynklog-api` e `zynklog-front`. A simulação confere somente a instalação local; não comprova que a versão exista no GHCR. Consulte as [notas de versão](https://zynklog.codifylabs.com.br/versoes) para saber qual versão está disponível e se a atualização exige mudanças além da troca de imagens.

Para atualizar, o terminal pede confirmação. O atualizador:

1. Confere serviços, containers existentes, projeto, volumes e versões. Recusa downgrade.
2. Baixa API e frontend antes da indisponibilidade. Se o download falhar, a instalação continua como estava.
3. Por padrão, para os serviços e arquiva todos os volumes nomeados, incluindo PostgreSQL, Redis, chaves e, no servidor, os volumes de certificados/configuração do Caddy, usando uma imagem da API já instalada como ferramenta. Salva Compose, `.env`, Caddyfile quando presente e identificação das imagens antigas junto ao backup.
4. Grava apenas as imagens de `init`, `api` e `web` em **compose.override.yaml**. O Compose original, as variáveis e as configurações não são editados. O override é carregado automaticamente nos próximos `docker compose up`/`pull` sem `-f`. Não o apague após atualizar. As versões do override prevalecem sobre as tags do Compose original e do `.env`.
5. Retoma os containers de infraestrutura existentes sem trocar suas imagens. Atualiza a API (que aplica migrations no startup) e só depois o frontend. Aguarda as verificações de saúde configuradas no Compose/imagens. Há indisponibilidade durante esse processo; saúde não equivale a testar todas as funcionalidades.

**Backup é recomendado, mas opcional:**

```bash
./zynklog update v1.1.0 --skip-backup
```

Para execução não interativa, acrescente `--yes`. Isso autoriza a atualização sem a pergunta do terminal. Não há atualização automática em segundo plano.

Os backups ficam em `backups/<data>-to-<versão>-<pid>/`, com permissões restritas. Contêm dados e credenciais: não publique nem envie para repositórios. O arquivo **COMPLETE** indica que todos os arquivos foram produzidos com sucesso; não substitui um teste de restauração. Backup parcial não recebe esse marcador. O backup físico exige as mesmas versões de PostgreSQL/Redis para restauração. Verifique espaço livre e faça também sua política de cópias externas.

## Compatibilidade

Quem já usa uma versão integrada ao Codify Control pode baixar o atualizador e rodar na pasta existente. Para habilitar o Codify Control em uma instalação legada da v1.0.1, prepare a migração de configuração antes de ativar a licença.

- Pacote distribuído com serviços `init`, `api`, `web`, `postgres`, `redis`, e `caddy` no servidor. Serviços persistentes devem estar em execução antes de começar. O atualizador também preserva volumes de versões anteriores.
- Exatamente um Compose base com nome padrão (`compose.yaml`, `compose.yml`, `docker-compose.yaml` ou `docker-compose.yml`).
- Imagens oficiais estáveis ou beta como origem e tag estável `vX.Y.Z` como destino, com uma instância por serviço.
- Dados persistentes em volumes Docker nomeados. O Caddy gerado pelo assistente pode montar somente o Caddyfile da própria pasta em `/etc/caddy/Caddyfile`; ele é copiado para o backup. Outras montagens personalizadas, overrides próprios e `COMPOSE_FILE` personalizado são recusados, sem sobrescrita.
- Somente atualizações de imagens que mantenham o contrato deste Compose. Uma versão que exija novos serviços, mudanças de ambiente ou de infraestrutura precisa de um procedimento específico; não basta mudar a tag.
- Não muda a versão do PostgreSQL/Redis, não remove volumes e não altera Jira, Confluence ou outro serviço externo. A atualização troca o código em execução; as rotinas habilitadas da aplicação voltam a funcionar quando ela iniciar.

## Se falhar

**Download ou verificação inicial:** nenhuma troca de imagem em execução foi feita. Corrija acesso ao GHCR/tag e tente novamente.

**Backup, antes de iniciar a API nova:** a instalação antiga é retomada com os containers existentes. O diretório parcial é preservado para diagnóstico. Se a retomada falhar, confira `docker compose ps`.

**Depois que a API nova começou a iniciar:** migrations podem ter sido aplicadas. O atualizador para API/frontend e mantém a configuração da versão nova. Não volta automaticamente a imagem antiga. Você pode corrigir o problema e executar novamente o mesmo comando, depois de retomar a instalação conforme o diagnóstico, ou restaurar um backup completo. Não trate a simples troca de tag como rollback do banco.

Inspecione:

```bash
docker compose ps
docker compose logs --tail=100 api web
```

Não compartilhe logs que contenham credenciais. O script não imprime segredos, `.env` ou o Compose resolvido.

Se o processo for encerrado abruptamente, pode restar `.zynklog-update.lock`. Antes de remover essa pasta, confirme que não existe outra atualização/backup em execução. Não execute atualizações concorrentes ou comandos Compose manuais durante o processo.

## Restauração manual de um backup completo

A restauração substitui os dados atuais. Escolha conscientemente um diretório com **COMPLETE**, confira `installation.txt`, os arquivos de configuração salvos e as imagens antigas. Não execute restauração automaticamente ao ocorrer um erro.

1. Pare os serviços. Use o mesmo projeto e os mesmos volumes anotados em `volumes.txt`; nunca use `down -v`.
2. Guarde uma cópia da configuração atual. Restaure o Compose, `.env` e override anteriores a partir do backup; se aquele backup não contiver override, remova o override gerado pelo atualizador. Variáveis do terminal também precisam corresponder à instalação anterior.
3. Restaure **todos** os arquivos de volumes do mesmo backup, com os serviços parados, em volumes vazios de recuperação e compatíveis. Não misture arquivos de PostgreSQL antigo e novo nem restaure apenas banco sem suas chaves.
4. Aponte o Compose para esses volumes de recuperação, confira as versões antigas registradas e inicie a instalação. Valide os dados antes de reabrir o acesso.

O atualizador fornece o ponto de recuperação, mas não oferece um comando destrutivo de restauração nesta versão.

Referência: [mesclagem e carregamento de overrides no Docker Compose](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/).

## Servidor instalado pelo assistente

O serviço opcional `caddy` usa volumes nomeados para certificados/configuração e monta o Caddyfile da pasta da instalação. Esses volumes são arquivados com os demais, com o proxy parado, e o Caddyfile é copiado junto às configurações. O proxy é retomado depois da API/frontend. Somente essa montagem de arquivo é aceita automaticamente; configurações próprias fora do layout gerado precisam de revisão manual.