# Definitions e Instances

Um template é a especificação de um serviço — abstrato, reutilizável. Para virar um container rodando, ele precisa de duas etapas intermediárias: uma definition e uma instance.

# Conceitos

# Definition

Uma definition é um template + inputs + profile + instance_uid. Representa a intenção de ter um serviço configurado de determinada forma neste host.

Template (memos)
      +
Inputs (WEB_HOSTNAME=memos.example.com)
      +
Profile (production)
      +
instance_uid (memos-blog-001)
      =
Definition "memos-blog-001"

A definition resolve todas as referências do template:

• ${input.WEB_HOSTNAME} → memos.example.com
• ${secrets.MARIADB_ROOT_PASSWORD} → gerado e persistido
• ${needs.database.host} → container do asset MariaDB
• ${instance.uid} → memos-blog-001

# Instance

Uma instance é a materialização da definition: um container rodando no Docker, com volumes, rede, healthcheck e labels.

Definition "memos-blog-001"
      ↓
docker create + docker start
      ↓
Instance (container_id: abc123…, status: running)

A regra é simples: uma instance por instance_uid. Tentar deployar o mesmo instance_uid duas vezes resulta em update da existente, não em duplicação.

# Inputs

Os inputs vêm de três fontes do bloco config do template:

O CLI oferece dois modos de fornecimento:

Wizard interativo — agrupa inputs por prefixo (MAIN_DB_*, WEB_*, SMTP_*), valida pattern e oferece ajuda inline com ?:

deployally deploy --species memos --instance-uid memos-blog-001

Flags inline — sem wizard, ideal para automação:

deployally deploy --species memos --instance-uid memos-blog-001 \
  --input WEB_HOSTNAME=memos.example.com \
  --input MEMOS_MODE=prod \
  --profile production \
  --apply

# Secrets

Secrets nunca aparecem no wizard. Eles são resolvidos por uma chain de providers declarada no template:

secrets:
  MARIADB_ROOT_PASSWORD:
    kind: password
    length: 32
    providers: [local, random]
    persist: true

A chain [local, random] significa: primeiro tenta ler de /opt/deployally/<uid>/secrets/MARIADB_ROOT_PASSWORD (provider local); se não existir, gera aleatório (provider random) e persiste. No próximo redeploy do mesmo instance_uid, o secret é reaproveitado — sem perder a senha do banco.

Outros providers disponíveis incluem vault, env e input (quando o usuário precisa fornecer o segredo, como uma chave de API externa).

# Profile

O profile é um override declarativo aplicado em cima da definition base. Mesmo template, sizing diferente:

profiles:
  development:
    overrides:
      resources.memory.limit: 128M
      config.optional.MEMOS_MODE.default: dev
  production:
    overrides:
      resources.memory.limit: 256M
      config.optional.MEMOS_MODE.default: prod

deployally deploy --species memos --instance-uid memos-blog-001 \
  --profile development \
  --apply

# Ciclo de Vida

┌─────────────┐
│   Template  │   (catálogo)
└──────┬──────┘
       │ deployally deploy --species X
       ▼
┌─────────────┐
│  Definition │   (template + inputs + profile + uid)
└──────┬──────┘
       │ --apply (resolve secrets, needs, cria recursos)
       ▼
┌─────────────┐
│   Instance  │   (container running)
└─────────────┘

# Multi-Tenancy: Per-Instance Provisioning

Quando uma aplicação declara needs de um asset, o asset dispatcher provisiona recursos isolados por instância. Exemplo do WordPress sobre MariaDB:

# wordpress.yaml
needs:
  database:
    class: relational
    options: [mariadb, mysql]
    per_instance:
      database: "wp_${instance.uid}"
      user:     "wp_${instance.uid}"
      password: ${secrets.WP_DB_PASSWORD}
      on_provision:    create_user_and_db
      on_decommission: drop_user_and_db

No deploy de uma instance WordPress, o dispatcher chama a function create_user_and_db declarada pela MariaDB (em provides.functions) passando db_name=wp_<uid>, user=wp_<uid> e password=<secret>. Resultado: uma MariaDB compartilhada, N WordPress isolados, cada um com seu próprio banco/usuário/senha.

Ver detalhes em Ecologia.

# Auto-Provision em Cascata

Se o asset declarado em needs ainda não existe no host, o flag --provision-missing-assets instrui o deploy a criá-lo automaticamente — primeira opção de needs.options, variant default: true, mesmo profile do consumer:

deployally deploy --species wordpress --instance-uid wp-blog-001 \
  --input WEB_HOSTNAME=blog.example.com \
  --provision-missing-assets \
  --apply

Sem esse flag, o deploy aborta exigindo o asset preexistente.

# Comandos

# Listar instances ativas
deployally list

# Detalhes de uma instance
deployally show memos-blog-001

# Logs em tempo real
deployally logs memos-blog-001 --follow

# Executar uma action declarada no template
deployally action memos-blog-001 restart

# Decommission (remove container + cleanup)
deployally remove memos-blog-001

# Próximos Passos

• Templates — Estrutura do template que origina a definition.
• Manifestos — Onde a instance persiste config rendered e secrets.
• Ecologia — Como needs e provides conectam apps e assets.