Workers and scheduled jobs next to your application

See where a worker and a scheduled job run next to a web application in Tenkai, how a schedule starts a run, and what happens when one fails or overlaps.

Run background work beside your web application on your cluster. Use a Worker for a process that stays running, such as one that takes jobs from a queue and processes them. Use a Scheduled job for a command that runs at set times, then stops.

Both can use the same repository or image as your web application. Set a different Entrypoint, such as node ace queue:work or node ace reports:send.

A worker and a scheduled job next to a web application1/8

Scene 1 of 8: Three applications, one cluster

This example has three manager nodes that accept workloads. Requests from visitors reach the two web replicas; the worker gets no public route. The dashed outline marks a possible place for a scheduled job run, not reserved capacity.

How a worker runs

Tenkai runs a worker as a Docker Swarm service with 1 to 10 replicas. Its size sets the CPU and memory each replica reserves and the limits it may use. Swarm places replicas on nodes that accept workloads and have room for their reservations. Several replicas can share a node.

Tenkai gives it no public route or published port. It joins the private network of its environment in that cluster.

Your code decides what the worker does. For a queue consumer, your queue library controls concurrency and retries, not Tenkai. You can bind a Redis® or Valkey managed service to both applications for the queue.

If a replica exits, Swarm starts a replacement. A deployment starts the new version beside the old one and checks that its replicas stay running for 15 seconds before stopping the old version. Both versions can consume jobs during that overlap. See deploy a worker.

How a scheduled job runs

Once you deploy a scheduled job, a scheduler on your cluster starts its runs, even while Tenkai is down. The tenkai-scheduler service runs on one manager node. It uses cron schedules with five fields for minute, hour, day of month, month and day of week. All times use UTC.

At each scheduled time, it checks for an unfinished run across all releases of the job. If it finds one, it skips that time. Otherwise, it asks Swarm to start a run on an eligible node with room. Each run uses the job's size. Between runs, the job reserves no CPU or memory. The shared scheduler stays running.

Swarm stores the schedules on its manager nodes. If the scheduler's node stops, Swarm can start it on another manager, provided a majority of managers remain available. Three managers let the scheduler survive the loss of one. This does not make the job's database or queue highly available.

When a run overlaps the next one

The scheduler skips times that fall during an unfinished run. It does not queue them for later. Try different intervals and run lengths below. The example assumes each accepted run starts at the scheduled time, with no manual runs or outages.

When a run lasts longer than the interval between runs1/3

Scene 1 of 3: Short runs

Every 15 minutes, a run starts and takes 7 minutes. All 8 scheduled times before 05:00 start a run. These examples assume no outages, startup delays or manual runs.

Run now also checks for an unfinished run. Avoid using it just as the schedule fires. If both starts pass the check together, the second can stop the run the first started.

When a run fails

Neither Swarm nor Tenkai retries a failed run. The schedule still applies. Add retries to your command or use a queue if failed work must be tried again.

Every minute, Tenkai collects records of job runs. It keeps these records for 30 days and shows the latest 20. The page warns if the latest run with a known outcome failed. Tenkai sends no email. Swarm keeps five runs per service by default. Records Tenkai never collected can disappear from that history during an outage. See Follow the runs.

Deployments and runs

A scheduled job deployment starts no run. It sets the release for future runs. An existing run keeps its release.

Each application deploys separately. Put shared database migrations in the web application's pre-deploy commands and deploy it first. Keep the schema compatible with workers and runs still using the old code.

Limits

A missed time is not replayed after a scheduler outage or move.
Schedules use UTC, with no daylight-saving adjustment. 0 9 * * * means 09:00 UTC all year.
A schedule fires at most once a minute. Use a worker for a loop that runs every few seconds.
Workers and scheduled jobs cannot keep local files across deployments or runs. Store lasting data in a database or object storage.

When another option suits better

For work after an event, such as a sign-up email, use a queue and a worker.
For parallel imports, configure your queue consumer's concurrency or add worker replicas.
To catch up missed work, record progress in your database and let the next run resume it.

Go further

Redis is a registered trademark of Redis Ltd. Any rights therein are reserved to Redis Ltd.