Workers
A worker is an application built from your repository and kept running, with no public hostname. A scheduled worker is built the same way and run on a schedule, one run at a time, until the command exits. Both have deployments, logs and variables; neither has domains.
Use a worker for something that waits for work: a queue consumer, a listener, a process that polls. Use a scheduled worker for something that should happen at a time and then stop: a nightly report, an hourly sync, a cleanup.
Adding one
On an environment's Overview, choose Add resource, then Worker or Scheduled worker. Kuppit analyses the branch the environment deploys and proposes what to build, as it does for a web service. A worker can point at a different Root directory of the same repository, so an application and its background process can live side by side.
Then, for either kind:
| Field | What it is |
|---|---|
| Command | The executable and its arguments, separated by spaces. Leave it empty to run the image's own command. |
| Arguments | One per line, passed exactly as written. No shell expands them. |
A worker also asks for its Instances: how many copies are kept running, whether or not there is work. A scheduled worker asks for its Schedule and Time zone instead.
A worker can be added to Production or a named environment, never to a preview.
How a worker runs
A worker's deployment goes through the same steps a web service's does: a build, a revision, then the new revision takes over. What differs is the last step. A web service moves traffic; a worker moves its instances. Until the new revision is running, the previous one keeps working, so a failed deployment never stops a worker that was working.
A worker's instances are allocated for as long as it exists, and are billed for that time whether or not there is work to do. That is what makes it a worker rather than a web service that scales to zero.
PORT is not set, and nothing routes to a worker. A worker that starts an HTTP server is not wrong, but nothing will reach it.
Capacity
The worker's Overview shows how many instances it keeps. Pause sets that to zero: the deployment stays, nothing runs, and nothing is billed for compute until Resume. The Settings tab changes the number, from zero up to ten.
A change to capacity takes effect at once when a deployment is live. If nothing is live yet, it is saved and applied by the first deployment.
How a scheduled worker runs
A scheduled worker's deployment builds the image and prepares the job; when it goes live, the schedule is pointed at the new job. Each run starts the container with the command, waits for it to exit, and records the outcome. A run has one hour to finish.
The Schedule is a five-field cron expression, in the order minute, hour, day of month, month, day of week, with numbers, ranges, lists and steps: 0 * * * * runs hourly, 30 2 * * 1-5 at 02:30 on weekdays. The Time zone is an IANA name, such as UTC or Europe/Amsterdam.
Runs
The Overview lists the recent runs, each with its outcome:
| Run | Meaning |
|---|---|
| Pending | Waiting for the runtime to start it. |
| Running | The run is executing. |
| Succeeded | The run finished and exited cleanly. |
| Failed | The run exited with an error or ran out of time. |
| Cancelled | The run was stopped before it finished. |
Every run names the deployment it ran, so a failed run is one click from that deployment and its runtime logs. A run that fails is not repeated; the next one starts at the next scheduled time.
A run that the runtime did not accept — a transient refusal at the moment the schedule fired — is retried once. That means a run may, rarely, start twice. Write the task so that a repeat is harmless.
Pausing
Pause keeps the deployment and the schedule; nothing starts until Resume. A run already in progress finishes. The Settings tab changes the expression and time zone. As with a worker's capacity, a change takes effect at once when a deployment is live, and with the first deployment otherwise.
Variables
A worker has its own variables and inherits every variable set on its environment, exactly as a web service does. Values can be literals or references to what another resource exposes, such as a database's DATABASE_URL. See Environment variables.
A worker does not expose any variables of its own for other resources to reference.
In a named environment
A worker is a component of its environment like any other. When a named environment is created from one that has a worker, the plan offers New worker, deployed from the new environment's branch with the source's configuration copied across, or Don't include. A worker copied forward keeps its command, its capacity or schedule, and its variables; a scheduled worker copied forward starts with its schedule paused as its source was.
Removing a worker
Deleting a worker stops it, destroys the workload and removes its deployment history and, for a scheduled worker, its runs. Deleting an environment removes its workers with it.