Run GetRatchet housekeeping independently on Railway.
Platform maintenance on Railway
The GetRatchet-owned process uses pnpm platform-worker, Dockerfile.platform-worker and railway.platform.json. It is separate from customer workers. It never executes customer code. Recovery only re-queues eligible existing jobs. Its one claimant role is HTTP workers: for Pro workspaces that registered an HTTPS endpoint, it claims matching jobs as http-<id> and POSTs them to that endpoint (public addresses only, no redirects, bounded responses), so execution stays on customer-owned infrastructure.
Deploy the repository root as a Railway service. For new services, configure the Dockerfile builder with /Dockerfile.platform-worker, healthcheck /health, and restart-on-failure with ten retries in Railway settings. Railway no longer accepts Config as Code for new services; railway.platform.json remains a reference for legacy services. Start with one replica. The container installs pinned dependencies and generates Prisma; it does not run migrations or build the web app. Apply migrations once through the controlled application release process before starting it.
Configure:
DATABASE_URL: the platform runtime database connection for this environment, with the same organization-scoped maintenance access as the API. Never use a customer API key or provider/tool credential.NEXT_PUBLIC_APP_URL: canonical application URL;RESEND_API_KEYwithgetratchet.appverified in Resend for operational notifications.BILLING_ENFORCEMENT_ENABLED: identical to the API. Stripe API secrets are not needed for deadline reconciliation; webhooks belong to the web process.PORT: Railway-injected health port (default 8080).MAINTENANCE_INTERVAL_MS: pause between pages, clamped to 1–60 seconds; default 5 seconds.MAINTENANCE_IDLE_INTERVAL_MS: optional pause after a successful complete sweep with no queued/running bulk recovery. Defaults to the normal interval; bounded by that interval and 15 minutes. Set900000to let an otherwise idle Neon database suspend. Partial sweeps, failures, and active recovery retain the normal interval. Health checks allow the configured sleep plus five minutes for the next successful page.- Preview deployments must use the existing
VERCEL_ENV=preview,PREVIEW_DATABASE_URLandVERCEL_URLisolation configuration instead of inheriting production credentials.
No customer tool credentials are required. The process needs the same RESULT_ENCRYPTION_KEY (and RESULT_ENCRYPTION_KEY_ID / RESULT_ENCRYPTION_KEY_PREVIOUS when set) as the API: it decrypts schedule inputs, alert destinations and HTTP worker URLs, secrets and job inputs. Retention does not decrypt payloads. Keep database migration credentials out of the running container.
Health: HTTP /health, success 200; unavailable during shutdown or after five minutes without a fully successful page. Restart policy: ON_FAILURE, at most ten retries. Railway service health checks validate deployment; configure external monitoring for continuing health. Logs contain fixed event names, timestamps and counts only.
Each iteration selects at most 25 organizations using an ID cursor. Each organization performs one bounded retention sweep (25 completed runs, gated once/hour), one recovery scheduling step, up to 20 new offline notifications, up to three pending notifications and billing deadline reconciliation. Expired rate-limit deletion is capped at 100 rows/page. Retention/recovery/reconciliation use database locks or conditional updates, and notifications have delivery leases/deduplication. As with any external email send, a crash after sending but before recording delivery may duplicate a notification.
SIGTERM/SIGINT stops new work, waits for the current bounded task and up to 10 seconds for open HTTP worker requests to report, closes HTTP and disconnects the database. Allow sufficient Railway termination grace for an active database or email request. Do not run multiple replicas initially; existing transactional guards are the protection for overlapping restarts, not a reason to scale blindly.
Idle scheduling and Neon Free
With a 15-minute idle interval, a newly requested bulk recovery can wait up to 15 minutes before maintenance discovers it; subsequent pages use the normal interval. Offline-worker detection, failed notification retries, retention sweeps, and billing housekeeping may also wait for that next sweep. Normal API operations, job claim/report, lease fencing, retry due times, immediate notification dispatch, and billing checks on reads are unchanged. The health endpoint does not query PostgreSQL.
This setting reduces idle housekeeping traffic; it does not guarantee fitting a free allowance. Customer worker polling, dashboard activity, database health probes, and other queries can keep the database awake. Do not silently extend customer-worker polling beyond the five-minute offline threshold: their heartbeat and execution expectations need a separate coordinated change. Stop disposable workers when testing is complete. Continuously active production workloads may require a paid database plan; never rely on quota exhaustion as a scheduling mechanism.
Rollout without a housekeeping gap
Customer claim polls keep the existing idempotent fallback unless PLATFORM_MAINTENANCE_POLL_FALLBACK=false. Start the platform worker, verify its health/logs and maintenance progress without customer polling, then set that variable to false on the web app. Customer SDKs need no changes. Roll back the flag if maintenance is unavailable. Billing deadlines are also computed on reads and do not depend on polling.
Sentry: see observability for server/browser/worker DSNs, preview isolation, sampling, private source-map uploads with build-only credentials, production alerts, local verification and rollback. Railway uses a built worker with debug IDs; never pass SENTRY_AUTH_TOKEN to its image or runtime.