# Runbook de Restauracao no Servidor do Cliente

**Status:** Operacional
**Ultima revisao:** 2026-06-20
**Documento normativo relacionado:** [Fluxo Administrativo de Exportacao e Migracao](./admin-export-migration-flow.md)

> Este runbook descreve como restaurar, no servidor final do cliente, um `pacote de migracao privada` gerado pelo CMS. O objetivo e executar a entrega com previsibilidade operacional, sem reaproveitar segredos do ambiente de origem e com validacoes suficientes para detectar falhas antes da entrada em producao.

## 1. Quando usar

Use este procedimento em um dos cenarios abaixo:

1. entrega inicial do CMS/API privada no ambiente do cliente;
2. restauracao controlada de backup administrativo em ambiente privado do cliente;
3. recuperacao de ambiente apos falha operacional, desde que o pacote tenha sido validado previamente.

Este runbook cobre apenas a restauracao do ambiente privado (`cms/`, `api/`, banco e `uploads/`). A publicacao do frontend publico deve acontecer depois, conforme o fluxo de entrega descrito em [admin-export-migration-flow.md](./admin-export-migration-flow.md).

## 2. Entradas obrigatorias

Antes de iniciar, o operador deve ter:

- pacote de migracao privada no formato canonico `tar.gz`;
- checksum SHA-256 do pacote;
- acesso SSH ao servidor do cliente;
- credenciais locais do banco de destino;
- segredos locais que **nao** podem ser herdados da origem;
- janela de manutencao aprovada, quando a restauracao afetar ambiente ja existente;
- local definido para armazenar backup preventivo e logs da operacao.

## 3. Pre-flight obrigatorio

Validar todos os itens abaixo antes de extrair o pacote:

- versao do PHP compativel com a instalacao do projeto;
- extensao `pdo_mysql` disponivel;
- espaco livre suficiente para:
  - pacote compactado;
  - extracao temporaria;
  - backup preventivo;
  - `uploads/` restaurado;
- conectividade entre aplicacao e banco de destino;
- usuario do processo web com permissao de leitura/escrita nos diretorios privados;
- ausencia de outra restauracao ou deploy concorrente;
- possibilidade de ativar modo de manutencao ou isolamento operacional durante a janela.

## 4. Estrutura de trabalho recomendada no servidor

Definir um diretorio temporario exclusivo por execucao, por exemplo:

```bash
export RESTORE_ROOT=/var/tmp/cms-restore-20260620T210000Z
mkdir -p "$RESTORE_ROOT"
```

Sugestao de subpastas:

- `$RESTORE_ROOT/package`
- `$RESTORE_ROOT/extracted`
- `$RESTORE_ROOT/backup-before-restore`
- `$RESTORE_ROOT/logs`

Nao reutilize diretorio de execucao entre restauracoes diferentes.

## 5. Validacao inicial do pacote

1. Copiar o pacote para `$RESTORE_ROOT/package`.
2. Validar o checksum recebido:

```bash
cd "$RESTORE_ROOT/package"
sha256sum -c pacote.sha256
```

3. Extrair o pacote em diretorio isolado:

```bash
tar -xzf migration-package.tar.gz -C "$RESTORE_ROOT/extracted"
```

4. Confirmar a presenca minima dos artefatos esperados:

- `manifest.json`
- `database/schema.sql`
- `database/data.sql`
- `uploads/`
- `config/cms-config.redacted.php`
- `config/restore.env.example`
- `checksums/sha256sums.txt`
- `reports/export-report.json`

5. Validar os checksums internos do pacote:

```bash
cd "$RESTORE_ROOT/extracted/migration-package"
sha256sum -c checksums/sha256sums.txt
```

Se qualquer checksum falhar, interrompa a execucao. Nao tente restaurar parcialmente.

## 6. Validacoes de compatibilidade

Ler `manifest.json` e confirmar manualmente, no minimo:

- versao esperada do CMS;
- formato do pacote;
- `project_mode`;
- prefixo das tabelas;
- timezone declarada;
- escopo exportado;
- data da exportacao;
- avisos emitidos no `export-report.json`.

Bloquear a restauracao quando houver qualquer uma destas condicoes:

- versao minima do CMS maior que a instalada no destino;
- modulo exigido pelo pacote ausente no destino;
- prefixo de tabela incompativel sem plano explicito de remapeamento;
- `project_mode` diferente do ambiente que sera entregue;
- pacote incompleto ou adulterado.

## 7. Mapeamento de configuracao local

Antes de tocar no banco ou nos arquivos do ambiente atual, preencher os valores locais que **substituirao** placeholders da origem:

- host do banco;
- porta do banco;
- nome do banco;
- usuario do banco;
- senha do banco;
- prefixo de tabelas, quando suportado;
- `app_url`, `siteUrl` e hostnames canonicos do cliente;
- segredos de sessao e quaisquer chaves privadas locais;
- caminhos locais de `uploads/`, cache e storage temporario;
- configuracoes de SMTP, CDN, bucket ou integracoes externas do cliente.

Regra operacional:

- nunca promover `config.php` da origem diretamente para producao;
- usar `cms-config.redacted.php` apenas como referencia estrutural;
- reconstruir o arquivo final do destino com os segredos locais.

## 8. Backup preventivo do destino

Se o ambiente ja existir, executar backup preventivo antes de sobrescrever qualquer coisa:

1. gerar dump logico do banco atual;
2. compactar `uploads/` atual;
3. preservar a configuracao atual;
4. registrar data/hora UTC e local dos backups em `$RESTORE_ROOT/logs`.

Exemplo generico:

