UpuaiUpuai
Documentação

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
  • Escala por réplicas e por CPU e memória de cada serviço, dentro do total do plano
  • Secrets e variáveis de ambiente gerenciados por environment
  • Volumes persistentes que sobrevivem a redeploys; bancos gerenciados com backup conforme a retenção do plano
  • Domínios próprios com certificado TLS emitido automaticamente
  • 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 sobrevivem a redeploys. Não há backup automático de volume — mantenha cópias próprias dos dados que importam; bancos gerenciados têm backup conforme a retenção do plano.

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. Sem backup automático de volume: quem gerencia o engine no volume é responsável pelas próprias cópias (os bancos gerenciados da plataforma têm backup conforme a retenção do plano).

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. Pessoas entram com `upuai login`. Em CI/CD, um dono ou admin do workspace cria uma vez um token escopado (`upuai token create`) e o pipeline o usa pela variável `UPUAI_TOKEN`, com `--yes` (`-y`) e flags explícitas para suprimir todos os prompts. O token opera recursos do projeto (deploy, serviços, variáveis); membros, cobrança e configurações do workspace continuam exigindo uma pessoa logada. Um token `--scope read` só lê: não altera nada, não abre shell no container e não lê credenciais de bucket.

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
# Once, by a person (workspace owner or admin), in a logged-in terminal:
$ upuai token create --name ci --scope deploy --project <project-id>

# In the pipeline: the token goes in a secret, never in the repository
$ export UPUAI_TOKEN=upua_...
$ upuai deploy -p <project> -s <service> -e production --wait --yes -o json

Serviço de imagem: todo deploy baixa a imagem de novo, então uma tag mutável (latest) só precisa de redeploy. Para trocar uma tag fixa, `upuai deploy --image <ref>` grava a imagem e faz o deploy num passo só. Exige o CLI v0.22.0+ — `unknown flag --image` significa binário antigo no runner. Este workflow confere o Docker Hub todo dia e só faz deploy quando existe versão nova:

.github/workflows/update-mailpit.yml
name: Update mailpit
on:
  schedule:
    - cron: '0 6 * * *'
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    env:
      UPUAI_TOKEN: ${{ secrets.UPUAI_TOKEN }}   # upuai token create --scope deploy --project <id>
      UPUAI_DISABLE_UPDATE_CHECK: '1'
      IMAGE: axllent/mailpit
    steps:
      - name: Install the Upuai CLI
        run: curl -fsSL https://raw.githubusercontent.com/saiph-ti/upuai-cli/main/install.sh | sh

      - name: Latest release tag on Docker Hub
        id: hub
        shell: bash   # -eo pipefail: a failed curl or an empty match stops the job
        run: |
          tag=$(curl -fsSL "https://hub.docker.com/v2/namespaces/axllent/repositories/mailpit/tags?page_size=100&ordering=last_updated" \
            | jq -r '.results[].name' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
          echo "image=$IMAGE:$tag" >> "$GITHUB_OUTPUT"

      - name: Image running on Upuai
        id: current
        shell: bash
        run: |
          current=$(upuai config show -p my-project -s mailpit -e production -o json | jq -er '.config.source.image')
          echo "image=$current" >> "$GITHUB_OUTPUT"

      - name: Deploy the new tag
        if: steps.hub.outputs.image != steps.current.outputs.image
        run: upuai deploy -p my-project -s mailpit -e production --image "${{ steps.hub.outputs.image }}" --wait --yes

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.

PostgreSQL gerenciado

PostGIS, pgvector e extensões ativadas pelo painel ou pela CLI sem reiniciar o banco, atualização de manutenção e troca de versão maior.

MySQL gerenciado

Conta de aplicação pronta, vários bancos na mesma instância, reparo e rotação de senha pelo painel ou pela CLI.