# Instalação e Primeiro Deploy

Este guia leva você do zero ao primeiro container rodando em produção em cinco minutos.

# Pré-requisitos

• Servidor Linux x86_64 ou aarch64 com Docker 20.10+ instalado
• Acesso sudo ao servidor
• Container do Traefik já rodando (ou deploy do template traefik antes)
• Domínio resolvendo para o IP do servidor (para emissão automática de TLS)

# 1. Instalar o CLI

O instalador detecta a arquitetura automaticamente e instala o binário em /opt/deployally/ com symlink em /usr/local/bin/:

curl -fsSL https://get.deployally.com/init.sh | sudo bash

Para usar o canal de release candidate:

curl -fsSL https://get.deployally.com/init.sh | sudo bash -s -- --rc

# Verificar instalação

deployally --version

Saída esperada (a versão exata reflete o release atual):

deployally <versão>

# 2. Inspecionar o Catálogo

Para descobrir o que está disponível, valide qualquer template do catálogo. Por exemplo, memos:

deployally validate --species memos

A saída lista as seções declaradas no template (inputs requeridos, secrets que serão gerados, rotas HTTP, healthcheck) e termina com valid se tudo estiver consistente.

# 3. Primeiro Deploy

Vamos subir o Memos — um serviço de notas pessoais. É um template application simples, sem dependências externas.

deployally deploy \
  --species memos \
  --instance-uid memos-001 \
  --input WEB_HOSTNAME=memos.exemplo.com \
  --apply

Substitua memos.exemplo.com por um domínio real que aponta para o servidor.

# O que acontece

1. O CLI baixa o template memos do registry (ou usa cache local).
2. Roda o wizard para os inputs faltantes — neste caso, nenhum (já passamos WEB_HOSTNAME via flag).
3. Gera secrets automaticamente conforme o template declara (tokens hex, senhas).
4. Faz preflight de DNS para memos.exemplo.com.
5. Sobe o container com as labels do Traefik para roteamento HTTPS.
6. Aguarda o healthcheck retornar saudável.

# Verificar o deploy

docker ps --filter "label=ccs.systems/uid=memos-001"
curl -I https://memos.exemplo.com

O segundo comando deve retornar HTTP/2 200 (após o Traefik emitir o certificado Let's Encrypt, o que pode levar alguns segundos no primeiro acesso).

# 4. Deploy com Auto-Provisão

Aplicações como WordPress precisam de banco. O DeployAlly provisiona automaticamente o asset que faltar:

deployally deploy \
  --species wordpress \
  --instance-uid blog-001 \
  --input WEB_HOSTNAME=blog.exemplo.com \
  --input ADMIN_EMAIL=admin@exemplo.com \
  --provision-missing-assets \
  --apply

Se nenhum MySQL estiver rodando, o deployer:

1. Detecta a dependência (needs.options[0] declarado no template do WordPress).
2. Sobe um MySQL automaticamente com a primeira variante default.
3. Aguarda o asset ficar saudável (retry com backoff exponencial).
4. Sobe o WordPress conectado ao MySQL provisionado.

# 5. Profiles

Profiles ajustam recursos por ambiente (memória, CPU, tamanho de pool):

# Deploy com profile production (mais recursos)
deployally deploy --species memos \
  --instance-uid memos-prod \
  --input WEB_HOSTNAME=memos.exemplo.com \
  --profile production \
  --apply

Profiles disponíveis variam por template. Consulte a saída de deployally validate --species <X> para ver opções.

# 6. Dry-Run

Para ver o que seria feito sem aplicar nada:

deployally deploy --species memos \
  --instance-uid memos-001 \
  --input WEB_HOSTNAME=memos.exemplo.com \
  --dry-run

A saída mostra os containers que seriam criados, secrets que seriam gerados, networks e labels do Traefik — sem executar nada.

# 7. Atualizar o CLI

deployally self-update          # canal stable
deployally self-update --rc     # release candidate

O comando baixa a nova versão do CDN, valida (-V), substitui o binário e restaura o backup automaticamente se falhar.

# 8. Estrutura de Arquivos

Após o primeiro deploy, o DeployAlly mantém estado em:

/opt/deployally/
├── deployally               # binário
├── config.yaml              # configuração global (se aplicável)
└── manifests/               # manifests por instance
    └── <instance-uid>/
        ├── manifest.yaml    # spec rendered
        ├── secrets.json     # secrets gerados (chmod 600)
        └── config/          # arquivos config_file montados nos containers

# Próximos Passos

• Reflang Reference — escreva ou customize templates
• Referência CLI — todos os comandos e flags
• Templates — como funcionam os archetypes
• Ecologia de Serviços — como dependências são resolvidas

# Problemas Comuns

# "no running asset matched class X"

A aplicação declara dependência (needs) em um asset que não está rodando. Soluções:

# Subir o asset manualmente
deployally deploy --species mysql --instance-uid mysql-shared --apply

# Ou usar auto-provisão
deployally deploy --species wordpress --instance-uid blog-001 \
  --provision-missing-assets --apply

# "DNS preflight failed"

O domínio não resolve para o servidor. Verifique o registro A/AAAA antes de fazer deploy:

dig +short memos.exemplo.com

# "Docker not found"

Instale o Docker antes:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Para mais erros, veja Troubleshooting.