# Manifestos

O manifesto é o estado local de uma instance no host. Ele guarda tudo o que o DeployAlly precisa para redeployar, atualizar ou recuperar o serviço sem perder configuração nem segredos.

Cada instance tem seu próprio diretório em:

/opt/deployally/<instance_uid>/

Esse diretório é o home da instance: persiste entre redeploys, é local ao host (nunca versionado em git) e contém só o que pertence àquela instância.

# Estrutura

/opt/deployally/<instance_uid>/
├── state.yaml              # Metadata da instance
├── secrets/                # Secrets persistidos (mode 0700)
│   ├── MARIADB_ROOT_PASSWORD     # 0600
│   ├── MARIADB_PASSWORD          # 0600
│   └── WP_DB_PASSWORD            # 0600
└── config/                 # Arquivos de config renderizados (bind-mount)
    ├── custom.cnf
    └── nginx.conf

# `state.yaml`

Metadata da instance — referência ao template, inputs aplicados, profile escolhido, IDs de containers e volumes criados, timestamps:

schema_version: "3"

instance:
  uid: memos-blog-001
  species: memos
  created_at: "2026-06-05T10:00:00Z"
  updated_at: "2026-06-05T10:00:00Z"

template:
  spec: "3"
  app_version: "0.22.0"
  archetype: application
  variant: stable

inputs:
  WEB_HOSTNAME: memos.example.com
  MEMOS_MODE: prod

profile: production

container:
  id: "a1b2c3d4e5f6…"
  name: memos-blog-001
  image: "neosmemo/memos:0.22.0"

storage:
  - id: data
    kind: volume
    docker_volume: memos-blog-001_data
    mount: /var/opt/memos

needs:
  database:
    asset_uid: mariadb-shared
    provisioned:
      database: wp_memos-blog-001
      user: wp_memos-blog-001

state:
  status: running
  health: healthy
  last_check: "2026-06-05T10:05:00Z"

# `secrets/`

Cada secret declarado no template ocupa um arquivo, com nome igual ao do secret e permissão 0600. O diretório secrets/ tem permissão 0700.

secrets/MARIADB_ROOT_PASSWORD   →   p4ssw0rd_s3cr3t0_d0_r00t
secrets/WP_DB_PASSWORD          →   aXc92kf…

Quando o template tem secrets.X.persist: true, o secret é gravado no primeiro deploy e reaproveitado em redeploys seguintes. Isso garante que a senha do banco não muda entre updates.

# `config/`

Quando o template tem storage com kind: config_file, o arquivo é renderizado aqui e bind-mountado no container. Cada redeploy regenera o arquivo a partir do template (resolvendo ${input.X}, ${secrets.X}, etc.) — então mudanças de configuração propagam automaticamente.

storage:
  - id: my-cnf
    kind: config_file
    mount: /etc/mysql/conf.d/custom.cnf
    content: |
      [mysqld]
      max_connections = ${input.MAX_CONNECTIONS}

Resultado no host: /opt/deployally/<uid>/config/custom.cnf (mode 0644), montado read-only em /etc/mysql/conf.d/custom.cnf dentro do container.

# Por que isso importa

# 1. Redeploy é idempotente

Rodar deployally deploy --species memos --instance-uid memos-blog-001 --apply duas vezes resulta no mesmo container, com os mesmos secrets, os mesmos volumes. O manifesto é a fonte da verdade.

# 2. Recuperação sem perder dados

Se o container some (acidente, limpeza, queda de host), o state.yaml permite reconstruir tudo: o volume Docker continua nomeado, os secrets continuam no disco, os inputs estão registrados. Basta redeployar.

# 3. Multi-tenant isolado

Cada instance tem seu próprio diretório. Dez WordPress sobre uma MariaDB compartilhada significam dez /opt/deployally/wp-* distintos, cada um com sua senha de DB exclusiva em secrets/WP_DB_PASSWORD.

# 4. Auditoria

state.yaml registra qual app_version, qual variant e quais inputs geraram aquele container. Quem subiu, quando, com qual config — tudo rastreável sem inspeção do container.

# Permissões

O processo do container roda como o usuário definido pela imagem; bind-mounts são read-only por padrão.

# O que NÃO está no manifesto

• Não está versionado em git. O diretório /opt/deployally/ é local ao host e contém secrets — nunca commitar.
• Não está em outro lugar. O DeployAlly não sincroniza manifestos para cloud por padrão.
• Não há cópia remota dos secrets. Se você perder o disco do host sem backup, os secrets se vão.

# Backup

A responsabilidade de backupear /opt/deployally/ é do operador. Recomendado:

# Backup de todos os manifestos do host
tar -czf deployally-manifests-$(date +%F).tar.gz /opt/deployally/

# Restore
tar -xzf deployally-manifests-YYYY-MM-DD.tar.gz -C /

O BackupAlly (componente do ecossistema CCS) faz isso automaticamente quando configurado, respeitando as tags de backup declaradas no storage de cada template (backup.tag: critical, backup.frequency: hourly, backup.retain: 168).

# Próximos Passos

• Definitions e Instances — Como inputs viram secrets e o manifesto é populado.
• Templates — Como o template declara storage, secrets e config.
• Ecologia — Como instances multi-tenant compartilham assets.