Skip to content

Command Palette

Search for a command to run...

Version 1.2.0

Workers

Supervised background workloads with no public port: restart policies with jittered backoff, exec health checks, replica scaling, and rolling replacement.

What a worker is

A worker is a long-running background process: a queue consumer, an email sender, a scheduler. It has no public port, so the deployment questions are different from a service. Nobody routes traffic to it, so a blue-green cutover is meaningless; what matters is that at least the configured number of replicas stays alive, that a crashed replica comes back with growing patience, and that a new version replaces the old one without ever running zero replicas.

Phelix models this as a second workload type next to services. A project declares type: worker in phelix.yaml, and from then on Phelix never allocates a port, never injects PORT, and never creates proxy routes. Startup is judged by process identity and the health policy instead of a listen check. Services need no type key: every file written before the key existed is a service, and the worker keys are rejected for services just as service keys (port, endpoint probes, canary rollouts, the docker runtime) are rejected for workers. An invalid combination fails with a CONFIGURATION_ERROR naming the exact yaml path.

The worker config

phelix init --type worker writes a port-less template with the supervision defaults filled in. The full field reference is in the configuration reference. The example below shows the setup:

phelix.yamlyaml
name: email-worker
type: worker

process:
  restart:
    policy: on-failure
    max_attempts: 10
    backoff: { initial: 2s, max: 60s, multiplier: 2 }
  shutdown:
    signal: SIGTERM
    grace_period: 30s
  startup_timeout: 30s

health:
  mode: process

deploy:
  strategy: rolling
  replicas: 3
  rolling:
    max_surge: 1
    max_unavailable: 0
    drain_timeout: 60s

resources:
  cpu: 500m
  memory: 512Mi

Health without a port

Services prove health by answering HTTP. Workers pick one of two modes. health.mode: process (the default) is identity liveness: the replica is healthy while its process is alive. health.mode: exec runs a probe command on an interval: argv executed without a shell from the app directory with the replica's environment, where exit 0 means healthy.

FieldDefaultMeaning
health.exec.commandrequired with execProbe argv; exit 0 is healthy
health.exec.interval10sProbe cadence
health.exec.timeout5sPer-probe timeout, enforced with a process-group kill
health.exec.retries3Consecutive failures that cause one health-driven restart
process.startup_timeout30sWindow a fresh replica has: alive plus, in exec mode, a passing probe

Exec probes never restart-loop: retries consecutive failures trigger exactly one health-driven restart; the restart policy takes over from there.

Restarts, backoff, crashloop

The restart policy decides what an exit means. always restarts on any exit, on-failure (the default) restarts on non-zero exit, a signal, or OOM, and never leaves the replica down. Restart delays grow initial * multiplier^attempt, capped at max, with jitter, so a hundred replicas crashing together do not retry in lockstep.

After max_attempts consecutive failure-driven restarts the replica enters crashloop and stays there until a manual restart or a redeploy, instead of restarting forever. A clean exit (code 0) is never a failure: under on-failure the replica is marked completed and left alone. On stop, Phelix sends the configured signal, waits grace_period, then kills; a rolling deploy retiring a replaced replica waits drain_timeout instead.

Deploying workers

phelix rebuild on a worker runs the worker deploy engine. classic drains every replica, then starts the new version. rolling replaces one replica at a time: the replacement starts alongside the old replica, the old one keeps running until its replacement has passed the startup gate, and only then is it drained. There is no proxy involved, and --blue-green and --canary are rejected for workers, as are service-only strategies.

Terminal
phelix rebuild email-worker

phelix rebuild email-worker --strategy classic

A failed deploy reverts the replicas that were already replaced, so the app never ends up half on the new version. Rollback is not yet supported for workers: phelix rollback fails cleanly with ROLLBACK_FAILED rather than guessing. The zero-downtime strategies for port-ful apps are documented in Zero-downtime deploys.

Scale and day-2 commands

phelix scale changes a worker's replica count in place at the current version, without rebuilding. Growing launches the new slots from the recorded environment snapshot; shrinking drains the highest-index replicas gracefully, and they never count as crashes. Services scale through rebuild --replicas N instead.

Terminal
phelix scale email-worker --replicas 5
phelix scale email-worker --replicas 1 --json
CommandWorker behavior
phelix startLaunches every dead replica slot; no port is used
phelix stopGraceful stop of every replica (configured signal + grace period)
phelix restartRestarts every replica and resets crash counters; --replica N restarts one slot only
phelix scale --replicas NGrow or shrink worker or rolling-service replicas in place at the current version
phelix statusThe replica tree: per-replica status, PID, restarts, last exit, version
phelix listThe deploy column shows worker (×N)
phelix log --replica NTails one replica's output instead of the app log
phelix removeStops the replicas first; --purge deletes the app's data

With --json, scale returns the machine envelope with from_replicas and to_replicas on the machine contract. Encrypted environment snapshots ride along on every launch, so a grown replica runs with the configuration its version was built against - see Environment & security.