Blueprint

What is a Blueprint?

A Blueprint is a blueprint.yaml file that describes your apps and the managed add-ons they attach to: web services, background workers, cron jobs, databases and caches, and the environment variables and storage they need. You can start from a catalog template, or export a Blueprint from an app you've already built in the dashboard, then check it into your repository so the definition lives alongside your code.

Because the definition is declarative and version-controlled, you can review changes in a pull request and redeploy the same stack into another environment (staging, production, a customer instance) without clicking through the dashboard each time.

File format

The blueprint.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

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

services:
  - ...

addons:
  - ...

Service definition

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
    addons: [main-db]      # attach add-ons; their connection env vars are injected automatically
    envVars:
      - key: NODE_ENV
        value: production

Add-on definition

addons:
  - name: main-db
    type: postgresql        # postgresql | mysql | redis | mongodb | ...
    plan: starter
    version: "17"
    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 static frontend, a PostgreSQL add-on, and a Redis add-on. Each service attaches the add-ons it needs, and their connection env vars (DATABASE_URL, REDIS_URL) are injected automatically:

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

addons:
  - name: postgres
    type: postgresql
    plan: starter
    version: "17"
    storage: 20Gi

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

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
    addons: [postgres, redis]   # connection env vars injected automatically
    envVars:
      - key: NODE_ENV
        value: production
      - 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
    addons: [postgres, redis]

  - 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
    addons: [postgres]

Deploying a Blueprint

stackblaze up

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

stackblaze up

StackBlaze will:

1. 1. Parse and validate the YAML file.
2. 2. Compare it against what's currently running in the project.
3. 3. Show you what will be created, updated, or removed.
4. 4. Prompt for confirmation.
5. 5. Provision add-ons first, then create/update apps and wire the injected connection env vars.

Preview without applying

stackblaze up --dry-run

The --dry-run flag shows what would change without touching anything. Use this in CI pipelines to verify your Blueprint before merging.

Auto-apply in CI

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. This is the recommended pattern for secrets, your Blueprint documents what the service needs without exposing the actual values in version control. Connection strings for attached add-ons are handled for you and don't need to be listed here at all.

Schema reference

For the complete schema reference, see the API Reference.