BB SkillsFind a workflow. Make it your own.
Create account
New here? Start with the guide ↗
Browse sections ＋
Render Deploy / Package file
READ-ONLY PACKAGE PREVIEW

openai-render-deploy/references/blueprint-spec.md

Version 49f948fa.bb1 · Apache-2.0. This preview displays packaged text and does not execute code. Treat the contents as untrusted instructions.

← Return to resource and package checksum

Render Blueprint Specification

Complete reference for render.yaml Blueprint files. Blueprints define your infrastructure as code for reproducible deployments on Render.

Overview

A Blueprint is a YAML file (typically render.yaml) placed in your repository root that describes: - Services (web, worker, cron, static, private) - Databases (PostgreSQL, Redis) - Environment variables and secrets - Scaling and resource configuration - Project organization

Root-Level Structure

# Top-level fields
services: []         # Array of service definitions
databases: []        # Array of PostgreSQL databases
envVarGroups: []     # Reusable environment variable groups (optional)
projects: []         # Project organization (optional)
ungrouped: []        # Resources outside projects (optional)
previews:            # Preview environment configuration (optional)
  generation: auto_preview | manual | none

Service Types

Web Services (type: web)

HTTP services, APIs, and web applications. Publicly accessible via HTTPS.

Required fields: - name: Unique service identifier - type: Must be web - runtime: Language/environment (see Runtimes section) - buildCommand: Command to build the application - startCommand: Command to start the server

Common optional fields: - plan: Instance type (default: free) - region: Deployment region (default: oregon) - branch: Git branch to deploy (default: main) - autoDeploy: Auto-deploy on push (default: true) - envVars: Environment variables array - healthCheckPath: Health check endpoint (default: /) - numInstances: Number of instances (manual scaling) - scaling: Autoscaling configuration

Example:

services:
  - type: web
    name: api-server
    runtime: node
    plan: free
    buildCommand: npm ci
    startCommand: npm start
    branch: main
    autoDeploy: true
    envVars:
      - key: NODE_ENV
        value: production
      - key: PORT
        value: 10000

Worker Services (type: worker)

Background job processors, queue consumers. Not publicly accessible.

Required fields: - name: Unique service identifier - type: Must be worker - runtime: Language/environment - buildCommand: Command to build - startCommand: Command to start worker process

Key differences from web services: - No public URL - No health checks - No port binding required

Example:

services:
  - type: worker
    name: job-processor
    runtime: python
    plan: free
    buildCommand: pip install -r requirements.txt
    startCommand: celery -A tasks worker --loglevel=info
    envVars:
      - key: REDIS_URL
        fromDatabase:
          name: redis
          property: connectionString

Cron Jobs (type: cron)

Scheduled tasks that run on a cron schedule.

Required fields: - name: Unique service identifier - type: Must be cron - runtime: Language/environment - schedule: Cron expression - buildCommand: Command to build - startCommand: Command to execute on schedule

Schedule format: Standard cron syntax (minute hour day month weekday)

Examples: - 0 0 * * * - Daily at midnight UTC - */15 * * * * - Every 15 minutes - 0 9 * * 1 - Every Monday at 9 AM UTC

Example:

services:
  - type: cron
    name: daily-backup
    runtime: node
    schedule: "0 2 * * *"
    buildCommand: npm ci
    startCommand: node scripts/backup.js
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: postgres
          property: connectionString

Static Sites (type: static or type: web with runtime: static)

Serve static HTML/CSS/JS files via CDN.

Required fields: - name: Unique service identifier - type: web - runtime: static - buildCommand: Command to build static assets - staticPublishPath: Path to built files (e.g., ./build, ./dist)

Optional configuration: - routes: Routing rules for SPAs - headers: Custom HTTP headers - buildFilter: Path filters for build triggers

Example:

