Dependency Readiness
A dependency container being started doesn’t mean it’s ready — a database
accepts connections some time after its process launches. This page is the one
place for what “ready” means, how Ratect waits for it, and how several
dependencies’ waits combine into one task’s start-up. The fields themselves
(dependencies, health_check, setup_commands) are in the batect.yml
reference; a
ratect.toml dependency reads them the same way (see Field
reference), which is what the
running example is written in. A task’s own container is the one place the
two binaries differ — see The task’s own container.
That example, throughout, is
examples/full-stack’s
db container — a real postgres:16 gated on pg_isready, whose init script
bulk-seeds a million-row table, and which then runs a real setup_commands
entry once it’s healthy:
[containers.db]
image = "postgres:16"
environment = { POSTGRES_HOST_AUTH_METHOD = "trust" }
volumes = [{ local = "db/init", container = "/docker-entrypoint-initdb.d" }]
health_check = { command = "pg_isready -h 127.0.0.1 -U postgres", interval = "1s", retries = 90 }
# ANALYZE needs a real, committed table to work against, which is exactly
# what setup_commands is for — running once db is healthy, not baked into
# the init script that creates and seeds that table in the first place.
# Genuinely useful here, not just illustrative: a bulk INSERT this size
# leaves the query planner without fresh statistics until something
# collects them, and the journey-test/app queries below count() this table.
setup_commands = [
{ command = "psql -U postgres -c \"ANALYZE visits;\"" },
]
app depends on db and on cache (a redis:7 with its own health check),
and the journey-test task depends on app and, again, on cache. app
itself is checked a third way — an
external_health_check
requesting /healthz from outside it, which reports exactly as the other two
do. ratect run journey-test -o simple, captured on a terminal in examples/full-stack:
Running journey-test...
Starting cache...
Starting db...
Started cache.
Started db.
cache has become healthy.
db has become healthy.
Running setup command psql -U postgres -c "ANALYZE visits;" (1 of 1) in db...
db has completed all setup commands.
Starting app...
Started app.
app has become healthy.
Running sh -c 'npm ci && node test.js' in journey-test...
added 6 packages, and audited 7 packages in 983ms
found 0 vulnerabilities
app responded: {"message":"Hello from Ratect!","visit_id":1000001,"total_visits":1000001,"count_source":"database"}
cache holds visits:count=1000001, confirming app and this container share the same cache
journey test passed
Cleaning up...
journey-test finished with exit code 0 in 9.1s.
The recording on the homepage is the same command in fancy mode.
db takes longer than cache because it’s genuinely seeding that table before
its health check can pass, not because anything is padded. The rest of this page
is what the lines between Starting db... and Starting app... mean.
The readiness gate
Matching Batect, a dependency must pass one readiness gate, in two steps in order, before anything that depends on it (another dependency, or the task’s own container) starts:
-
It must report healthy. If the container has a Docker health check — from its image’s own
HEALTHCHECK, from thehealth_checkfield, or both — Ratect waits for Docker’s verdict: proceeds on healthy; fails the task on unhealthy (the error includes the last health-check run’s exit code and output, unless the container or the daemon has gone by the time Ratect looks them up) or if the container exits first. A container with no health check at all is immediately considered healthy — for it, started is ready. In the transcript, this step is the gap betweenStarted db.anddb has become healthy.This step is Docker’s own health check, so it needs a shell and a check tool inside the image. If yours has neither — a distroless or
scratchbuild — aratect.tomlcontainer can be checked from outside instead, withexternal_health_check, which then replaces this step, imageHEALTHCHECKincluded. -
Its
setup_commandsmust succeed. Each runs inside the running container (via Docker’sexecmechanism), one at a time in declared order, with the container’s ownenvironmentand the same user/group the container runs as (under User mapping or, in aratect.toml,user/group). A command exiting non-zero fails the task, with its output in the error. In the transcript,Running setup command psql -U postgres -c "ANALYZE visits;" (1 of 1) in db...is this step, andStarting app...doesn’t appear untildb has completed all setup commands.
A ratect.toml setup command can run somewhere else:
run_in
(ratect-native only) names one of the declaring container’s own dependencies
to exec into instead, for the case where the tooling a setup step needs lives in
a different image — seeding a database from a client container, say. When it
runs is unchanged: it is still the second step of the gate of the container
that declares it, so
nothing depending on that container starts until it has succeeded. The
restriction to that container’s own dependencies is what makes it safe, and is
explained in that field’s own section.
Whichever step fails, the task fails, and already-started containers are still
cleaned up as usual. The error ends by suggesting --no-cleanup-after-failure,
which keeps those containers in place so you can look inside the one that
wasn’t ready; with that flag (or --no-cleanup) given, there is nothing to
suggest, and the error ends without it.
A ratect.toml dependency can opt into a different readiness gate entirely:
run_to_completion
(ratect-native only — batect.yml has no equivalent) replaces “healthy, then
setup commands” with running to completion and exiting 0 — Kubernetes-style
init-container behavior, still just a node in the same dependency graph
described below. It participates in resolution exactly like any other
dependency (concurrent with an unrelated branch, deduplicated if shared,
nestable either directly under a task’s own dependencies or under another
dependency’s); the only difference is what “ready” means for it. What it
rejects, and why it isn’t a substitute for prerequisites, is in that field’s
own section.
A ratect.toml container can also be checked from outside itself:
external_health_check
(ratect-native only) makes an HTTP request or a bare TCP connection to the
container over the project’s own network, for an image with no shell and no
check tooling to run the first step with — a distroless or scratch build. The two
are different concepts rather than two spellings of one: health_check is
Docker’s own HEALTHCHECK, owned by the daemon and re-run for the container’s
whole lifetime, while this is closer to a Kubernetes readiness check — asked
once, from outside, with no opinion about the container’s health afterwards.
(Ratect has no equivalent of a liveness check in either form.) It alone
decides readiness: an image’s own HEALTHCHECK still runs, but Ratect
doesn’t wait on it. It is
config-level sugar over run_to_completion rather than a gate of its own:
declaring one generates a companion container that loops the check and exits
0 or non-zero, and everything that depended on the checked container depends
on that companion too. None of that surfaces — the companion narrates nothing
of its own, and the checked container reports has become healthy. when the
check passes, exactly as it would for a health_check. So the resolution
described below is unchanged.
How Docker reaches its verdict
This is Docker’s own behavior, not Ratect’s, but it’s what actually determines how long the first step waits and when it fails, so it’s worth spelling out:
- A freshly started container with a health check isn’t unhealthy — it’s in a
third state,
starting, until Docker reaches a first verdict. Docker runscommandeveryinterval; the first success makes the container healthy, and onlyretriesconsecutive failures make it unhealthy. Withdb’s settings above (interval = "1s",retries = 90), the earliest possible unhealthy verdict is about ninety seconds in — a health check can’t “fail fast” on its first bad run, anddb’s generousretriesis exactly what gives its million-row seed the time it needs. - Failures during
start_perioddon’t count towardretriesat all — that’s the grace period for slow-booting services — but a success during it still flips the container healthy immediately. - Ratect waits for that first verdict, and only the first: matching Batect, a dependency’s health is never re-checked once its dependents have started, even though Docker keeps running the check for the container’s whole lifetime and the state can flip later. See Once ready below for what Ratect does instead.
While a task appears to hang on a dependency, docker ps shows each container’s
health state in its STATUS column (health: starting, etc.), and
docker inspect --format '{{.State.Health.Status}}' <container> shows it
directly — .State.Health.Log keeps the last few check runs’ exit codes and
output, which is also where the detail in Ratect’s “did not become healthy”
error comes from.
Ratect imposes no timeout of its own on the health wait (matching Batect) —
Docker’s own interval/retries bound how long a verdict can take, so a health
check configured to retry forever waits forever.
Resolution order
Dependencies are resolved concurrently, gated by readiness — and the gate is
on starting: a container with dependencies of its own never starts before
every one of them is ready, but two containers with no dependency relationship
to each other start at the same time rather than one after the other. Nothing
before the start waits for it: every container’s image in the task’s graph, the
task’s own included, is pulled or built from the moment the task’s network
exists, and each container is created as soon as its own image is ready, so a
pull, build or create that fails — an image that doesn’t exist, a device or
mount that doesn’t — ends the task as soon as it fails, not once every
dependency is ready and its setup commands have run, and the pulls along a
chain overlap rather than each following the previous container’s readiness.
A container sharing another’s network (network_mode = "container:<name>",
ratect.toml only) is the one exception, and only partly: it is created once
its target has been created, since Docker needs the target’s id, and started
once the target is ready, like anything else. For example:
[containers.app]
image = "my-app"
dependencies = ["database"]
[containers.database]
image = "postgres:16"
dependencies = ["cache"]
[containers.cache]
image = "redis:7-alpine"
graph TD
app["app (task's container)"] --> database
database --> cache
Running a task against app starts pulling all three images at once, and
creates each container as its image lands. cache starts as soon as it is
created (nothing else is holding it back), then database once cache is
ready, then app once database is ready — a straight chain, so each start
is genuinely waiting on the last. All
three share one network and are reachable by their container-config name (e.g.
app’s command can reach database:5432 and cache:6379).
Add a second container that also depends on cache — say queue, also one of
app’s dependencies, but with no relationship to database — and cache is
now a shared dependency of two others, forming a diamond rather than a
straight chain:
graph TD
app["app (task's container)"] --> database
app --> queue
database --> cache
queue --> cache
sequenceDiagram
participant Engine as TaskEngine
participant Cache as cache
participant Database as database
participant Queue as queue
participant App as app (task's container)
Note over Engine: cache has no dependencies of its own — starts immediately
Engine->>Cache: start, wait for healthy, run setup commands
Note over Cache: ready
par database and queue both depend only on cache — start together,<br/>the moment it's ready, not one after the other
Engine->>Database: start, wait for healthy, run setup commands
Note over Database: ready
and
Engine->>Queue: start, wait for healthy, run setup commands
Note over Queue: ready
end
Note over Engine: app depends on both database and queue —<br/>waits for whichever is slower before starting
Engine->>App: start (runs to completion)
cache is only ever started once, even though both database and queue
depend on it: whichever of the two reaches it first triggers the actual start,
and the other waits on that same in-flight readiness rather than starting a
second instance or pulling its image twice (see below — this holds generally,
not just for a leaf like cache). database and queue then
genuinely overlap in time — both start the moment cache’s readiness gate has
actually passed, not just once its container exists, and neither waits on the
other since they share no relationship. app is gated on whichever of the two
takes longer, not just the first one to finish.
examples/full-stack has the same ingredients with real names: journey-test
depends on app and cache, and app depends on db and cache. db and
cache are unrelated branches, so the transcript above starts them together;
app waits on both, so Starting app... follows db has completed all setup commands.; and cache, reached by journey-test directly and by app, starts
once.
More generally, within one task’s resolution any dependency shared by two
others — not just a leaf like cache — is only ever started once, no matter how
many dependents reach it or how deep in the graph they sit, including when they
reach it genuinely concurrently: the second to arrive waits on the first’s
already-in-flight readiness rather than starting a second instance or
double-pulling its image. A circular container dependency (a depends on b
depends on a), or a container depending on itself, is detected up front and
reported as an error rather than hanging: after the task’s prerequisites have
run, but before the task itself starts, so there’s no Running line, no task
network is created, and nothing is cleaned up.
This concurrency is unbounded by default — every container’s pull/build and
create, every dependency’s start, and every setup command can all be in
flight at once, across the whole invocation, not just within one task.
--max-parallelism <N>
caps it: at most N of those specific operations run at a time,
invocation-wide. A create and a start are separate capped steps, and a
container holds no slot while it waits for its dependencies to be ready, so a
chain longer than N can’t deadlock. The health-check wait itself is
deliberately not capped (it’s a polling wait, not real work), so two
dependencies can still become healthy at the same time even under a low cap —
only the pull/build/create/start/setup-command steps queue up behind it. See CLI reference and
differences from Batect for exactly
what’s covered.
A task’s own dependencies (sidecars scoped to that task specifically) join
this same resolution at the root, alongside its container’s own — each still
resolves its own container-level dependencies transitively from there, same
as any other dependency, and is just as eligible to start concurrently with an
unrelated branch. And a task’s customise map, if it has one, is checked
against whichever dependency is starting: a match overrides that container’s
environment/ports/working_directory for this task’s run of it
specifically (merged the same way a task’s own run overrides its main
container — see config
reference),
before it starts, regardless of how deep in this graph it sits.
Once ready
Health is a one-time gate in this sequence, not ongoing monitoring (the verdict lifecycle above): a dependency that turns unhealthy after its dependents have started doesn’t affect the rest of the task.
Not re-checking health doesn’t mean staying silent, though: a dependency that
has already become ready and then exits on its own — while the task’s own
command, or a later dependency’s own health/setup wait, is still going — prints
a progress line naming the container and its exit code, in every output style
except quiet. Without
it, that container’s own death would otherwise surface later as a confusing
symptom in whatever depended on it (a connection refused, a timeout) rather
than the real cause. This is a notification only — the run isn’t failed or
stopped because of it — and it’s never printed for a container cleanup itself
stops: Ratect stops watching a dependency for this the moment the task’s own
execution finishes, strictly before cleanup ever touches a container. Nor is
it printed for a run_to_completion dependency: its exit is
how it became ready in the first place, not a later surprise, so there’s
nothing unexpected to report.
The task’s own container
Which rules apply depends on which binary loaded the project, ratect or
ratect-compat, not on which file declares the container.
ratect(native): no readiness gate. Running the task’s own container is the task, and nothing depends on it becoming ready. Ratect doesn’t wait for its health check, whether fromhealth_checkor the image’s ownHEALTHCHECK, and doesn’t run itssetup_commands. The task’s result is the main command’s alone. Docker still runs the health check; Ratect doesn’t watch it. Nor doesrun_to_completionchange anything: the container runs as the task, exactly as it would without it. The fields stay valid on that container, since the same container can be another task’s dependency.ratect-compat(Batect-compatible): the same gate as a dependency, run concurrently with its main command rather than gating anything on it — matching Batect, which runs every container through identical per-container steps, task container included. A failure there while the main command is still running stops it and fails the task — after waiting up to two seconds for the command’s own exit, which decides the task instead if it arrives. Once that command has exited, with any code, whatever the gate was still doing — a health wait, a setup command the container’s exit killed — is dropped, and after an exit 0 a failure it already reported isn’t one. That, and the race it leaves open, are in known limitations; where Ratect differs from Batect on it is in Differences from Batect.