Railway and Render Deploys skill for Codex

A good PaaS setup is reproducible from the repo: services, databases and variables are declared in render.yaml or railway.json, migrations run in a pre-deploy step rather than at boot, the app binds to the injected PORT, and services talk over the private network instead of public URLs.

Inspect first

1. Read AGENTS.md, package.json or equivalent, the Dockerfile if any, and existing render.yaml, railway.json or railway.toml, Procfile.
2. Find how the app reads its port and database URL. Both platforms inject PORT; the app must listen on 0.0.0.0 (Railway private networking may need ::).
3. List what the app needs: web service, background worker, cron, Postgres, Redis, disk.
4. Platform CLIs and dashboards need network and login. In an offline sandbox, write the config files and hand deploy commands to the user.

Choosing between them

Factor	Railway	Render
Config as code	railway.json / railway.toml per service	One render.yaml Blueprint for the whole stack
Builds	Railpack auto-detect or Dockerfile	Native runtimes (node, python, ruby, go, rust, elixir) or Docker
Pricing model	Usage-based (CPU, RAM, egress)	Per-instance plans
Previews	PR environments	Preview environments from the Blueprint
Good fit	Many small services, quick experiments, variable references	Stable stacks wanting declarative Blueprints and predictable plan costs

Either is fine for a typical web plus worker plus Postgres app. Pick the one the team already uses; migration between them is mostly config translation.

Render Blueprint

# render.yaml
services:
  - type: web
    name: api
    runtime: node
    plan: starter
    region: oregon
    buildCommand: npm ci && npm run build
    startCommand: node dist/server.js
    preDeployCommand: npm run migrate
    healthCheckPath: /healthz
    envVars:
      - key: DATABASE_URL
        fromDatabase: { name: main-db, property: connectionString }
      - key: REDIS_URL
        fromService: { type: keyvalue, name: cache, property: connectionString }
      - key: SESSION_SECRET
        generateValue: true
      - key: STRIPE_SECRET_KEY
        sync: false            # entered in the dashboard, never in git
      - fromGroup: shared-settings

  - type: worker
    name: jobs
    runtime: node
    plan: starter
    buildCommand: npm ci && npm run build
    startCommand: node dist/worker.js
    envVars:
      - key: DATABASE_URL
        fromDatabase: { name: main-db, property: connectionString }

  - type: cron
    name: nightly-report
    runtime: node
    schedule: "0 4 * * *"
    buildCommand: npm ci && npm run build
    startCommand: node dist/report.js

  - type: keyvalue
    name: cache
    plan: starter
    ipAllowList: []            # private network only

databases:
  - name: main-db
    plan: basic-256mb
    postgresMajorVersion: "17"
    ipAllowList: []

envVarGroups:
  - name: shared-settings
    envVars:
      - key: LOG_LEVEL
        value: info

Plan names change over time; confirm current values in the Render dashboard or docs before committing. Apply a Blueprint from the dashboard (New, Blueprint) the first time; later pushes sync it.

Railway config as code

{
  "$schema": "https://railway.com/railway.schema.json",
  "build": { "builder": "RAILPACK", "buildCommand": "npm run build" },
  "deploy": {
    "startCommand": "node dist/server.js",
    "preDeployCommand": ["npm run migrate"],
    "healthcheckPath": "/healthz",
    "healthcheckTimeout": 120,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 5
  }
}

Each service in a Railway project has its own config file path; set it in the service settings when a monorepo holds several.

railway login
railway link                               # choose project and environment
railway add --database postgres            # adds a Postgres service
railway variables --set "LOG_LEVEL=info"
railway run npm run migrate                # runs locally with the service's variables
railway up                                 # deploy current directory (confirm for production)
railway logs

Variable references wire services together without copying secrets:

DATABASE_URL = ${{Postgres.DATABASE_URL}}          # private connection string
API_INTERNAL = http://${{api.RAILWAY_PRIVATE_DOMAIN}}:${{api.PORT}}
SHARED_FLAG  = ${{shared.SHARED_FLAG}}

Use the private URL for service-to-service and app-to-database traffic; the public URL (DATABASE_PUBLIC_URL) costs egress and is exposed to the internet.

Migrations and releases

• Run migrations in the pre-deploy step. If it fails, the new version is not released and the old one keeps serving.
• Never run migrations in the start command of a multi-instance service: every instance races to migrate.
• Make migrations backward compatible with the running version (expand, migrate code, contract later), because old and new instances overlap during the rollout.

Disks and state

Attaching a persistent disk on either platform pins the service to one instance and usually means a short downtime on each deploy, since the disk cannot attach to two instances. Prefer managed Postgres, Redis and object storage; use disks only for things like a self-hosted CMS that insists on local files, and back them up.

Free tiers and sleeping

• Render free web services spin down after about 15 minutes idle and take tens of seconds to wake; free Postgres instances expire after a fixed period. Fine for demos, never for production or anything receiving webhooks.
• Railway trial and hobby credits run out; a service stops when they do. Set usage alerts and limits.

Debug table

Symptom	Check
Deploy fails health check	Listening on PORT and 0.0.0.0, health path returns 200 without auth, timeout long enough for boot
ECONNREFUSED to database	Using a public URL blocked by allow list, or private hostname from outside the project
Railway private DNS fails	App bound to IPv4 only; listen on ::
Works locally, crashes on boot	Missing variable; compare railway variables or the Render env tab with .env.example
Webhooks time out	Free instance asleep; upgrade plan or move the endpoint

Verification

• Config file validates (Render Blueprint preview, Railway schema in the editor).
• A preview or staging environment deploys from the config with no dashboard edits.
• Health endpoint returns 200; logs show the pre-deploy migration ran once.
• Database is reachable only privately; ipAllowList or public networking reviewed.
• Production deploys, database deletions and plan changes only after explicit user confirmation.

Gotchas

• generateValue: true creates the secret once; changing the Blueprint later does not rotate it.
• Deleting a Render database or a Railway Postgres service deletes its data; confirm a fresh backup and get explicit approval first.
• Build-time and runtime variables differ on Render Docker services; secrets needed during docker build must be passed as build args or secret files deliberately.
• Cron services run in their own container; they do not share memory or disk with the web service.