veloz.json

O veloz.json é o arquivo de configuração do seu projeto na Veloz. Ele é gerado automaticamente no primeiro veloz deploy e fica na raiz do repositório.

Importante: Nunca crie o veloz.json manualmente. Rode veloz deploy e a CLI gera o arquivo com os IDs corretos do servidor. Criar manualmente resulta em IDs inválidos e deploy quebrado. Após gerado, você pode editar campos como build, runtime, size, etc. — mas nunca os campos id.

Exemplo básico

Para um projeto simples (um único app):

{
  "version": "1.0",
  "project": {
    "id": "proj_abc123",
    "name": "meu-app"
  },
  "services": {
    ".": {
      "id": "svc_xyz789",
      "name": "meu-app",
      "type": "web",
      "root": ".",
      "branch": "main",
      "build": {
        "command": "next build"
      },
      "runtime": {
        "command": "next start",
        "port": 3000
      }
    }
  }
}

Exemplo monorepo

Para projetos com múltiplos apps:

{
  "version": "1.0",
  "project": {
    "id": "proj_abc123",
    "name": "meu-projeto"
  },
  "defaults": {
    "build": {
      "nodeVersion": "22",
      "packageManager": "pnpm"
    },
    "resources": {
      "cpu": "500m",
      "memory": "512Mi"
    }
  },
  "services": {
    "apps/web": {
      "id": "svc_web123",
      "name": "web",
      "type": "web",
      "root": "apps/web",
      "build": {
        "command": "next build"
      },
      "runtime": {
        "command": "next start",
        "port": 3000
      }
    },
    "apps/api": {
      "id": "svc_api456",
      "name": "api",
      "type": "web",
      "root": "apps/api",
      "build": {
        "command": "tsc"
      },
      "runtime": {
        "command": "node dist/index.js",
        "port": 8080
      }
    }
  }
}

Referência de campos

version

Versão do schema. Sempre "1.0".

"version": "1.0"

project

Informações do projeto na Veloz.

services

Mapa de serviços. A chave é o caminho relativo do serviço (. para raiz, apps/web para monorepo).

defaults

Configurações padrão aplicadas a todos os serviços. Valores definidos no serviço individual sobrescrevem os defaults.

"defaults": {
  "type": "web",
  "branch": "main",
  "build": { ... },
  "runtime": { ... },
  "resources": { ... }
}

Configuração de serviço

Cada serviço aceita os seguintes campos:

Campos básicos

root — diretório raiz do serviço

Define onde o código-fonte do serviço está no repositório. Em projetos simples, é "." (raiz). Em monorepos, aponta para o subdiretório do serviço (ex: "apps/api").

O root é usado pelo sistema de build para localizar o código do serviço. Quando build.method é "dockerfile", o campo build.context herda o valor de root se não for definido explicitamente — ou seja, o Docker build context será o mesmo diretório do serviço.

Se o seu Dockerfile precisa acessar arquivos fora do diretório do serviço (ex: pacotes compartilhados na raiz do monorepo), defina build.context separadamente:

{
  "root": "apps/api",
  "build": {
    "method": "dockerfile",
    "dockerfile": "apps/api/Dockerfile",
    "context": "."
  }
}

Nesse exemplo, root indica que o serviço vive em apps/api, mas o Docker build context é a raiz do repo ("."), permitindo COPY de qualquer diretório.

Tipos de Serviço

Workers são ideais para:

• Filas de jobs (BullMQ, Agenda)
• Cron jobs (node-cron)
• Consumidores de mensagens (Kafka, RabbitMQ)
• Pipelines de dados

{
  "services": {
    "workers/email": {
      "name": "email-worker",
      "type": "worker",
      "runtime": {
        "command": "npx tsx worker.ts"
      }
    }
  }
}

build

Configuração de build. A Veloz suporta dois métodos de build:

Método de build: nixpacks (padrão)

Por padrão, a Veloz usa nixpacks para auto-gerar um Dockerfile a partir do seu código. Para projetos simples ou quando o nixpacks funciona de primeira, não é necessário configurar nada.

"build": {
  "command": "npm run build",
  "nodeVersion": "22",
  "packageManager": "pnpm",
  "outputDir": ".next",
  "aptPackages": ["ffmpeg", "libvips-dev"]
}

Método de build: dockerfile

Para projetos com requisitos complexos de build, é preferível usar seu próprio Dockerfile para builds mais confiáveis e reproduzíveis. Se o projeto tem dependências do sistema, multi-stage builds, ou precisa de controle total sobre o ambiente, use method: "dockerfile".

