AGENT SKILL

render-background-workers

Sets up and configures background workers on Render for queue-based job processing. Use when the user needs to process async jobs, consume from a queue, run Celery/Sidekiq/BullMQ/Asynq/Oban workers, handle graceful shutdown with SIGTERM, wire a worker to Key Value (Redis), or choose between workers and cron jobs for background work. Trigger terms: background worker, async jobs, queue consumer, Celery, Sidekiq, BullMQ, Asynq, Oban, job processing, SIGTERM, graceful shutdown.

License 许可
MIT
最近更新
2026-07-06
Stars
★ 30
Forks
2

01 前言 Front Matter

name
render-background-workers
license
MIT
metadata
{ "author": "Render", "version": "1.0.0", "category": "compute" }
description
Sets up and configures background workers on Render for queue-based job processing. Use when the user needs to process async jobs, consume from a queue, run Celery/Sidekiq/BullMQ/Asynq/Oban workers, handle graceful shutdown with SIGTERM, wire a worker to Key Value (Redis), or choose between workers and cron jobs for background work. Trigger terms: background worker, async jobs, queue consumer, Celery, Sidekiq, BullMQ, Asynq, Oban, job processing, SIGTERM, graceful shutdown.
compatibility
Render background worker services

02 资源文件 3

03 SKILL.md 正文

Render Background Workers

This skill explains worker services on Render: processes that consume jobs from a queue instead of serving HTTP. Pair with render-blueprints, render-env-vars, and render-networking when wiring render.yaml and private connectivity.

When to Use

  • Designing or debugging queue-backed workers (Celery, Sidekiq, BullMQ, Asynq, etc.)
  • Choosing between a worker, Cron Job, or Workflow for background work
  • Configuring Render Key Value as a broker (not a cache) with correct eviction policy
  • Implementing graceful shutdown so in-flight jobs are not lost on deploy

Per-framework setup and signal-handling detail: references/queue-framework-setup.md, references/graceful-shutdown.md.

How Workers Work

  • Long-running services with no inbound (HTTP) traffic. Render does not expose a public URL or internal hostname for workers the way it does for web or private services—workers cannot receive private network traffic directed at them.
  • The typical pattern is a poll loop: the process connects to a queue backend (often Render Key Value, Redis-compatible Valkey 8) and pulls jobs.
  • Workers can initiate outbound connections on the private network—to PostgreSQL, Key Value, private services, web services (internal URLs), and the public internet—subject to your plan and firewall rules.

Queue Framework Overview

Framework Language Queue backend Notes
Celery Python Redis / Key Value Most common Python task queue
Sidekiq Ruby Redis / Key Value Standard for Rails
BullMQ Node.js Redis / Key Value Modern Node queue (Redis-based)
Asynq Go Redis / Key Value Go async task processing
Oban Elixir Postgres (not Redis) Queue stored in the database

Pairing with Key Value

  • Use Render Key Value as the job broker when your framework expects Redis.
  • Set maxmemory policy to noeviction. allkeys-lru and similar policies are for caches; evicting queue keys drops jobs.
  • Wire REDIS_URL (or your framework’s equivalent) via fromService with type: keyvalue and property: connectionString in the Blueprint.
  • Blueprints require ipAllowList on Key Value—include the CIDRs that should reach the instance (often [] for private-network-only access; see render-blueprints / Key Value field reference).

See references/queue-framework-setup.md for minimal app + YAML examples.

Worker vs Cron vs Workflow

Need Use Why
Always-on queue consumer Background Worker Polls continuously; long-lived process
Periodic scheduled task Cron Job Runs on a schedule, exits; 12h max per run
Distributed parallel compute Workflow Each run gets its own instance; fan-out patterns
High-volume or bursty jobs Workflow Scales per run; no idle instance cost between runs

Graceful Shutdown

  • Before stopping an instance, Render sends SIGTERM, then waits up to maxShutdownDelaySeconds (1–300, default 30) before SIGKILL.
  • Workers should: (1) stop accepting new jobs, (2) finish the current job or checkpoint progress, (3) close connections, (4) exit 0.
  • Set maxShutdownDelaySeconds to at least your longest safe job duration (see Dashboard or Blueprint).

Language- and framework-specific handlers: references/graceful-shutdown.md.

Blueprint Configuration

Minimal pattern: type: worker, runtime, buildCommand, startCommand, and envVars wired from Key Value.

services:
  - type: keyvalue
    name: jobs
    plan: starter
    region: oregon
    ipAllowList: []

  - type: worker
    name: task-worker
    runtime: python
    region: oregon
    plan: starter
    buildCommand: pip install -r requirements.txt
    startCommand: celery -A tasks worker --loglevel=info
    envVars:
      - key: REDIS_URL
        fromService:
          name: jobs
          type: keyvalue
          property: connectionString

Optional: maxShutdownDelaySeconds on the worker service for longer draining jobs.

References

Topic File
Celery, Sidekiq, BullMQ, Asynq, Oban setup + YAML references/queue-framework-setup.md
SIGTERM, maxShutdownDelaySeconds, per-language patterns references/graceful-shutdown.md

Related Skills

  • render-deploy — First deploy, CLI, service creation
  • render-blueprints — Full render.yaml schema, fromService, projects
  • render-networking — Private URLs, what can call what
  • render-scaling — Worker plans, instance counts, limits

04 同仓库更多 Skills

zhongjingyun
zhongjingyun/codex-plugins

android-emulator-qa

Use when validating Android feature flows in an emulator with adb-driven launch, input, UI-tree inspection, screenshots, and logcat capture.

★ 30
zhongjingyun
zhongjingyun/codex-plugins

supabase-postgres-best-practices

Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.

★ 30
zhongjingyun
zhongjingyun/codex-plugins

sentry

Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry API; perform read-only queries with the bundled script and require `SENTRY_AUTH_TOKEN`.

★ 30
zhongjingyun
zhongjingyun/codex-plugins

render-workflows

Sets up, develops, tests, and deploys Render Workflows. Covers first-time scaffolding (via CLI or manual), SDK installation (Python or TypeScript), task patterns (retries, subtasks, fan-out), local development, Dashboard deployment, and troubleshooting. Use when a user wants to set up Render Workflows for the first time, scaffold a workflow service, add or modify workflow tasks, test workflows locally, or deploy workflows to Render.

★ 30
zhongjingyun
zhongjingyun/codex-plugins

render-web-services

Configures Render web services—port binding, TLS, health checks, custom domains, auto-deploy, PR previews, persistent disks, and deploy lifecycle. Use when the user needs to set up a web service, fix health check failures, add a custom domain, configure zero-downtime deploys, or troubleshoot port binding issues.

★ 30
zhongjingyun
zhongjingyun/codex-plugins

render-static-sites

Deploys and configures static sites on Render's global CDN—build commands, publish paths, SPA routing, redirects, custom headers, and PR previews. Use when the user needs to deploy a static site, set up a React/Vue/Hugo/Gatsby frontend, configure SPA fallback routing, add redirect rules, customize response headers, or choose between a static site and a web service for their frontend. Trigger terms: static site, CDN, SPA, single-page app, React deploy, Vue deploy, Hugo, Gatsby, Docusaurus, Jekyll, staticPublishPath.

★ 30