Tutorial: deploy a background worker
A background worker runs continuously without a public HTTP port. Typical examples consume queued work or perform long-running background processing.
Worker requirements
The worker command should:
- stay running while it waits for or processes work;
- handle temporary dependency failures without exposing secrets;
- write useful, redacted operational messages to standard output and error;
- stop safely when the application is replaced or restarted;
- avoid storing durable state only in temporary local files.
Start an application deployment
Open Applications → Deploy application and enter a permanent name such as email-worker.
Choose the source
Select a Git repository or a ready-made image. For Git, confirm the branch and root directory. For an image, use a versioned image tag.
Choose Background Worker
In Type & build, choose Background Worker. Workers do not use a public port.
For a Git source, choose the runtime and enter the build and start commands required by your project. The start command must launch the worker and remain running.
Choose resources
Select a resource pool, CPU, and memory based on the amount and size of work. Leave capacity in the pool for traffic peaks and other applications.
Add runtime values
Add the variable names needed to reach the worker’s queue or dependencies. Enter credentials only in value fields. Add a persistent volume only if the worker truly needs durable filesystem data.
Deploy and observe
Review and deploy. Because a worker has no public endpoint, use Deployments and Logs to verify it starts, waits for work, and processes a safe test job.
A worker that completes one task and exits may be treated as stopped or failed. Confirm that a continuously running worker matches your intended workload before deploying it with this application type.
Diagnose a quiet worker
If it is live but appears idle, confirm that it is expected to have work, then inspect redacted logs. Check variable names, dependency availability, and the start command. Never log full queue URLs, tokens, or message contents just to prove connectivity.