GoForjUnreleased

Runtime Processes ​

Runtime processes are the long-running commands supervised in production.

This page owns the deployable command shapes, process separation, and shutdown behavior. For the conceptual difference between an app and its runtime roles, read Runtime Topology.

Common Processes ​

ProcessSupervised command
Combined runtime./bin/app
HTTP./bin/app api
Queue workers./bin/app worker
Scheduler./bin/app scheduler

The bare runtime-capable binary selects run; ./bin/app run is the explicit equivalent. This operations page uses direct binaries because a supervisor should execute the artifact being deployed. For source-aware development commands, see Local-First Development.

For a staff operations App named admin, use its binary:

ProcessSupervised command
Combined runtime./bin/admin
HTTP./bin/admin api
Queue workers./bin/admin worker
Scheduler./bin/admin scheduler

Choose the Processes to Supervise ​

Topology is selected by the commands the process manager starts; it does not require a build flag or a change to App code.

TopologyChoose it when
StandaloneOne deployment unit should own the enabled runtimes, as in local development, demos, small deployments, or simple operational environments.
DistributedHTTP, workers, and the scheduler need independent scaling, restart policies, metrics targets, or resource limits.

Use the combined command in the process table for one standalone service. Distributed deployments should start the explicit api, worker, and scheduler commands so ownership remains visible. The admin App can make the same choice when staff HTTP traffic, reporting workers, and operational schedules need separate ownership, such as ./bin/admin api.

Driver selection is separate from process topology. If API and worker processes share cache, queue, events, or files, configure backends that cross process boundaries. Splitting commands does not make process-local drivers shared or make jobs correct without idempotency and backend planning.

Supervise the Combined Runtime ​

run starts enabled runtimes together. A runtime-capable generated binary selects run when launched without arguments, so the bare and explicit forms are equivalent.

The runtime host cancels sibling runtimes when one fails and returns the first runtime failure with the runtime name.

Explicit commands still win: ./bin/app api starts only HTTP rather than selecting run. CLI-only App binaries retain root help behavior because they do not have a standalone runtime.

Supervise Split Runtimes ​

Split runtime commands are useful when production needs:

  • independent scaling
  • separate restart policy
  • scheduler singleton control
  • queue worker resource isolation
  • runtime-specific metrics scrape targets

Shutdown ​

Shutdown should be bounded and predictable.

Common variables:

text
APP_SHUTDOWN_TIMEOUT=30s
QUEUE_SHUTDOWN_TIMEOUT=10s
SCHEDULER_SUBPROCESS_SHUTDOWN_TIMEOUT=30s

APP_SHUTDOWN_TIMEOUT controls HTTP and scheduler graceful shutdown and the outer App lifecycle. QUEUE_SHUTDOWN_TIMEOUT controls worker drain separately. SCHEDULER_SUBPROCESS_SHUTDOWN_TIMEOUT defaults to the App timeout when unset and controls the grace period for scheduler-owned subprocesses.

Queue and scheduler subprocess settings are not automatically capped to the App timeout. Keep them consistent with the supervisor's stop grace period and test shutdown with in-flight work. The supervisor must allow enough time for the complete shutdown path, including cleanup after runtimes stop.

Constructors should build dependencies, not start long-running work. Keep business behavior independent of process topology, allow workers time to finish in-flight jobs, and use locking or singleton control before running multiple schedulers. Splitting processes does not provide shared state or job correctness by itself.

Next Steps ​