# 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

```yaml
# 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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:

```yaml
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:

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

### 3. User-Provided Secrets

Prompt user for values during Blueprint creation:

```yaml
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:

```yaml
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:

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

### 6. Environment Variable Groups

Reusable groups shared across services:

```yaml
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

```yaml
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):**
```yaml
databases:
  - name: postgres
    databaseName: myapp_prod
    plan: pro-4gb
    highAvailabilityEnabled: true
```

**Read Replicas (paid plans):**
```yaml
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)

```yaml
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:

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

### Autoscaling

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

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

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

```bash
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