Lifecycle control

Status: Accepted · Audience: Operator · Area: B — Running it

---

Purpose

Start, stop, restart and inspect the stack — whole forms or individual services — without the operator needing to know Docker.

This is the most-used feature in the product. It must be fast, predictable, and honest about what actually happened. “Started” must mean the thing is usable, not merely that a container process exists.

Behaviour

Starting is health-gated, not process-gated

A container reaching “running” says nothing about whether the application inside it has finished initialising. The *arrs take several seconds to open their databases and bind their ports; Jellyfin takes longer on first run.

Starting therefore waits for each service to report healthy, and reports progress per service. An operator told “started” who then gets connection refused has been lied to.

Progress reaches every surface, and says whose it is

A terminal shows what the container engine writes while it pulls and while it starts, and what the wait after it is still waiting for. A start or a fetch asked for over the web API is answered with a job name and nothing else, so everything it says afterwards comes down the event stream (B2-R18). One stream carries every job’s lines, so a line a job said names that job; a surface following the start it asked for tells that start’s lines from another’s by the name it was answered with, not by when they happen to arrive (B2-R19).

Every operation states what it will affect before doing it

Stopping hunt while tv is also running stops six services, four of which tv still needs. The operator sees the affected list first.

How long it will be disturbed, where that can be said honestly

The operator deciding whether to restart hunt now or after dinner is asking one question: how long will this be down for? The stack can answer it in one of two ways, and only one of them is a duration.

Where the operation has a bound — a stop grace period, a health-check timeout, the wait a start gives a service before it gives up on it — that bound is a real number the stack already holds, and it is what gets stated. Where it does not — a teardown that lets downloads finish, a pull over an unknown connection, a start waiting on a service doing an hour of work it was in the middle of — there is no honest figure, and the operation says so rather than producing one.

What is refused is the middle: an estimate nobody can check. A duration guessed from an average is wrong in exactly the cases the operator most needs it — a large library mid-scan, a slow disk — and wrong silently, because nothing afterwards compares it to what happened. “Up to ninety seconds” and “as long as the downloads take” are both answers somebody can plan around. “About a minute”, where a minute was never measured, is not.

This is stated by the stack rather than worked out by whatever is displaying it. A surface that estimates is a second opinion with less to go on, and there is no version of that which is better than the first one being honest.

Fetching a form’s images is one of these operations. It stops nothing, and it is the one whose length depends entirely on the line: what it waits on is the images coming down, and the status reading says so beside what starting, stopping and restarting disturb, so a surface away from the machine can say before a fetch that it may take long and use a lot of the line without putting a figure on either (B2-R17).

Individual services are addressable

Restarting one wedged service must not require restarting the form. Operations apply to a form, a list of services, or everything.

Operations are idempotent

Starting an already-running form is a no-op that reports as such, not an error and not a restart. Stopping something already stopped likewise.

Order is derived, not configured

Because no depends_on crosses a profile boundary, services can start in any order. Where genuine ordering exists — qBittorrent requiring Gluetun’s network namespace — it lives within a single profile and is handled by Compose.

The corollary matters for stopping: the VPN must be stopped last, since tearing down Gluetun first would drop qBittorrent’s networking out from under it.

The underlying command is always inspectable

--dry-run prints the exact docker compose invocation without executing it. This serves debugging, learning, and the operator who wants to run it themselves (ADR-0001).

Status answers “is it working”, not “is it running”

Per-service status distinguishes: not created, created but stopped, starting, healthy, unhealthy, restart-looping, and stopped-with-error. “Up” is not a status — it’s an ambiguity.

A container a start created and that never ran is not stopped. lemonfiber never creates a container without starting it, so one left created is a start that did not happen — most often because something it depends on never became ready — and it is reported as failed. Reported as stopped, it would read as something the operator turned off, and a form holding it would stop counting as brought the moment the operator asked for it.

A start that did not complete says what did not come back

A start can fail before anything settles: the engine refuses it, or a dependency never becomes ready and the service that needs it is left created. The report still names the state of every service the start addressed, and of the services those depend on, read once when the start ends rather than waited for. A failed start that says nothing about any service reads as one where nothing fell short, which is the opposite of what happened. See G7 for the one-line rollup.

States

Per service:

Per form: inactive, partial (some services healthy), active (all healthy), degraded (running with at least one failure).

Edge cases

Acceptance criteria

Related

• B1 Forms — what a lifecycle operation applies to
• B3 Dashboard — where state is observed
• B8 Autostart — lifecycle across reboots
• G7 Health summary — the one-line rollup