YAML reference

Use this reference after the task-oriented configuration guide. Put resources below .deliberate/; project.yaml selects the Team, Project, and Environment Flow, while every other document starts with resource:.

Project pin

team: acme
project: chat
flow: default

Resources

Resource	Purpose
component	A long-running service, background worker, or scheduled job
database	Platform-operated PostgreSQL or FerretDB
volume	Durable, automatically expanding filesystem storage
bucket	Elastic S3-compatible object storage
route	Explicit public or Private Net HTTP routing
domain	A customer-owned hostname attached to an environment
blueprint	A pinned instance of a published Blueprint
flow-pattern	A custom persistent and disposable Environment topology

Components

Components declare an image and only the behavior they need. Ports are internal unless they request visibility: public or private. No ports means a worker; schedule: means a scheduled job.

resource: component
name: app
image: ghcr.io/acme/app:1.4.2
cpu: 1
memory: 2Gi
ports:
  - port: 3000
    visibility: public
env:
  DATABASE_URL: "${{ postgres.url }}"
secrets:
  - SESSION_SECRET
needs:
  databases:
    - postgres
healthcheck:
  path: /health

Declaring needs authorizes the dependency; it injects nothing automatically. Wire the output to the environment-variable name your software expects with a ${{ name.output }} expression.

Complete example

This bundle describes a production application and its supporting resources. Put it in .deliberate/app.yaml, next to .deliberate/project.yaml.

# PostgreSQL is addressed as `postgres` by the components below.
resource: database
name: postgres
engine: postgres
tier: prod
version: "17"
extensions:
  - vector

---
# Volumes grow automatically. `backup` selects the durability policy.
resource: volume
name: uploads
backup: offsite

---
# Buckets expose S3-compatible outputs such as endpoint and access_key.
resource: bucket
name: assets
expose: true
anonymousRead: false

---
resource: component
name: app
image: ghcr.io/acme/example-app:1.4.2
cpu: 1
memory: 2Gi
replicas: 1
class: standard
ports:
  - port: 3000
    protocol: http
env:
  NODE_ENV: production
  DATABASE_URL: "${{ postgres.url }}"
  DATABASE_POOL_URL: "${{ postgres.pooled_url }}"
  S3_ENDPOINT: "${{ assets.endpoint }}"
  S3_BUCKET: "${{ assets.bucket }}"
  S3_ACCESS_KEY: "${{ assets.access_key }}"
  S3_SECRET_KEY: "${{ assets.secret_key }}"
secrets:
  - SESSION_SECRET
needs:
  databases:
    - postgres
  buckets:
    - assets
  volumes:
    - name: uploads
      path: /app/uploads
healthcheck:
  path: /health
  port: 3000
  initialDelay: 15s
release:
  command: ["npm", "run", "migrate"]
  timeout: 10m
postDeploy:
  command: ["npm", "run", "warm-cache"]
  timeout: 5m
shutdown:
  gracePeriod: 60s
alerts:
  - name: elevated-error-rate
    type: http_error_rate
    threshold: 5
    window: 10m
    minRequests: 100
    recipients:
      - ops@example.com
overrides:
  preview-*:
    cpu: 0.125
    memory: 256Mi
    replicas: 1
    class: standard

---
# A worker is the same component primitive without a port.
resource: component
name: worker
image: ghcr.io/acme/example-app:1.4.2
command: ["npm", "run", "worker"]
cpu: 1
memory: 2Gi
env:
  DATABASE_URL: "${{ postgres.url }}"
needs:
  databases:
    - postgres

---
# Routes deliberately connect a hostname to a component.
resource: route
host: chat
visibility: public
rules:
  - path: /
    to: app
open:
  - label: Open Acme Chat
    path: /
    description: Open the customer-facing application.
  - label: Administration
    path: /admin
    description: Configure the application.

The needs declarations grant the app access to the named resources. The ${{ ... }} expressions then map their outputs to the environment-variable names this particular image expects. release runs before the new revision is made current; postDeploy runs after deployment. Both use the bounded lifecycle hook contract. The preview-* override keeps every matching preview environment smaller without changing production.

The route makes public exposure explicit. Change its visibility or replace its host without changing the Component that serves it.

The parser rejects unknown fields.