The nubicloud.yaml manifest

The nubicloud.yaml describes what you want, not how to do it. You list your services and your databases; the platform takes care of the build, the provisioning, the wiring and the deployment order.

General structure

version: "1"          # format version (currently "1")
name: my-app          # stack name (optional)

databases:            # managed databases (optional)
  - name: db
    type: postgres

services:             # at least one service (required)
  - name: api
    type: web
    image: my-registry/api:1.0
    port: 8000

envGroups:            # variables shared between services (optional)
  common:
    LOG_LEVEL: info

ℹ️ Names (services, databases, groups) must be lowercase, made of letters, digits and dashes, and start with a letter (40 characters max). Services and databases share the same namespace: two blocks cannot have the same name.

services[]

A service = an application that runs.

⚠️ build or image, never both, never neither. That choice determines whether the block goes through a build phase.

The four service types

- name: cleanup
  type: cron
  schedule: "0 2 * * *"        # every day at 2 am
  image: my-registry/tools:1.0
  command: ["python", "cleanup.py"]

build

To use when the platform must build the image from your repository.

- name: front
  type: web
  framework: nextjs
  build:
    repo: https://github.com/you/your-repo
    branch: main
    rootDir: apps/web
    buildFilter: ['apps/web/**', 'packages/ui/**']
  port: 3000
  exposePublic: true

💡 Monorepo: declare several services with different rootDir values. Each becomes an independent block with its own build.

image

To use for an already published image (public or private registry).

- name: cache-proxy
  type: private
  image: nginxinc/nginx-unprivileged:stable-alpine
  port: 8080

⚠️ The image must run without root privileges. Many official images have a variant meant for that (for example nginx-unprivileged instead of nginx). An image that requires root will not start.

databases[]

A managed database or message broker: the platform provisions it, generates the credentials and keeps them secret.

databases:
  - name: db
    type: postgres
    extensions: [pgvector]
    enableBackups: true
    additionalDatabases:
      - name: analytics
        user: analytics_user
    resources: { cpu: 0.5, memory: 1, storage: 5 }

  - name: cache
    type: redis
    resources: { cpu: 0.25, memory: 0.5 }

ℹ️ You never write the credentials. They are generated at provisioning time and injected into your services through fromDatabase. See Managed services.

Resources

resources is always expressed the same way, for a service as for a database:

Omitting resources applies the platform defaults. The stack's total is checked against the project's quota during the plan.

env — the five forms

This is the heart of NubiStack: environment variables are not copied over, they are referenced. Each variable uses exactly one form.

1. Literal value

env:
  LOG_LEVEL: info                              # short form
  API_TOKEN: { value: "abc123", secret: true } # encrypted at rest

secret: true is only valid together with value.

2. From a database — fromDatabase

env:
  DATABASE_URL: { fromDatabase: { name: db, property: connectionString } }
  DB_HOST:      { fromDatabase: { name: db, property: host } }

scheme option: forces the URL prefix to match your driver (for example postgresql+asyncpg for async SQLAlchemy).

DATABASE_URL: { fromDatabase: { name: db, property: connectionString, scheme: postgresql+asyncpg } }

3. From a neighboring service — fromService

env:
  API_URL: { fromService: { name: api, property: url } }

Referencing a service automatically creates a deployment dependency: the referenced service will be deployed first.

4. Generated by the platform — generateValue

env:
  SECRET_KEY: { generateValue: true }
  JWT_SECRET: { generateValue: { length: 64, charset: hex } }

The value is generated once, then stays stable across updates. charset accepts alnum (default), hex or base64; length ranges from 8 to 256.

5. Asked for at the first deployment — sync: false

env:
  STRIPE_KEY: { sync: false }

The variable is asked of you once only, when the stack is applied (Secrets to provide section of the plan), and is never overwritten afterwards. This is the form to use for third-party API keys, which you do not want to write into a versioned file.

Bonus — inherited from a group: fromGroup

envGroups:
  common:
    LOG_LEVEL: info
    REGION: eu-west

services:
  - name: api
    # ...
    env:
      LOG_LEVEL: { fromGroup: common }

Deployment order and dependencies

The platform works out the order by itself, from:

• the dependsOn you declare explicitly,
• the fromService references (implicit dependency),
• the databases, always provisioned before the services that use them.

- name: front
  dependsOn: [api]

A waiting block shows Deployment blocked with the name of what it is waiting for, then starts by itself as soon as the dependency is online.

⚠️ Circular dependencies are refused at plan time (api depends on front which depends on api). The error message shows the cycle.

Common validation errors

The plan validates the manifest before anything is created. The most frequent rejections:

See also

• NubiStack — overview
• Detecting from a repo — let the platform write this file for you.
• Stack lifecycle