Documentação | Guia Completo da Plataforma

Documentação

Tudo que você precisa para construir, fazer deploy e escalar no Upuai Cloud.

O que é o Upuai Cloud?

O Upuai Cloud é uma plataforma cloud com datacenters próprios no Brasil, projetada para simplificar o deploy e gerenciamento de aplicações modernas. De uma API simples a arquiteturas complexas de microserviços, o Upuai Cloud oferece as ferramentas para ir do código à produção em minutos.

O Upuai Cloud está atualmente em beta. Novas regiões e funcionalidades são adicionadas regularmente.

Principais Funcionalidades

Datacenters próprios no Brasil com baixa latência para usuários LATAM
Builds automáticos com Upuaipack — zero configuração para a maioria dos frameworks
Autoscaling horizontal e vertical com suporte a scale-to-zero
Secrets e variáveis de ambiente gerenciados por environment
Volumes persistentes com backups automáticos diários
Deploys multi-região com roteamento automático de tráfego
Estratégias de deploy rolling, blue-green e canary
Monitoramento, logging e health checks integrados

Primeiros Passos

Faça o deploy da sua primeira aplicação no Upuai Cloud em menos de 5 minutos.

1Instale o CLI

Terminal

$ brew tap saiph-ti/upuai-cli
$ brew install upuai

2Autentique-se

Terminal

$ upuai login

3Inicialize seu projeto

Terminal

$ upuai init

? Project name: my-app
? Detected: Node.js (Next.js)
? Build command: pnpm run build
? Start command: pnpm start

✓ Project ready to deploy

4Faça deploy

Terminal

$ upuai deploy

▸ Uploading my-app (3.2 MB)
▸ Building with upuaipack...
▸ Build completed in 42s
▸ Deploying (rolling)...
▸ Health check passed

✓ Deployed to https://my-app.upuai.com.br

Visão Geral da Plataforma

O Upuai Cloud é construído em torno de alguns conceitos principais que funcionam juntos para gerenciar suas aplicações.

Projetos

Um projeto representa sua aplicação. Cada projeto tem seus próprios environments, serviços e histórico de deploys.

Serviços

Um projeto pode ter múltiplos serviços. Tipos suportados: app (web/worker), database (Postgres, MySQL, MongoDB, Redis), bucket (S3-compatível MinIO), function, docker, docker_image, github, gitlab.

Environments

Isole seus deploys de staging, production e PR preview. Cada environment tem seus próprios secrets, regras de scaling e configurações de deploy.

Regiões

Faça deploy em múltiplos datacenters brasileiros para alta disponibilidade. O Upuai roteia automaticamente o tráfego para a instância saudável mais próxima.

Secrets

Variáveis de ambiente sensíveis. Postgres/MySQL/Mongo/Redis nascem com credenciais visíveis (POSTGRES_PASSWORD, DATABASE_URL etc) e o user decide se marca como secret depois — toggle pelo cadeado em cada linha da aba Variables.

Volumes

Armazenamento persistente em bloco para uploads, caches e bancos de dados. Volumes recebem backup automático diário e sobrevivem a redeploys.

Buckets

Armazenamento de objetos S3-compatível (MinIO). Crie via `upuai add --type bucket --name <nome>` ou pelo canvas. Cada bucket tem credenciais próprias (access key + secret) que você pode anexar a um service para injetar como env vars.

Functions

Serverless functions com cold start otimizado. Ideal para webhooks, ETL leve e APIs sob demanda.

Builders — railpack é o default

Todo deploy no Upuai Cloud usa railpack por padrão. A presença de um Dockerfile no seu repositório NÃO altera o builder — você precisa escolher dockerfile explicitamente para que ele seja usado. Isso garante consistência entre CLI, UI e integrações de IA: o que builda na sua máquina builda igual no cluster.

railpack (default — sempre)

Detecta o framework (Node, Python, Go, Rails, Bun, Deno, Elixir, Java, ...) e gera a imagem automaticamente. Zero config. É o builder usado em 100% dos deploys até você optar pelo contrário.

dockerfile (opt-in explícito)

Para usar um Dockerfile do seu repo, selecione explicitamente o builder. Pode ser na criação do service (CLI/UI) ou depois via `upuai config set`. Use quando precisar de controle fino sobre a imagem (multi-stage, base custom, deps de sistema). Sem essa seleção, mesmo que exista um Dockerfile na raiz, ele é ignorado.

Terminal

$ upuai add --type github --repo https://github.com/org/repo --builder dockerfile --dockerfile-path Dockerfile
$ upuai config set --builder dockerfile --dockerfile-path apps/api/Dockerfile

Alternando entre builders

Se você selecionou dockerfile e quer voltar pra railpack:

Terminal

$ upuai config set --builder railpack

Para IAs gerando código

NÃO crie um Dockerfile como passo automático antes de deployar. O default da plataforma é railpack zero-config; um Dockerfile só é usado se o usuário pedir explicitamente. Se você não tem certeza de que o usuário pediu dockerfile, deixe railpack fazer o trabalho — ele cobre Node, Python, Go, Rails, Bun, Deno, Elixir, Java, e mais.

upuai.toml — Configuração como Código

