Blueprint / Infrastructure as Code

Define every service, database, and environment variable in a single stackblaze.yaml file. Review diffs before you apply.

What is a Blueprint?

A Blueprint is a stackblaze.yaml file checked into your repository that describes your entire stack: web services, background workers, cron jobs, databases, and the environment variables that wire them together. When you run stackblaze up, StackBlaze computes a diff between the current live state and the desired state in your YAML, shows you a preview, and applies the changes.

Blueprints are ideal for teams that want infrastructure as code (IaC) practices without managing Kubernetes YAML, Helm charts, or Terraform providers. A single file captures the full picture of what's running in production.

Tip

Blueprints are optional. You can always manage services individually through the dashboard or CLI. Blueprints shine when your stack has multiple interdependent services that need to be versioned and reviewed together.

File format

The stackblaze.yaml file lives at the root of your repository (or in a directory you specify with --file). It follows a declarative YAML schema.

Top-level structure

stackblaze.yaml

version: "1"
name: my-project          # Must match the project name in the dashboard
region: us-east-1

services:
  - ...

databases:
  - ...

Service definition

stackblaze.yaml

services:
  - name: api
    type: web              # web | worker | cron | static
    repo: github.com/my-org/my-repo
    branch: main
    buildCommand: npm run build
    startCommand: node dist/server.js
    port: 8080
    plan: starter          # starter | standard | pro | custom
    scaling:
      min: 1
      max: 3
    healthCheck:
      path: /health
      intervalSeconds: 10
    envVars:
      - key: NODE_ENV
        value: production
      - key: DATABASE_URL
        fromDatabase:
          name: main-db
          property: connectionString

Database definition

stackblaze.yaml

databases:
  - name: main-db
    type: postgresql        # postgresql | mysql | redis | mongodb
    plan: starter
    version: "16"
    storage: 10Gi

Full example: full-stack app

Here is a complete Blueprint for a typical full-stack application with a Node.js API, a background worker, a Next.js static frontend, a PostgreSQL database, and a Redis cache:

stackblaze.yaml

version: "1"
name: acme-app
region: us-east-1

databases:
  - name: postgres
    type: postgresql
    plan: starter
    version: "16"
    storage: 20Gi

  - name: redis
    type: redis
    plan: starter
    version: "7"

services:
  - name: api
    type: web
    repo: github.com/acme/acme-app
    branch: main
    rootDir: packages/api
    buildCommand: npm run build
    startCommand: node dist/index.js
    port: 3000
    plan: standard
    scaling:
      min: 2
      max: 10
    healthCheck:
      path: /health
      intervalSeconds: 10
    envVars:
      - key: NODE_ENV
        value: production
      - key: DATABASE_URL
        fromDatabase:
          name: postgres
          property: connectionString
      - key: REDIS_URL
        fromDatabase:
          name: redis
          property: connectionString
      - key: JWT_SECRET
        sync: false          # marks as "fill in dashboard / secret"

  - name: worker
    type: worker
    repo: github.com/acme/acme-app
    branch: main
    rootDir: packages/worker
    buildCommand: npm run build
    startCommand: node dist/worker.js
    plan: starter
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: postgres
          property: connectionString
      - key: REDIS_URL
        fromDatabase:
          name: redis
          property: connectionString

  - name: frontend
    type: static
    repo: github.com/acme/acme-app
    branch: main
    rootDir: packages/web
    buildCommand: npm run build
    publishDir: dist
    envVars:
      - key: VITE_API_URL
        value: https://api.acme-app.stackblaze.app

  - name: nightly-report
    type: cron
    repo: github.com/acme/acme-app
    branch: main
    rootDir: packages/scripts
    buildCommand: npm run build
    startCommand: node dist/report.js
    schedule: "0 2 * * *"   # 02:00 UTC daily
    timezone: UTC
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: postgres
          property: connectionString

Applying a Blueprint

stackblaze up

Run this command in the directory containing your stackblaze.yaml:

terminal

stackblaze up

StackBlaze will:

1. Parse and validate the YAML file.
2. Fetch the current live state of your project.
3. Compute a diff (new services, updated configs, deleted services).
4. Display the diff and prompt for confirmation.
5. Apply changes, databases are provisioned first, then services are created/updated in dependency order.

Preview without applying

terminal

stackblaze up --dry-run

The --dry-run flag shows the diff without making any changes. Use this in CI pipelines to verify your Blueprint before merging.

Auto-apply in CI

terminal

stackblaze up --yes

Skip the confirmation prompt. Combine with --dry-run first in a separate CI step, then apply with --yes on merge to main.

Environment variable sync

Variables marked sync: false are declared in the Blueprint but their values are not stored in the YAML file. StackBlaze tracks that the variable must exist but expects you to set the value via the dashboard or CLI. This is the recommended pattern for secrets, your Blueprint documents what the service needs without exposing the actual values in version control.

Warning

Never commit real secret values to your stackblaze.yaml. Use sync: false for any sensitive variables and set them via the dashboard.

Schema reference

Field	Type	Required	Description
`version`	string	Yes	Always "1"
`name`	string	Yes	Project name, must match the dashboard
`region`	string	Yes	Region code, e.g. us-east-1
`services`	array	No	List of service definitions
`databases`	array	No	List of database definitions
`services[].name`	string	Yes	Unique service identifier
`services[].type`	string	Yes	web \| worker \| cron \| static
`services[].repo`	string	Yes	GitHub repo path
`services[].branch`	string	No	Deploy branch (default: main)
`services[].plan`	string	No	Instance plan (default: starter)
`services[].schedule`	string	Cron only	Standard cron expression

For the complete schema reference, see the API Reference.