Creating a Background Worker

A Background Worker is a long-running process without a public web endpoint. It is built and deployed exactly like a Web Application — you push code, the platform builds it with buildpacks and runs it — but it gets no public URL. It can declare an optional health check — see Health checks.

When to use a worker

Choose a worker when your process does its job without serving web requests:

• consuming a queue or processing jobs
• running a bot or a long-lived connection to an external service
• periodic or streaming data processing

For an application HTTP service, create a Web Application. A worker may still listen on a port solely to answer its health check.

Running a bot that must never run twice, such as a chat bot? Make it a singleton.

Before you begin

You need an Environment to create the worker in, and permission to manage workers in that Project (see Access Control). Workers count toward your plan’s limits like any other Resource — see Plans, Limits & Usage.

Create a worker in the dashboard

1. In the dashboard, open the Environment (for example production in the shop project) and create a new Resource.
2. Select the Background Worker resource type.
3. Enter a Name — up to 50 lowercase letters, numbers, and hyphens, starting with a letter (for example jobs).
4. Pick the Framework that matches your code — Ruby on Rails, Node.js, Python, Go, Rust, or Static Files (see Supported Frameworks).
5. Set Process type to the name your build declares, such as worker. Leave it blank only when the build’s default process is the worker. This selects a buildpack process, not a shell command; the same field is editable later in Settings.
6. Optionally adjust Replicas (how many instances run; default 1), CPU Limit, Memory Limit, and Max egress per replica (Mbps) (outbound bandwidth per instance; unlimited when left blank).
7. Click Create Resource.

There is no Networking section for a worker — no port, since it takes no public traffic. A worker’s health check, if you set one, lives under its own settings instead — see Health checks. Or set it, along with the worker’s process, in d2o-paas.yaml in your repository — see d2o-paas.yaml Reference.

The platform hosts a git repository for your worker’s source. After creating it, you get a remote to push to; pushing to the main branch triggers a build and deploy.

Create a worker with the CLI

paas apps create creates a Web Application by default; add --worker to create a Background Worker:

paas apps create jobs --worker \
  -o acme -p shop -e production \
  --framework nodejs

Useful options for workers:

• --framework <FRAMEWORK> — the buildpack framework for your code
• --process <PROCESS> (alias --start-command) — select a named process such as worker
• --replicas <REPLICAS> — how many instances to run
• --cpu <CPU> / --memory <MEMORY> — per-instance resource limits
• --health-check-path <PATH> or --health-check-command <COMMAND> — optional; without either, a new instance just has to run for 30 seconds without restarting to count as healthy (see Health checks)
• --git-repo <GIT_REPO> / --git-branch <GIT_BRANCH> — reserved for building from an arbitrary git URL, which isn’t supported; push to the platform-hosted repository (see Deploying with Git Push), or deploy from GitHub or GitLab
• --autoscaling-min, --autoscaling-max, --autoscaling-cpu-target — enable CPU-based autoscaling (see Scaling & Autoscaling)

A worker never gets a public URL. If you give it a health check path, it must answer on the port in $PORT — 8080 unless you set --port.

Deploy your code

From your worker’s source directory, configure the paas git remote and push:

cd my-worker
paas git remote -o acme -p shop -e production -a jobs
git push paas main

The push triggers a build and deployment. Follow along with:

paas status -o acme -p shop -e production -a jobs
paas logs -a jobs --tail

See How Builds & Deployments Work for what happens between the push and your worker running.

Several apps from one repository? Create them with --shared-source and use the Environment’s remote instead — see One remote for several apps.

What a worker doesn’t have

Because a worker serves no HTTP traffic, there is no public URL and no custom domain. A health check is optional — see Health checks — and without one the platform just waits for a new instance to stay up for 30 seconds. Everything else works the same as for a Web Application: environment variables, secrets, database attachments, scaling, restarts, logs, metrics, and the console.

Next steps

• Designing Apps for d2o — shutdown and retry-safe jobs

• Environment Variables — configure your worker

• Attaching a Database — give it a database connection

• Logs — watch what it’s doing

• Scaling & Autoscaling — run more instances

For complete web and worker examples sharing one build, follow the language tutorials.