```bash
mysqldump --single-transaction --routines --triggers \
  -h "$DB_HOST" -P "$DB_PORT" -u "$DB_USER" -p"$DB_PASSWORD" \
  "$DB_NAME" > "$RESTORE_ROOT/backup-before-restore/database-before.sql"

tar -czf "$RESTORE_ROOT/backup-before-restore/uploads-before.tar.gz" /caminho/do/uploads
cp /caminho/do/config.php "$RESTORE_ROOT/backup-before-restore/config-before.php"
```

Se o backup preventivo falhar, interrompa a restauracao.

## 9. Sequencia de restauracao

### 9.1 Entrar em modo de manutencao

- suspender jobs agendados e automacoes que escrevam no banco;
- impedir edicoes no CMS durante a operacao;
- quando aplicavel, exibir pagina de manutencao administrativa.

### 9.2 Preparar configuracao local

1. gerar ou editar o `config.php` do destino com os valores locais definidos na secao 7;
2. validar sintaxe do arquivo antes de prosseguir.

Exemplo:

```bash
php -l /caminho/do/cms/config.php
```

### 9.3 Restaurar schema e dados

1. garantir que o banco de destino esta apontando para a instancia correta;
2. aplicar `schema.sql`;
3. aplicar `data.sql`;
4. validar se o prefixo de tabelas restaurado corresponde ao prefixo configurado no destino.

Exemplo generico:

```bash
mysql -h "$DB_HOST" -P "$DB_PORT" -u "$DB_USER" -p"$DB_PASSWORD" \
  "$DB_NAME" < "$RESTORE_ROOT/extracted/migration-package/database/schema.sql"

mysql -h "$DB_HOST" -P "$DB_PORT" -u "$DB_USER" -p"$DB_PASSWORD" \
  "$DB_NAME" < "$RESTORE_ROOT/extracted/migration-package/database/data.sql"
```

Se o ambiente de destino nao estiver vazio, a estrategia de sobrescrita deve estar decidida antes da execucao. Nao improvise `DROP`, `TRUNCATE` ou rename de tabelas no meio da janela sem registro da decisao.

### 9.4 Sincronizar `uploads/`

Restaurar a arvore `uploads/` do pacote para o caminho privado configurado no destino. Preferir copia preservando estrutura e horario.

Exemplo:

```bash
rsync -a "$RESTORE_ROOT/extracted/migration-package/uploads/" /caminho/do/uploads/
```

Validar ao final:

- dono/grupo corretos para o processo web;
- ausencia de arquivos parcialmente copiados;
- volume restaurado coerente com o manifesto.

### 9.5 Ajustes finais de configuracao

Revisar configuracoes sensiveis ao ambiente:

- URLs canonicas;
- endpoint publico da API;
- politicas de cache;
- integracoes de email;
- path de sessao;
- storage local/remoto;
- qualquer segredo nao exportado.

## 10. Verificacoes pos-restauracao

Executar, no minimo, o checklist abaixo antes de liberar o ambiente:

1. `php -l` do `config.php` final sem erros.
2. Conexao do CMS com o banco funcional.
3. Endpoint de readiness da API, quando existir, respondendo com sucesso.
4. Login administrativo valido com usuario autorizado.
5. Leitura de conteudo basico pela API publica (`/api/v1`).
6. Leitura de ao menos um arquivo restaurado em `uploads/`.
7. Confirmacao de que `siteUrl`, canonical e hostnames publicos apontam para o dominio final do cliente.
8. Revisao de permissoes de arquivos criticos.
9. Ausencia de referencias obrigatorias ao hostname da origem.

Checklist minimo sugerido:

```bash
php /caminho/do/cms/public/index.php >/dev/null
curl -I https://cliente.exemplo.com/api/v1
curl -I https://cliente.exemplo.com/caminho/de/media-critica.jpg
```

Se qualquer validacao critica falhar, nao encerre a janela como concluida.

## 11. Criterios de rollback

Acionar rollback quando ocorrer qualquer um destes eventos:

- falha de importacao do banco sem resolucao imediata e segura;
- incompatibilidade estrutural descoberta apos alteracao irreversivel;
- `uploads/` inconsistente ou corrompido;
- aplicacao sobe, mas nao autentica ou nao le dados essenciais;
- configuracao final aponta para recursos errados do cliente sem correcao de baixo risco na mesma janela.

Sequencia minima de rollback:

1. recolocar o ambiente em manutencao;
2. restaurar `config.php` anterior;
3. restaurar dump preventivo do banco;
4. restaurar snapshot/arquivo de `uploads/` anterior;
5. repetir as validacoes minimas no estado restaurado;
6. registrar causa, ponto de falha e proxima acao.

## 12. Evidencias que devem ser registradas

Ao final da operacao, registrar em relatorio interno ou ticket:

- identificador do pacote restaurado;
- hash SHA-256 validado;
- horario UTC de inicio e fim;
- operador responsavel;
- hostname final atendido;
- estrategia usada para restaurar banco e `uploads/`;
- resultado das verificacoes pos-restauracao;
- local do backup preventivo;
- decisao final: sucesso, rollback ou pendencia.

## 13. Armadilhas operacionais comuns

- restaurar `config.php` da origem com segredos errados;
- validar somente homepage e esquecer API, login e media;
- sobrescrever `uploads/` sem backup preventivo;
- ignorar prefixo de tabelas diferente do ambiente final;
- concluir a entrega sem revisar referencias absolutas ao ambiente antigo;
- misturar restauracao do ambiente privado com publicacao do bundle publico na mesma etapa sem checklist separado.

## 14. Resultado esperado

Ao concluir este runbook com sucesso, o ambiente privado do cliente deve estar:

- com banco restaurado e coerente com o pacote;
- com `uploads/` sincronizado;
- com configuracao recomposta usando segredos locais;
- pronto para receber a etapa posterior de publicacao do bundle publico.