upuai.toml

O que é

upuai.toml é um arquivo de configuração declarativa que vive na raiz do rootDirectory do seu service no monorepo (ex: apps/api/upuai.toml). Permite declarar como o Upuai Cloud builda, faz release phase (rodar migrations antes do rollout) e inicia seu app — sem precisar mexer na UI.

Quick start

Para um app Node + Prisma rodando migrations automáticas a cada deploy, copie o snippet abaixo para apps/api/upuai.toml (ou upuai.toml na raiz, em single-package). Próximo deploy roda automaticamente.

#:schema https://upuai.com.br/schemas/upuai-toml-v1.json

[deploy]
releaseCommand = "pnpm exec prisma migrate deploy"

Schema v1 completo

Todas as keys são opcionais. Validação .strict() rejeita keys desconhecidas com erro explícito.

#:schema https://upuai.com.br/schemas/upuai-toml-v1.json

[build]
builder = "railpack"           # default; outro valor: "dockerfile"
buildCommand = "pnpm build"    # opcional, override do railpack
dockerfilePath = "Dockerfile"  # só pra builder = "dockerfile"

[deploy]
startCommand = "node dist/server.js"
releaseCommand = "pnpm exec prisma migrate deploy"
releaseTimeoutSeconds = 300    # default 300s, max 1800s
healthCheckPath = "/health"

Processos (Procfile App)

Declare múltiplos processos (web + worker + release + clock) a partir de um único repositório/build, no estilo Procfile do Heroku. Um push builda a imagem uma vez e roda N processos compartilhando essa imagem — cada um com seu próprio comando, réplicas e recursos. Variáveis de ambiente são compartilhadas por todos os processos (paridade Heroku config vars). Gerencie com `upuai ps`, `upuai scale web=2 worker=1` / `upuai logs --process worker` por processo, ou pela aba Processos no dashboard.

#:schema https://upuai.com.br/schemas/upuai-toml-v1.json

# 1 push → 1 build → N processos compartilhando a imagem (web + worker + ...).
[processes.web]
command = "bundle exec puma"

[processes.worker]
command = "bundle exec sidekiq"
type = "worker"      # opcional; inferido do nome (web→web, worker→worker, clock/cron→clock)
instances = 2        # opcional; default 1

[processes.release]
command = "bundle exec rails db:migrate"
type = "release"

Release Command por framework

Lista curated de commands recomendados. Explicit, sem mágica — copie pro seu upuai.toml.

Monorepo

Cada service tem seu próprio rootDirectory — coloque o upuai.toml em <rootDirectory>/upuai.toml. O rootDirectory é a working directory dos commands releaseCommand e startCommand: eles rodam como se você tivesse feito cd <rootDirectory> antes — sem precisar de pnpm --filter, cd, ou --prefix no command. Services que não precisam de release phase / build customizado simplesmente não criam o arquivo. Ausência = nenhum override.

my-monorepo/
├── apps/
│   ├── api/
│   │   ├── upuai.toml      # service "api" — releaseCommand pra migrations
│   │   └── src/
│   ├── web/
│   │   └── src/            # service "web" — sem upuai.toml (não precisa)
│   └── landing/
│       └── src/            # service "landing" — sem upuai.toml
└── pnpm-workspace.yaml

Precedência

Quando o mesmo campo aparece em mais de uma fonte, esta é a ordem de prioridade aplicada pelo Upuai.

1. 1

   UI (Service Settings)

   Vence sempre. Use para override operacional sem precisar de PR (ex: aumentar timeout em incident).

2. 2

   upuai.toml

   Config canonical, versionada, revisada em PR.

3. 3

   Procfile release: line

   Legacy compat Heroku-style. Continua suportado.

VS Code autocomplete

Adicione a primeira linha apontando para o JSON Schema público. Com a extensão Even Better TOML (tamasfe.even-better-toml), você ganha autocomplete e validação inline.

#:schema https://upuai.com.br/schemas/upuai-toml-v1.json

[deploy]
releaseCommand = "..."

Versioning

Schema segue SemVer. Mudanças backward-compat (novas keys opcionais) entram como v1.x sem mudar a URL. Breaking changes só num eventual v2 com janela mínima de 6 meses.

FAQ

Perguntas frequentes sobre upuai.toml.

Recursos

Links para o JSON Schema, CLI e outras referências.