# Generator de `.deploy.yml` (v2.16.0+)

Quando voce roda runner add em um repo que nao tem .deploy.yml, o runner detecta o perfil do repositorio e gera o manifesto proporcionalmente.

Filosofia: auxiliar, nao fazer magica. Quanto mais o repo ja tem definido (Dockerfile, compose, .env), mais o runner ajuda. Quanto mais cru, mais o runner instrui voce a definir o config manualmente.

# Detecção de perfil

A detecção e baseada nos arquivos presentes na raiz do repo. O primeiro perfil que matchar ganha:

# Perfil A — Repo já preparado

runner add --repo user/app --branch main
# usa o .deploy.yml que ja existe no repo

Sem mudancas — comportamento igual a versoes anteriores.

# Perfil B — Containerizado completo

Repo com Dockerfile + algum sinal de envs (.env, .env.example, docker-compose.yml):

# Dockerfile no repo
FROM python:3.12-slim
EXPOSE 5000
ENV FLASK_ENV=production

# .env.example no repo
DB_HOST=mysql
DB_NAME=meudb
DB_PASSWORD=changeme   # auto-detectado como secret

runner add --repo user/app --branch main --ckey
# [generator] Profile B detected. Generating .deploy.yml from inputs: Dockerfile, .env.example

.deploy.yml gerado:

project: app
system: api
build:
  context: .
  dockerfile: Dockerfile
port: 5000
networks:
  - public
environment:
  DB_HOST: "mysql"
  DB_NAME: "meudb"
  FLASK_ENV: "production"
  DB_PASSWORD: "{{::DB_PASSWORD}}"  # auto-detected (sensitive) → vira prompt
healthcheck:
  mode: tcp                          # ← v2.18.2 W2: python:3.12-slim → TCP (genérico)
  tcp: 5000
  interval: 30s
version:
  source: git-commit                 # ← v2.18.2: deploys auto-versionados via SHA
instances:
  production:
    domain: app.example.com
    source:
      type: branch
      branch: main                   # ← v2.18.1: --branch propagado pra source.branch
    keep_versions: 3

Note como DB_PASSWORD virou placeholder com sintaxe de prompt — o runner detectou como sensivel via Aho-Corasick e sugere preenchimento via wizard.

# Perfil C — Dockerfile só

Repo com Dockerfile mas sem .env* ou compose:

runner add --repo user/app --branch main
# [generator] Profile C detected. Generating .deploy.yml from inputs: Dockerfile
# WARN [generator] Profile C: Dockerfile sem env detectado. Adicione `environment:`
#                  no .deploy.yml com as vars que sua app precisa antes de fazer deploy.

.deploy.yml gerado e parcial — voce precisa adicionar environment: manualmente. O runner avisa explicitamente. Nao tenta inventar variaveis.

# Perfil D — Compose só

Repo com docker-compose.yml mas sem Dockerfile:

# docker-compose.yml no repo
services:
  app:
    image: nginx:1.25
    ports:
      - "80:8080"
    environment:
      - LOG_LEVEL=info

runner add --repo user/app --branch main
# [generator] Profile D detected. Generating .deploy.yml from inputs: docker-compose.yml
# WARN [generator] Profile D: usando service 'app' do compose. Confira .deploy.yml gerado
#                  antes do deploy.

Generator usa o service app se existir, senao o primeiro. Extrai image, primeira porta de ports, e environment.

v2.19.0+: o bloco ports: no .deploy.yml continua funcionando (publish_strategy: explicit, default). Mas se o config global tem network.publish_strategy: random (ou sequential), o runner aloca porta livre automaticamente sem precisar ports: no manifesto — primeira deploy sorteia, depois sticky. Veja Referencia config.yml — network ou o exemplo end-to-end em Wizard por perfil.

# Perfil E — Cru (sem Docker)

Repo sem nenhum sinal de containerizacao:

runner add --repo user/app --branch main
# Error: no_deploy_yml: no_deploy_profile: repo sem perfil de deploy detectado.
#   Adicione um Dockerfile ou .deploy.yml no repo.
#   Documentação: https://docs.runner.ccs.systems/getting-started

Falha explicita — o runner nao tenta inventar config pra repo sem padrao. Voce precisa:

1. Adicionar um Dockerfile no repo (e fazer push), ou
2. Criar um .deploy.yml manualmente (use runner generate-config como template), ou
3. Forcar com --insecure (NAO RECOMENDADO — vai gerar config minimo invalido)

# Onde o gerado e salvo

Por padrao, o .deploy.yml gerado e salvo em /data/apps/{app}/.deploy.yml apos o runner add (mesmo lugar do manifesto normal). Voce pode editar apos a geracao.

Nota: O .deploy.yml gerado nao e commitado de volta no repo automaticamente. Se quiser persistir, copie pra raiz do repo e faca commit:

cp /data/apps/meu-app/.deploy.yml ~/repos/meu-app/.deploy.yml
cd ~/repos/meu-app && git add .deploy.yml && git commit -m "feat: add .deploy.yml" && git push

# Heuristicas de geracao

Detector de secrets (Aho-Corasick): keys como DB_PASSWORD, API_KEY, JWT_SECRET, AUTH_TOKEN viram placeholders em secrets: (futuro: ou {{::KEY}} no environment: se nao tiver secrets: section ainda).

# Quando NAO usar o generator

• Apps em producao: prefira commitar .deploy.yml no repo (perfil A). Geracao e pra prototipagem ou onboarding rapido.

• Layouts customizados: monorepo, source_dir especifico, etc — geracao nao cobre. Edite o .deploy.yml manualmente.

• Apps com healthchecks especificos: desde a v2.18.2 o generator escolhe healthcheck type-aware baseado na imagem (W2):

  • nginx*, caddy*, httpd*, apache*, traefik* → mode: http path: /
  • php-fpm*, *fpm* → mode: tcp (FastCGI, não HTTP)
  • node*, python*, ruby*, openjdk*, rust* → mode: tcp (genérico)
  • Outros → mode: tcp (fallback seguro)

  Se sua app tem endpoint custom (ex: /healthz, /api/v1/health) ou precisa de outro modo (cmd:, tcp: com porta diferente), edite o .deploy.yml gerado. Veja Sistema de Health Check pra detalhes.

# Bypass: `--insecure`

Em situacoes excepcionais voce pode forcar o registro mesmo sem Dockerfile/compose:

runner add --repo user/app --branch main --insecure

Isso suprime a falha do perfil E. NAO RECOMENDADO — voce vai precisar criar .deploy.yml manualmente antes do primeiro deploy. Veja --insecure.

# Veja Tambem

• Referencia .deploy.yml — schema completo do manifesto
• Env Wizard — sintaxe de prompts ({{::KEY?default}}) e generators ({RANDOM})
• runner generate-config — template completo manual
• --insecure — bypass de validacoes