@vodailoc/kilo-kit-mcp 1.1.0 → 1.2.0

package/skills/engineering/render-deploy/references/blueprint-spec.md

@@ -1,718 +1,718 @@
-# 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
+# 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