Blueprint Spec

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

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:

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:

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:

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:

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:

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:

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:

Service Plans

Available instance types:

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:

Environment Variables

Three patterns for defining environment variables:

1. Hardcoded Values

For non-sensitive configuration:

2. Generated Secrets

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

3. User-Provided Secrets

Prompt user for values during Blueprint creation:

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

4. Database References

Link to database connection strings:

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:

6. Environment Variable Groups

Reusable groups shared across services:

Databases

PostgreSQL

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):

Read Replicas (paid plans):

Redis (Key-Value Store)

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:

Autoscaling

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

Notes:

• Autoscaling disabled in preview environments
• Preview environments run minInstances count
• Requires Professional or higher workspace

Health Checks

Configure health check endpoints:

Default: / (root path)

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

Build Filters

Control when builds are triggered based on changed files:

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:

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:

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:

Validation

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

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 (opens in a new tab)
• Render CLI Documentation: https://render.com/docs/cli (opens in a new tab)
• Environment Variables Guide: https://render.com/docs/environment-variables (opens in a new tab)