Render

Render — make this repo deploy correctly, wired as code

Take any repo and make it deploy on Render (render.com) in one pass: pick the right service type, declare everything in a version-controlled render.yaml Blueprint, bind the port the way Render expects, and wire DATABASE_URL / secrets across services so they survive rotation. Steer clear of the four traps that eat first deploys: the "no open ports detected" 502, the free-tier spin-down, the 30-day free-Postgres expiry, and the 12-hour cron kill.

pick service type → render.yaml at repo root → bind 0.0.0.0:$PORT → wire env across services → push (auto-deploy)
        │                                                                                            │
   web|worker|cron|pserv|static|keyvalue                                       full key surface → references/blueprint-reference.md

Facts here are dated to 2026-06-02 against render.com/docs. Render ships changes; if a key or limit looks off, confirm against the live Blueprint spec before betting a deploy on it.

The one decision that decides everything: service type

Pick the type before you write a line of YAML. The type sets the billing model, whether the process gets a public URL, and whether Render expects it to bind a port. Choosing wrong means a worker that never starts because Render waited for a port, or a 12-hour job that dies silently as a cron.

runtime enum (everything except keyvalue): node, python, docker, image, static, go, ruby, elixir, rust.

Blueprint-first: everything lives in render.yaml

Rule: declare every service, database, and env var group in render.yaml at the repo root. Touch the dashboard only for sync: false secrets and one-off debugging. Why: the Blueprint is the reproducible, reviewable source of truth — it powers preview environments and a clean re-deploy, while dashboard-only config is invisible state that drifts and can't be code-reviewed.

Top-level keys: services, databases, envVarGroups, projects, previews.

Minimal correct render.yaml (annotated)

A multi-service app — a Node web service, a Python worker, a nightly cron, a Postgres db, and a shared env group. Every load-bearing key is commented.

databases:
  - name: app-db
    plan: starter            # NOT free for anything you care about — free expires in 30 days
    postgresMajorVersion: "17"
    region: frankfurt

envVarGroups:
  - name: app-shared
    envVars:
      - key: LOG_LEVEL
        value: info
      - key: SENTRY_DSN
        sync: false          # prompt once at setup; never stored in git

services:
  - type: web
    name: api
    runtime: node
    region: frankfurt
    plan: starter            # $7/mo — avoids the free-tier 15-min spin-down on an API
    buildCommand: npm ci && npm run build
    startCommand: npm start  # MUST bind 0.0.0.0 and read $PORT — see next section
    healthCheckPath: /healthz # gates zero-downtime rollout; new instance must pass first
    preDeployCommand: npm run migrate  # runs before the new instance serves traffic
    autoDeployTrigger: commit          # commit | checksPass | off
    envVars:
      - fromGroup: app-shared
      - key: DATABASE_URL
        fromDatabase:
          name: app-db
          property: connectionString   # never hardcode the URL
      - key: SESSION_SECRET
        generateValue: true            # Render generates a random secret

  - type: worker
    name: jobs
    runtime: python
    plan: starter
    buildCommand: pip install -r requirements.txt
    startCommand: celery -A app worker -l info  # no port — workers don't bind one
    envVars:
      - fromGroup: app-shared
      - key: DATABASE_URL
        fromDatabase: { name: app-db, property: connectionString }
      - key: API_URL
        fromService:                   # reference another service
          name: api
          type: web
          property: hostport

  - type: cron
    name: nightly-cleanup
    runtime: python
    schedule: "0 3 * * *"              # required for cron; 03:00 UTC daily
    buildCommand: pip install -r requirements.txt
    startCommand: python -m app.cleanup
    envVars:
      - key: DATABASE_URL
        fromDatabase: { name: app-db, property: connectionString }

Port binding — do this first (the #1 first-deploy failure)

Rule: a web service MUST listen on host 0.0.0.0 and read the PORT env var (Render sets it, default 10000). If Render detects no bound port within its window, the deploy fails with "no open ports detected" and visitors get a 502. This is the single most common first-deploy break — binding localhost/127.0.0.1 or a hardcoded port does it.

// Bad — binds the wrong host and ignores Render's PORT → "no open ports detected"
app.listen(3000);

// Good — bind 0.0.0.0 and honor $PORT
app.listen(process.env.PORT || 3000, "0.0.0.0");

# Bad — gunicorn on a fixed local port
gunicorn app:app --bind 127.0.0.1:8000

# Good — bind 0.0.0.0 and Render's $PORT
gunicorn app:app --bind 0.0.0.0:$PORT

Only web services need this. A worker/cron that tries to bind a port is fine but pointless; a web service that doesn't is broken.

Wiring env vars across services

Rule: never hardcode DATABASE_URL, REDIS_URL, or shared secrets as literal value: strings. Reference the resource so the value survives a rotation, recreate, or region move, and so secrets never land in git.

For a Key Value store, reference its connection string the same way you reference Postgres, via fromService against the keyvalue service.

Migrations and zero-downtime deploys

• preDeployCommand — runs once, before the new instance starts serving traffic. Put migrations here, not in startCommand (a startCommand migration runs on every instance and races under multiple replicas).
• healthCheckPath — Render polls it on the new instance and only shifts traffic once it passes, giving zero-downtime rollout. Point it at a route that checks real readiness.
• autoDeployTrigger — commit (deploy every push), checksPass (wait for CI status), or off (manual / deploy-hook only).