services:
  - type: web
    name: react-app
    runtime: static
    buildCommand: npm ci && npm run build
    staticPublishPath: ./dist
    routes:
      - type: rewrite
        source: /*
        destination: /index.html
    headers:
      - path: /*
        name: Cache-Control
        value: public, max-age=31536000, immutable

Private Services (type: pserv)

Internal services accessible only within your Render account.

Required fields: - name: Unique service identifier - type: Must be pserv - runtime: Language/environment - buildCommand: Command to build - startCommand: Command to start

Use cases: - Internal APIs - Database proxies - Microservices not exposed to internet

Example:

services:
  - type: pserv
    name: internal-api
    runtime: go
    plan: free
    buildCommand: go build -o bin/app
    startCommand: ./bin/app

Runtimes

Native Runtimes

Node.js (runtime: node): - Versions: 14, 16, 18, 20, 21 - Default version: 20 - Specify version in package.json engines field

Python (runtime: python): - Versions: 3.8, 3.9, 3.10, 3.11, 3.12 - Default version: 3.11 - Specify version in runtime.txt or Pipfile

Go (runtime: go): - Versions: 1.20, 1.21, 1.22, 1.23 - Uses go modules - Version from go.mod

Ruby (runtime: ruby): - Versions: 3.0, 3.1, 3.2, 3.3 - Uses Bundler - Version from .ruby-version or Gemfile

Rust (runtime: rust): - Latest stable version - Uses Cargo

Elixir (runtime: elixir): - Latest stable version - Uses Mix

Docker Runtime

Docker (runtime: docker): Build from a Dockerfile in your repository.

Additional fields: - dockerfilePath: Path to Dockerfile (default: ./Dockerfile) - dockerContext: Build context directory (default: .)

Example:

services:
  - type: web
    name: docker-app
    runtime: docker
    dockerfilePath: ./docker/Dockerfile
    dockerContext: .
    plan: free

Image (runtime: image): Deploy pre-built Docker images from a registry.

Additional fields: - image: Image URL (e.g., registry.com/image:tag) - registryCredential: Credentials for private registries

Example:

services:
  - type: web
    name: prebuilt-app
    runtime: image
    image: myregistry.com/app:v1.2.3
    plan: free

Service Plans

Available instance types:

Plan RAM CPU Price
free 512 MB 0.5 Free (750 hrs/mo)
starter 512 MB 0.5 $7/month
standard 2 GB 1 $25/month
pro 4 GB 2 $85/month
pro_plus 8 GB 4 $175/month

Always default to plan: free unless user specifies otherwise.

Regions

Available deployment regions:

  • oregon (US West) - Default
  • ohio (US East)
  • virginia (US East)
  • frankfurt (EU)
  • singapore (Asia)

Example:

services:
  - type: web
    name: my-app
    runtime: node
    region: frankfurt

Environment Variables

Three patterns for defining environment variables:

1. Hardcoded Values

For non-sensitive configuration:

envVars:
  - key: NODE_ENV
    value: production
  - key: API_URL
    value: https://api.example.com
  - key: LOG_LEVEL
    value: info

2. Generated Secrets

Render generates a base64-encoded 256-bit random value:

envVars:
  - key: SESSION_SECRET
    generateValue: true
  - key: ENCRYPTION_KEY
    generateValue: true

3. User-Provided Secrets

Prompt user for values during Blueprint creation:

envVars:
  - key: STRIPE_SECRET_KEY
    sync: false
  - key: JWT_SECRET
    sync: false
  - key: API_KEY
    sync: false

The sync: false flag means "user will fill this in the Dashboard".

4. Database References

Link to database connection strings:

envVars:
  - key: DATABASE_URL
    fromDatabase:
      name: postgres
      property: connectionString
  - key: REDIS_URL
    fromDatabase:
      name: redis
      property: connectionString

Available properties: - connectionString: Full connection URL - host: Database host - port: Database port - user: Database username - password: Database password - database: Database name - hostport: Combined host:port

5. Service References

Link to other services:

envVars:
  - key: API_URL
    fromService:
      name: api-server
      type: web
      property: host

6. Environment Variable Groups

Reusable groups shared across services:

envVarGroups:
  - name: shared-config
    envVars:
      - key: LOG_LEVEL
        value: info
      - key: ENVIRONMENT
        value: production

services:
  - type: web
    name: web-app
    runtime: node
    envVars:
      - fromGroup: shared-config
      - key: PORT
        value: 10000

Databases

PostgreSQL

databases:
  - name: postgres
    databaseName: myapp_prod
    user: myapp_user
    plan: free
    postgresMajorVersion: "15"
    ipAllowList: []

Plans: - free: 1 GB storage, 97 MB RAM, 0.1 CPU - basic-256mb, basic-512mb, basic-1gb, basic-4gb - pro-4gb, pro-8gb, pro-16gb, etc. - accelerated-4gb, accelerated-8gb, etc. (SSD-backed)

Key fields: - name: Identifier for references - databaseName: Actual PostgreSQL database name - user: Database username - postgresMajorVersion: PostgreSQL version (11-16) - ipAllowList: Array of CIDR blocks (empty = internal only) - diskSizeGB: Storage size (paid plans only)

High Availability (paid plans):

databases:
  - name: postgres
    databaseName: myapp_prod
    plan: pro-4gb
    highAvailabilityEnabled: true

Read Replicas (paid plans):

databases:
  - name: postgres
    databaseName: myapp_prod
    plan: pro-4gb
    readReplicas:
      - name: read-replica-1
        region: ohio
      - name: read-replica-2
        region: frankfurt

Redis (Key-Value Store)

databases:
  - name: redis
    plan: free
    maxmemoryPolicy: allkeys-lru
    ipAllowList: []

Plans: Same as PostgreSQL

maxmemoryPolicy options: - allkeys-lru: Evict least recently used keys - volatile-lru: Evict LRU keys with TTL - allkeys-random: Evict random keys - volatile-random: Evict random keys with TTL - volatile-ttl: Evict keys with soonest TTL - noeviction: Return errors when memory full

Scaling

Manual Scaling

Fixed number of instances:

services:
  - type: web
    name: my-app
    runtime: node
    plan: standard
    numInstances: 3

Autoscaling

Dynamic scaling based on CPU/memory (Professional workspace required):

services:
  - type: web
    name: my-app
    runtime: node
    plan: standard
    scaling:
      minInstances: 1
      maxInstances: 5
      targetCPUPercent: 60
      targetMemoryPercent: 70

Notes: - Autoscaling disabled in preview environments - Preview environments run minInstances count - Requires Professional or higher workspace

Health Checks

Configure health check endpoints:

services:
  - type: web
    name: my-app
    runtime: node
    healthCheckPath: /health

Default: / (root path)

Recommended: Add a dedicated /health endpoint that returns 200 OK.

Build Filters

Control when builds are triggered based on changed files:

services:
  - type: web
    name: frontend
    runtime: static
    buildFilter:
      paths:
        - frontend/**
      ignoredPaths:
        - frontend/README.md
        - frontend/**/*.test.js