"build": {
  "method": "dockerfile",
  "dockerfile": "docker/Dockerfile.prod",
  "context": "."
}

• dockerfile — caminho relativo ao Dockerfile a partir da raiz do projeto
• context — diretório de contexto do Docker build (onde os COPY resolvem). Se omitido, usa o valor de root do serviço. Defina explicitamente quando precisar de um contexto diferente do root (ex: "." para acessar a raiz do monorepo)

Quando usar cada método

Pacotes do sistema (aptPackages)

Use aptPackages (apenas com nixpacks) para instalar pacotes do sistema operacional que seu app precisa durante o build ou em runtime. Os nomes seguem a convenção de pacotes Ubuntu/Debian.

"build": {
  "aptPackages": ["ffmpeg", "libvips-dev"]
}

Regras de nomenclatura:

• Apenas letras minúsculas, números, ., + e -
• Mínimo 2 caracteres
• Deve começar com letra ou número
• Exemplos válidos: ffmpeg, libvips-dev, g++, python3.11
• Exemplos inválidos: FFmpeg, my package, pkg=1.0

Para a lista completa de pacotes e exemplos por caso de uso, veja o guia Pacotes do Sistema.

runtime

Configuração de execução.

"runtime": {
  "command": "node server.js",
  "preStartCommand": "npx prisma migrate deploy",
  "port": 8080,
  "healthCheck": {
    "path": "/health",
    "interval": 15,
    "timeout": 5
  }
}

preStartCommand — comando pré-start

O preStartCommand é executado antes do serviço iniciar, em cada deploy. É ideal para:

• Migrations de banco de dados — npx prisma migrate deploy, npx drizzle-kit migrate, python manage.py migrate
• Seed de dados — node scripts/seed.js
• Cache warmup — node scripts/warm-cache.js

O comando roda no mesmo ambiente do serviço (mesma imagem, mesmas variáveis de ambiente, mesmo acesso a volumes). Se o comando falhar (exit code ≠ 0), o deploy é interrompido e marcado como falha.

"runtime": {
  "command": "node server.js",
  "preStartCommand": "npx prisma migrate deploy"
}

Também pode ser configurado via CLI:

veloz config set --pre-start "npx prisma migrate deploy"

env

Declaração de variáveis de ambiente. Apenas as chaves e metadados ficam no veloz.json — os valores são definidos via CLI ou dashboard e nunca aparecem no arquivo.

"env": {
  "DATABASE_URL": {
    "description": "URL de conexão com o banco PostgreSQL",
    "required": true,
    "example": "postgres://user:pass@host:5432/db"
  },
  "REDIS_URL": {
    "description": "URL do Redis para cache",
    "required": false
  }
}

Isso serve como documentação viva das variáveis que o app precisa.

resources

Limites de CPU, memória e scaling.

"resources": {
  "instances": 2,
  "cpu": "1",
  "memory": "1Gi",
  "autoscale": {
    "enabled": true,
    "minInstances": 1,
    "maxInstances": 5,
    "targetCPU": 70
  }
}

Autoscale

databases

Bancos de dados gerenciados. Cada chave é o nome do banco.

"databases": {
  "postgres": {
    "engine": "postgresql",
    "version": "16",
    "storage": "20Gi",
    "size": "turbo",
    "pooler": {
      "enabled": true,
      "poolMode": "transaction"
    }
  }
}

Ao executar veloz deploy, o CLI detecta alterações e atualiza automaticamente bancos existentes — tamanho (size), configurações do pooler e armazenamento (só cresce, nunca diminui).

Para mais detalhes, veja a documentação de bancos de dados.

Validação

O veloz.json é validado automaticamente em cada deploy. Para validar manualmente, use o JSON Schema:

{
  "$schema": "https://onveloz.com/schemas/veloz-config.schema.json"
}

Adicione o campo $schema no topo do arquivo para ter autocomplete e validação no VS Code e Cursor.

Dicas

• Não edite ids manualmente — eles são gerados pela Veloz e vinculam seu projeto/serviço ao servidor
• Commite o veloz.json — ele deve ser versionado no Git para que toda a equipe use a mesma config
• Use defaults em monorepos para evitar repetição entre serviços
• null = auto-detectar — use null em build.command ou runtime.command para deixar a Veloz detectar automaticamente

Próximos passos

• Pacotes do Sistema — Instalar ffmpeg, Puppeteer, sharp, etc.
• Monorepo — Deploy de múltiplos apps
• Configuração — Editar config via CLI
• Variáveis de Ambiente — Gerenciar secrets