Task Lifecycle
This is the detailed, step-by-step version of what ratect run <task> (or
ratect-compat <task> — the two binaries share one engine) actually does,
covering task ordering, per-task setup and cleanup in depth (what a dependency
has to pass before it counts as ready is on its own page — see Dependency
Readiness). For the
broader architecture (config loading, CLI parsing, logging), see
how it works.
Task ordering
Ratect only ever runs one task’s containers at a time. A task’s prerequisites
just order sequential task executions — each prerequisite task runs to completion
(including its own cleanup, described below) before the next one starts, and before
the originally-requested task itself runs.
[tasks.compile]
run = { container = "build-env", command = "./build.sh" }
[tasks.test]
prerequisites = ["compile"]
run = { container = "build-env", command = "./test.sh" }
Running ratect run test here runs compile to completion first, fully cleaning up
after it, then runs test.
The whole order is worked out before any of it runs, as in Batect: a prerequisite that names no task, or a cycle among prerequisites, fails the run before the first task starts, so no earlier prerequisite has run by then.
A task doesn’t strictly need a run of its own — a task with only prerequisites
is valid (see config reference), and exists purely to
chain other tasks together:
[tasks.ci]
prerequisites = ["compile", "test"]
Running ratect run ci here runs compile then test to completion, same as above,
then stops — there’s no container of ci’s own left to run — saying The task ci only defines prerequisite tasks, nothing more to do. in every output style but
quiet.
Per-task steps
Every task execution gets its own Docker network, whether or not its container
declares dependencies — so a task’s container is never left running on Docker’s
shared default bridge network, reachable by or able to reach anything else on the
host. If the container does declare dependencies, those are started on that
network before the task’s own container, so the task’s container can reach them by
name — and so is anything named in the task’s own dependencies (sidecars scoped
to this task specifically, distinct from the container-level field — see config
reference), unioned in alongside the container-level ones.
(With ratect.toml, a container can leave that network with
network_mode
— it is then not reachable by name — while every other container still joins it.)
All of this — network, dependencies, and the task’s own container — is scoped
to this one task execution and torn down before moving on, regardless of whether
the task succeeded (though not if Ratect itself crashes — see Differences from
Batect) — unless --no-cleanup/--no-cleanup-after-failure/
--no-cleanup-after-success says otherwise, in which case everything below is left
genuinely running instead, for investigation (see CLI
reference):
sequenceDiagram
participant Engine as TaskEngine
participant Docker
participant Dep as Dependency container(s)
participant Main as Task's own container
Engine->>Docker: create_network()
par every container in the task's graph, the task's own included
Engine->>Docker: pull_image()/build_image() (per image_pull_policy, unless already decided this run)
Engine->>Docker: create_container(spec) — once its own image is ready
Docker-->>Engine: created on its network, not started
and independent branches of the dependency graph, each once every container it depends on is ready
Engine->>Docker: start_background_container(id)
Docker-->>Dep: started
Engine->>Docker: wait_for_container_healthy()
Docker-->>Engine: healthy (immediate if no health check)
loop for each setup command, in declared order
Engine->>Docker: exec_in_container(command)
Dep-->>Engine: exit code 0 (non-zero fails the task)
end
end
Note over Engine: a dependency's readiness gates only the *start* of what depends on it —<br/>every container is pulled or built, then created, regardless
Engine->>Docker: run_container(id) — once every container the task's own depends on is ready
Docker-->>Main: started
par the main command
Main-->>Engine: runs to completion, logs streamed live to stdout
and ratect-compat only: the task container's own readiness gate, gating nothing
Engine->>Docker: wait_for_container_healthy(), then exec_in_container() per setup command
Note over Engine: a failure cancels a still-running main command;<br/>the main command's exit ends the gate (see Known limitations)
end
Engine->>Docker: cancel_build() for each BuildKit build the run stopped waiting for, whatever --no-cleanup* says
Note over Engine: cleanup — runs even if the task's container failed,<br/>unless --no-cleanup* says otherwise
Engine->>Docker: stop_and_remove_container() for the task's own container
Engine->>Docker: stop_and_remove_container() for each dependency, in reverse dependency order
Engine->>Docker: remove_network()
Dependencies are stopped and removed in reverse dependency order: a container only
after every container that depends on it, so a dependent shutting down can still reach
what it depends on. A dependency whose dependent’s stop failed is still stopped.
Containers with nothing left depending on them are stopped at the same time, so
independent dependencies take one grace period between them, not one each.
Under -o all each step is reported as it happens: Container stopped. (for a container the run started) then Container removed. on each container’s
own prefix, and Removing task network... then Task network removed. on the task’s.
An image build that hasn’t finished when the run ends — because of a termination signal,
or because another container failed — is cancelled before anything is removed, and
under --no-cleanup* too: a BuildKit build would otherwise run on in the daemon to the
end of its steps. A cancel that fails is a warning naming the container. The classic
builder has no cancel; the daemon stops a classic build on its own some seconds after
Ratect disconnects from it.
If the container has no dependencies, the dependency steps (the loop above) are
skipped — but the network is still created and the task’s own container still joins
it, isolating it just the same as a task with dependencies.
--no-cleanup-after-failure skips the cleanup step above for a genuine infrastructure
failure (a build/pull/health-check/setup-command failure, or anything else before the
task’s own container gets to run — or, under ratect-compat, its own health check or
setup commands failing while its main command is still running, which cancels it);
--no-cleanup-after-success skips it when the
task’s own container ran to completion instead, regardless of its exit code (a
non-zero exit is still “success” for this purpose — it’s the task’s own container
actually running that matters, not what it returned); --no-cleanup is both at once.
Either way, everything above is left genuinely running, not just present-but-stopped
— see CLI reference. The success flag keeps the named task’s
resources alone: a prerequisite is always cleaned up after success, so only the task
you asked for is left to investigate. The failure flag applies to whichever task
failed, prerequisites included.
pull_image() in the diagram above is conditional on image_pull_policy (see config
reference): IfNotPresent, the default, checks whether
the image already exists locally first and skips the pull entirely if so; Always
skips that check and pulls unconditionally. Either way, the decision (pull or don’t)
is made once per image name and policy per run — a dependency and the task’s own
container sharing both don’t re-decide for each other, but an Always container
still pulls when another container already found the same image locally under
IfNotPresent, and an IfNotPresent one still checks locally when an Always
one pulled it. The container is then created from the image’s
ID — the one the pull fetched, found by the digest it reported, or the local one —
not from its name, so a tag moved by another pull meanwhile doesn’t change what
runs, as in Batect.
Passing --use-network <name> skips network creation and teardown entirely for every
task in this invocation: the named network is checked to exist up front (a clear error
if it doesn’t), and reused instead — dependencies and the task’s own container all join
it exactly as they would a freshly-created one, but it’s never removed at cleanup,
since Ratect didn’t create it. See CLI reference.
Dependency resolution
What happens between create_network() and the task’s own container starting
in the diagram above — how a dependency graph’s independent branches start
concurrently, why a shared dependency starts once, and what a dependency has to
pass before anything that depends on it starts — is its own page: Dependency
Readiness.
Cross-task isolation
Because dependency resolution is scoped to a single task execution, two different
tasks that each depend on the same container name get their own separate instance —
nothing is shared or deduped across tasks, even within one ratect invocation:
[tasks.migrate]
run = { container = "app", command = "run-migrations.sh" }
[tasks.test]
prerequisites = ["migrate"]
run = { container = "app", command = "run-tests.sh" }
Both migrate and test here depend on database (via app’s container config).
Running ratect run test starts a database instance, its own network, runs migrate,
cleans both up — then starts a second, independent database instance and network
for test. This matches Batect’s own documented behavior (“each task will start its
own instance of each container, even if multiple tasks share the same container”) and
is also what makes concurrent ratect invocations on the same host safe: each task
execution names its network and containers with a random six-character suffix of
its own — <project>-network-<suffix> and <project>-<container>-<suffix>, as
Batect names them — so two runs never share a container, nor a network Ratect
created. In the rare case two draw the same suffix, the second run fails
rather than join the first one’s network, but how depends on the daemon:
-
Docker 25 and later refuse its network when it’s created (
network with name <project>-network-<suffix> already exists), before any of its containers exist. -
Docker 20.10 to 24 create a second network with the same name, and the second run then fails at one of two points:
- If the first run’s containers still exist, creating the second run’s
containers fails, because their names are taken (
The container name "/<project>-<container>-<suffix>" is already in use). - If only the first run’s network is left — after
--no-cleanup, say — the second run’s containers are created, and starting the first of them fails (network <project>-network-<suffix> is ambiguous (2 matches found on name)).
In both cases the second run’s cleanup can’t remove its network by name, for the same ambiguity, so it reports that network as left behind. The
docker network rm <project>-network-<suffix>it suggests is refused too, and removes neither network. Remove each one by the IDdocker network lsshows, or, underratect, withratect resources clean, which removes by ID. - If the first run’s containers still exist, creating the second run’s
containers fails, because their names are taken (
Known limitations
- Under
ratect-compat, the task’s own container’s readiness gate can race a fast main command — and “main command” is usually a task-specific override. A task’srun.command/run.entrypoint(see TaskRun) replaces whatever the container’s owncommand/entrypoint, or the image’s defaultCMD, would otherwise run — often to run a one-off command (psql, a one-shot migration script) against a container that’s really built for something else, a long-running service. That override is what actually starts the instant the container starts. It is never gated on the container’s ownhealth_check/setup_commands— underratect-compatthe task’s own container goes through the same readiness gate a dependency does (health-check wait, thensetup_commands, in order), but run concurrently with the main command rather than blocking it, because nothing else in the graph depends on the task container’s own readiness. A setup command or health-check failure while the main command is still running cancels it and fails the task, as Batect does (after up to two seconds — see below); the container is then stopped and removed like any failed run’s. That includes ahealth_checkwritten for the container’s usual, non-overridden role, which a one-off command doesn’t make go away. Once the main command has exited, the gate no longer decides anything: a non-zero exit code is the task’s result, and an exit 0 succeeds whatever the gate was still doing. The health wait sees the container stop before Docker reports a health status; a setup command can’tdocker execinto a container that has stopped, or is killed with it mid-run (exit code 137, typically). None of those say anything about the container’s readiness, so the task succeeds, where Batect fails it. The cost is that a setup command genuinely failing at the same moment the main command exits 0 is forgiven too. A setup command that fails because the main command has just exited can be reported before Docker has marked the container stopped, so a gate failure while Docker still reports the container running, or can’t say, waits up to two seconds for the main command’s own result before cancelling it. A main command that exits within that window decides the task as above, so one exiting 0 up to two seconds after a setup command genuinely failed is forgiven too. The race that leaves: a main command that has in fact exited 0, but whose exit Docker reports more than two seconds after the setup command’s failure, is cancelled, and the task fails with the setup command’s error. Underratectnone of this applies: a task’s own container has no readiness gate at all (see Dependency Readiness). - Prerequisite tasks stay sequential, matching Batect exactly —
prerequisitesentries run one after another, each to completion, never concurrently with each other or with the task that named them (see “Task ordering” above). This is Batect’s own behavior (TaskExecutionOrderResolver/SessionRunner), not a Ratect simplification — Batect doesn’t parallelize independent prerequisite tasks either. Running independent prerequisites concurrently remains a possible Rust-specific enhancement beyond Batect, tracked as ratect#102, not something planned. - Minimal networking. The network created here exists only to make dependency
containers reachable by name for the duration of one task (or, with
--use-network, an existing network you reuse instead). It’s not the fully-configurable Docker networking Batect offers (custom drivers, other than by pre-creating the network yourself) — see differences from Batect.
Coming from Batect? Its own task lifecycle page describes the model this one is a deliberately simplified version of; the limitations above say where the two match and where they differ.