Behavior: - If paths specified: Build only when files in those paths change - If ignoredPaths specified: Don't build when only ignored files change

Projects and Environments

Organize services into projects with multiple environments:

projects:
  - name: my-application
    environments:
      - name: production
        services:
          - type: web
            name: prod-api
            runtime: node
            plan: pro
            buildCommand: npm ci
            startCommand: npm start
        databases:
          - name: prod-postgres
            plan: pro-4gb
        networking:
          isolation: enabled
        permissions:
          protection: enabled

      - name: staging
        services:
          - type: web
            name: staging-api
            runtime: node
            plan: starter
            buildCommand: npm ci
            startCommand: npm start
        databases:
          - name: staging-postgres
            plan: free

Environment features: - networking.isolation: Enable network isolation between environments - permissions.protection: Require approval for environment changes

Preview Environments

Configure automatic preview environments for pull requests:

previews:
  generation: auto_preview  # auto_preview | manual | none

Options: - auto_preview: Create preview environment for each PR automatically - manual: User manually triggers preview creation - none: Disable preview environments

Complete Example

Full-featured Blueprint with multiple services and databases:

services:
  # Web service
  - type: web
    name: web-app
    runtime: node
    plan: free
    region: oregon
    buildCommand: npm ci && npm run build
    startCommand: npm start
    branch: main
    autoDeploy: true
    healthCheckPath: /health
    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

  # Background worker
  - type: worker
    name: queue-worker
    runtime: node
    plan: free
    buildCommand: npm ci
    startCommand: node worker.js
    envVars:
      - key: REDIS_URL
        fromDatabase:
          name: redis
          property: connectionString

  # Cron job
  - type: cron
    name: daily-cleanup
    runtime: node
    schedule: "0 3 * * *"
    buildCommand: npm ci
    startCommand: node scripts/cleanup.js
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: postgres
          property: connectionString

  # Static frontend
  - type: web
    name: frontend
    runtime: static
    buildCommand: npm ci && npm run build
    staticPublishPath: ./dist
    routes:
      - type: rewrite
        source: /*
        destination: /index.html

databases:
  - name: postgres
    databaseName: app_production
    user: app_user
    plan: free
    postgresMajorVersion: "15"
    ipAllowList: []

  - name: redis
    plan: free
    maxmemoryPolicy: allkeys-lru
    ipAllowList: []

Validation

Validate your Blueprint before deploying (when CLI command is available):

render blueprint validate

Common validation errors: - Missing required fields - Invalid runtime values - Incorrect environment variable references - Invalid cron expressions - Invalid YAML syntax

Best Practices

  1. Always use plan: free by default - Let users upgrade if needed
  2. Mark all secrets with sync: false - Never hardcode sensitive values
  3. Use fromDatabase for database URLs - Automatic internal connection strings
  4. Add health check endpoints - Faster deployment detection
  5. Use non-interactive build commands - Prevents build hangs
  6. Bind to 0.0.0.0:$PORT - Required for web services
  7. Use environment variable groups - Share config across services
  8. Enable autoDeploy: true - Deploy automatically on push
  9. Set appropriate regions - Choose closest to your users
  10. Use build filters - Optimize build triggers in monorepos

Additional Resources

  • Official Blueprint Specification: https://render.com/docs/blueprint-spec
  • Render CLI Documentation: https://render.com/docs/cli
  • Environment Variables Guide: https://render.com/docs/environment-variables