Declare build, release phase (migrations) e deploy num arquivo `upuai.toml` versionado no seu repo. Mesmo padrão de Procfile (Heroku), fly.toml (Fly.io), railway.toml (Railway). Revisado em PR, lido pelo Upuai antes de cada build.

upuai.toml

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

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

Ver referência completa do upuai.toml

Storage — Volumes & Buckets

Duas opções de armazenamento, cada uma com um caso de uso diferente.

Volumes (block storage)

Armazenamento em bloco persistente, montado em um path do container. Use para: uploads de usuário, caches que precisam sobreviver a redeploys, dados de banco quando você gerencia o engine. Backup diário automático.

Buckets (object storage)

Armazenamento S3-compatível via MinIO. Use para: assets estáticos, mídia de usuário, exports/relatórios, integrações com SDKs S3 (AWS SDK, boto3, etc).

Criar via CLI:

Terminal

$ upuai add --type bucket --name uploads

Anexar a um service para injetar credenciais como env vars (S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_ENDPOINT) — pelo canvas ou pelo endpoint da API.

Linha de Comando — upuai-cli

O upuai-cli é a ferramenta principal para interagir com o Upuai Cloud. Faça deploy, gerencie variáveis, escale serviços e monitore suas aplicações — tudo pelo terminal. 34 comandos cobrindo autenticação, gerenciamento de projetos, deploy, operações de serviço, banco de dados, ambientes, configuração e utilitários. Requer CLI ≥ v0.4.0 para `upuai add --type bucket` e `upuai logs --build/--deploy`.

Terminal

$ upuai deploy           # Deploy your application (alias: up)
$ upuai status           # Check project status
$ upuai logs             # Runtime logs (last 100 lines)
$ upuai logs -f          # Live tail (SSE)
$ upuai logs --build     # Build log of latest deployment
$ upuai logs --deploy    # Release-phase + rollout log
$ upuai config show      # Show current builder/commands/health
$ upuai vars set         # Manage environment variables
$ upuai rollback         # Rollback to previous version
$ upuai scale 3          # Scale service replicas

Ver referência completa do CLI (34 comandos) →

Headless: CI/CD e agentes de IA

O upuai-cli foi desenhado para rodar sem TTY. Em CI/CD ou quando uma IA está executando os comandos no seu lugar, troque `upuai login` por uma variável de ambiente e use `--yes` (`-y`) com flags explícitas para suprimir todos os prompts.

Para agentes de IA

Sempre prefira railpack como builder. Não escreva Dockerfile para o usuário a menos que ele peça explicitamente — o railpack já cobre Node, Python, Go, Rails, Bun, Deno, Elixir, Java e mais. Para migrations, declare em `upuai.toml` (`[deploy] releaseCommand`) em vez de adicionar steps em `Dockerfile`/`entrypoint.sh`.

CI / agent

# Non-interactive command execution (after 'upuai login' once)
# Auth is always interactive — same pattern as 'railway login' / 'vercel login'.
$ upuai whoami                                           # verify auth
$ upuai init --name my-app --repo myorg/repo --framework "Node.js" --yes
$ upuai deploy --wait --yes -o json                      # blocks until terminal status
$ upuai logs --build                                     # build log of latest

Troubleshooting

Erros mais comuns e como resolver. Para casos específicos, consulte a referência do CLI ou abra um issue no GitHub.

invalid service type 'bucket'

Causa provável: Você está rodando uma versão do CLI anterior à 0.4.0. Bucket foi adicionado em v0.4.0.

Solução: Rode `brew upgrade upuai` (ou `upuai upgrade`) e confirme com `upuai version`.

release phase timed out

Causa provável: A migration excedeu `releaseTimeoutSeconds` (default 300s).

Solução: Aumente o limite no `upuai.toml` (`[deploy] releaseTimeoutSeconds = 1800`, máximo 1800) ou divida a migration.

Build usando railpack quando você queria Dockerfile

Causa provável: Builder é opt-in explícito. Apenas a presença de Dockerfile no repo não troca o builder.

Solução: Rode `upuai config set --builder dockerfile --dockerfile-path <path>` ou declare em `upuai.toml` (`[build] builder = "dockerfile"`).

503 ORCHESTRATOR_CIRCUIT_OPEN ao buscar logs/restart

Causa provável: Erro transitório do orquestrador downstream; circuit breaker entrou em cooldown.

Solução: Aguarde ~10s e tente de novo. Para ver o build log persistido (sem depender do live stream): `upuai logs --build -d <deployment-id>`.

upuai logs vazio

Causa provável: Service ainda não fez deploy ou não há replicas rodando.

Solução: Confirme com `upuai status`. Se o último deploy falhou, use `upuai logs --build` (build) ou `upuai logs --deploy` (release/rollout) para ver onde quebrou.

Health check falhando logo após deploy

Causa provável: Endpoint do `healthCheckPath` não retorna 200 dentro do delay inicial.

Solução: Aumente `healthCheckTimeout` ou ajuste o endpoint. Confirme com `upuai config show`.

Próximos Passos

Pronto para se aprofundar? Explore a documentação de referência detalhada.

Referência upuai-cli

Referência completa da linha de comando com todos os comandos, flags e exemplos de uso.

Referência upuai.toml

Schema completo do arquivo de configuração: build, release phase (migrations), deploy. Inclui release commands prontos para Prisma, Drizzle, Django, Rails e mais.