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:
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: 512MiHealth 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.
| Field | Default | Meaning |
|---|---|---|
| health.exec.command | required with exec | Probe argv; exit 0 is healthy |
| health.exec.interval | 10s | Probe cadence |
| health.exec.timeout | 5s | Per-probe timeout, enforced with a process-group kill |
| health.exec.retries | 3 | Consecutive failures that cause one health-driven restart |
| process.startup_timeout | 30s | Window 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.
phelix rebuild email-worker
phelix rebuild email-worker --strategy classicA 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.
phelix scale email-worker --replicas 5
phelix scale email-worker --replicas 1 --json| Command | Worker behavior |
|---|---|
| phelix start | Launches every dead replica slot; no port is used |
| phelix stop | Graceful stop of every replica (configured signal + grace period) |
| phelix restart | Restarts every replica and resets crash counters; --replica N restarts one slot only |
| phelix scale --replicas N | Grow or shrink worker or rolling-service replicas in place at the current version |
| phelix status | The replica tree: per-replica status, PID, restarts, last exit, version |
| phelix list | The deploy column shows worker (×N) |
| phelix log --replica N | Tails one replica's output instead of the app log |
| phelix remove | Stops 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.