# Troubleshooting

Soluções para os erros mais frequentes em deploys com DeployAlly.

# Validação de Template

# "validation failed: missing required input"

Error: validation failed
  - inputs.required: WEB_HOSTNAME has no default and no value provided

Causa: Template declara um input obrigatório que não foi passado via --input nem respondido no wizard.

Solução:

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

Para descobrir todos os inputs requeridos:

deployally validate --species memos

# "validation failed: archetype unknown"

Error: archetype "applikation" is not valid

Causa: Typo no campo archetype do template. Apenas seis valores são aceitos: application, asset, static, worker, multi_component_saas, network_appliance.

Solução: Corrija para um dos archetypes oficiais. Veja Templates.

# Auto-Provision

# "no running asset matched class X"

Error: needs.options[0] requires asset class "mysql"
  No running container has label ccs.systems/asset_class=mysql

Causa: A aplicação declara dependência em um asset que não está disponível no servidor.

Soluções:

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

# Ou usar auto-provisão (recomendado)
deployally deploy --species wordpress --instance-uid blog-001 \
  --input WEB_HOSTNAME=blog.exemplo.com \
  --provision-missing-assets --apply

# "auto-provision: asset image variant not found"

Error: variant "mysql-8.4" not declared in template "mysql"

Causa: O template do consumer declara um variant específico do asset que não existe no template do asset.

Solução: Use o variant default omitindo --variant, ou ajuste o template do consumer para referenciar um variant válido.

# DNS e TLS

# "DNS preflight failed"

Error: DNS preflight failed for memos.exemplo.com
  Expected A record pointing to <server-ip>, got nothing

Causa: O domínio não tem registro A apontando para o servidor onde o deploy está rodando. Sem isso, Let's Encrypt não emite certificado e o Traefik responde com cert default (404).

Solução:

# Verificar resolução do domínio
dig +short memos.exemplo.com

# Se vazio, configure no DNS antes:
#   memos.exemplo.com  A  <ip-do-servidor>

# Aguardar propagação e refazer deploy

# Container sobe, mas Traefik responde 404

Causa: As labels do Traefik foram emitidas mas o cert resolver não casa com o configurado no Traefik (alias diferente, certresolver com nome customizado, etc.).

Solução: O DeployAlly usa um cert resolver canônico (tls.certresolver). Confirme que o Traefik foi configurado com esse mesmo nome de resolver. Se você customizou, ajuste a configuração do Traefik para alinhar — ou use o template traefik do catálogo, que já vem pronto.

# Containers

# "Port already in use"

Error: bind: address already in use (port 3306)

Causa: Outro processo no host está ocupando a porta. Comum quando outro container ou serviço systemd já roda na mesma porta.

Solução:

# Descobrir o que está usando
sudo ss -tulpn | grep 3306

# Parar o conflitante (exemplo: mysql systemd)
sudo systemctl stop mysql

# Refazer deploy
deployally deploy --species mysql --instance-uid mysql-001 --apply

# Container "unhealthy" após deploy

Container is running but healthcheck failed: exit code 1

Causa: O serviço dentro do container não atende o comando declarado em healthcheck. Comum em apps que demoram pra inicializar (banco fazendo migração, postal subindo workers).

Diagnóstico:

# Ver logs do container
docker logs <container-id>

# Ver detalhe do healthcheck
docker inspect <container-id> --format '{{json .State.Health}}' | jq

Solução: Se o serviço estiver subindo normalmente mas demora, aumente o start_period no template. Se o erro for de configuração, corrija o input correspondente.

# Container reiniciando em loop

Causa: O processo principal está crashando antes do healthcheck conseguir rodar — geralmente erro de configuração ou variável de ambiente inválida.

Solução:

# Ver os últimos logs
docker logs --tail 100 <container-id>

# Ver o exit code do último restart
docker inspect <container-id> --format '{{.State.ExitCode}}'

Comum: secret esperando formato específico (ex: RAILS_SECRET_KEY precisa ser 128 hex chars). Verifique o template e confirme que o input/secret está sendo gerado corretamente.

# Reflang

# "reflang: undefined variable"

Error: ${input.MYSQL_PORT} is not defined

Causa: Template referencia um input que não está declarado em inputs.required, inputs.optional ou inputs.advanced.

Solução: Declare o input no template ou use um valor literal. Para substituição com fallback:

port: ${default(input.MYSQL_PORT, 3306)}

# "reflang: provider chain exhausted"

Error: secret DB_PASSWORD has no value (tried: input, env, generate)

Causa: A cadeia de providers do secret não retornou nenhum valor. Comum quando o template depende de um input que não foi passado e não tem generate: como fallback.

Solução: Adicione fallback generate: no secret:

secrets:
  DB_PASSWORD:
    provider: input
    generate:
      type: hex
      length: 32

# Substituição aninhada não funciona

Sintaxe correta para indireção: ${input.${SLUG_UPPER}_DOMAIN} — o motor resolve o ${SLUG_UPPER} primeiro, depois acessa input.<resultado>_DOMAIN. Templates antigos com sintaxe diferente devem ser migrados.

# API e Conexão

# "401 Unauthorized" na API

Error: API returned 401 Unauthorized

Causa: API key inválida, revogada ou em ambiente errado (test vs prod).

Solução:

1. Verifique se o header é Authorization: Bearer da_xxx
2. Para ambiente de teste, use key com prefixo da_test_ em dev.sys.deployally.com
3. Crie nova key no dashboard: Configurações → API Keys

# "Failed to connect to API"

Error: connection refused

Causa: Servidor indisponível, firewall bloqueando, ou DNS não resolve.

Diagnóstico:

curl -I https://sys.deployally.com/api/v1/health
dig sys.deployally.com

# Logs e Debug

# Habilitar logs verbose

RUST_LOG=debug deployally deploy --species memos \
  --instance-uid memos-001 --apply

# Conferir o manifest renderizado

cat /opt/deployally/manifests/<instance-uid>/manifest.yaml

O manifest mostra a spec após todas as substituições da Reflang aplicadas — útil para entender exatamente o que foi mandado pro Docker.

# Testar conectividade Docker

docker info
docker network ls

# Suporte

Se o problema persistir:

1. Colete a saída de deployally validate --species <X> e os logs do container afetado
2. Confira a FAQ
3. Abra issue em github.com/devborlot/deployally-client
4. Email: suporte@deployally.com