Introduction
Define your development tasks — build, test, lint, a database to develop against, … — once in configuration, and run them identically on any machine that has Docker. No “works on my machine”, no per-developer setup drift, no JVM to start: Ratect is a single native binary, so it runs instantly.
If that sounds like Batect, that’s
deliberate: Batect was archived in October 2023, and Ratect grew out of it —
same batect.yml, running on a native binary instead of a JVM one. But it’s
not just a port: Ratect already fixes real bugs Batect never got to (leaked
containers and networks on anything but Ctrl+C, an eight-year-old open proxy
issue) and adds tooling Batect
never had — ratect doctor, ratect resources, a native ratect.toml
format. See Differences from Batect for the
full list, drop-in replacement included. It’s an independent project, not
affiliated with or endorsed by the original Batect project.
See it in action
A real request against a real, composed stack — an app, a database, and a
cache, each waiting for the last to actually be ready (not just
“started”) before it starts itself — no wait-for-it.sh, no manual
networking, no leftover containers once it’s done. This is the dependency
graph from
examples/full-stack
— that project also has build/unit-test/run/lint/shell tasks, omitted
here to keep this to the part that’s actually running below:
ratect_version = "0.13.0"
project_name = "ratect-full-stack"
[containers.app]
image = "node:22"
working_directory = "/code"
enable_init_process = true
ports = [{ local = 8080, container = 8080 }]
environment = { DATABASE_URL = "postgres://postgres@db:5432/postgres", REDIS_URL = "redis://cache:6379" }
volumes = [
{ local = "app", container = "/code" },
{ type = "cache", name = "full-stack-npm-cache", container = "/root/.npm" },
]
# Not just for `run` — `app` cannot even start without both (it connects to
# `cache` at module load, and `db` on its first request), so this belongs
# on the container itself rather than repeated on every task that uses it.
dependencies = ["db", "cache"]
command = "sh -c 'npm ci && npm start'"
# Checked from outside, over the project's own network, instead of by the
# `node -e` one-liner this used to be — escaping quotes inside a TOML string
# to make a single HTTP request. `node:22` is a full Debian image and could
# run that check itself; the field exists for images that can't (distroless,
# `scratch`), and is used here because the declarative form says what is
# actually meant. Nothing runs inside `app` to prove it is ready.
[containers.app.external_health_check]
type = "http"
port = 8080
path = "/healthz"
interval = "1s"
retries = 20
[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;\"" },
]
[containers.cache]
image = "redis:7"
health_check = { command = "redis-cli ping", interval = "1s", retries = 10 }
[containers.journey-test]
image = "node:22"
working_directory = "/code"
environment = { REDIS_URL = "redis://cache:6379" }
volumes = [
{ local = "journey-test", container = "/code" },
{ type = "cache", name = "full-stack-npm-cache", container = "/root/.npm" },
]
command = "sh -c 'npm ci && node test.js'"
[tasks.journey-test]
description = "Exercise the running app end to end, sharing `cache` with `app`"
group = "Development"
dependencies = ["app", "cache"]
run = { container = "journey-test" }
A real recording, not a mockup — fancy output shows all four containers’
status live, updating in place, each independently: db seeding a real
million-row table before it’s ready (genuinely, not padded — that’s why it
takes longer than app/cache), then running a real setup_commands step
(ANALYZE visits, giving the query planner fresh statistics after that
bulk insert) once it’s healthy but before anything depends on it, then
app and journey-test both starting only once cache says it’s ready —
cache itself, once, even though it’s a dependency of both. journey-test
makes a real HTTP request to app (the JSON in the middle is its real
response), then checks Redis directly to confirm the value app read
got cached — see Dependency Readiness
for the full model behind all of it. Every container is removed afterwards
regardless of how the task ends.
Two binaries, two formats
Ratect ships two binaries. ratect reads its own ratect.toml format and is
the one to install if you’re starting fresh — it’s the forward-looking CLI, free
to add things Batect never had. ratect-compat reads a batect.yml
unchanged, as a drop-in replacement for the (now unmaintained) batect binary,
and stays batect.yml-only permanently — pick it if you already have a Batect
project and want a maintained tool without editing any YAML. Both run the same
engine and exit with the same codes, are versioned and released independently,
and can be mixed: ratect -f batect.yml reads a Batect config too, a
ratect.toml project can include a batect.yml fragment as-is, and
ratect config convert translates a whole batect.yml
when you’re ready to move.
Where to go next
- New here? Start with Installation and Getting Started, or jump straight to a worked example for your language.
- Coming from Batect? Start with Migrating a Batect Project to Ratect, then Differences from Batect for what to expect.
- Weighing Ratect against Docker Compose, Make, Task, Earthly, Dagger or
just? See How Ratect Compares to Other Tools. - Already running tasks and want to know what a run actually does, or why a dependency counts as ready? Task Lifecycle and Dependency Readiness, then Troubleshooting when a run fails or hangs, File Ownership and the Home Directory when what it writes isn’t yours, and the FAQ and Includes as the questions come up.
- Looking for a specific flag or config field? Jump to a reference:
ratectCLI ·ratect.toml·ratect-compatCLI ·batect.yml.
Source and issue tracker: or1can/ratect.
How Ratect Compares to Other Tools
This page compares Ratect against what a project is actually likely to be
choosing between today: Docker
Compose,
Make,
Task,
Earthly,
Dagger, and
just.
None of these six exist to lose to Ratect. Each was built to solve a real problem, several of them solve it better than Ratect does for the case they targeted, and picking the right one is usually about which problem you actually have — not which tool wins a feature count. What follows is honest about both directions.
Reach for Ratect when the problem is running development tasks
identically on every machine, isolated from your host and from each other,
with real dependency orchestration. Two of those are for free just by
running in Docker at all: the image is built the same way regardless of
what’s on your host (reproducibility), and by default each run gets its own
disposable network — created fresh per invocation, named after that run,
torn down after — so containers on one run can’t reach containers or ports
from another (isolation), unless you deliberately opt out with
--use-network. The third — a database or another service that needs
to actually be ready, not just started, before your task touches it — is
Ratect’s own design, not a side effect of Docker. That’s a narrower claim
than “runs my project”; the sections below say plainly where it isn’t the
best fit.
Docker Compose
Compose defines and runs multi-container applications — the closest match to Ratect in shape (containers, networks, dependencies between them), and the one most likely to already be sitting in a project you’re looking at.
Where Compose wins: it’s the default, not an alternative you have to
choose — ships with Docker Desktop and Engine, and most developers already
know it. Bringing up a stack and leaving it running (the actual point of a
docker-compose.yml) needs less ceremony in Compose than expressing the
same thing as a Ratect task, because that’s what Compose is for and
Ratect’s task model isn’t. docker compose watch gives you a live dev
loop with no equivalent in Ratect at all.
Where Ratect wins: Compose has no task layer — no prerequisites, no
distinct build/test/lint verbs, no per-invocation ephemeral
containers. depends_on: condition: service_healthy gates start order on
a health check, which is real and useful, but Compose has nothing like
setup_commands — a scripted
step that runs inside a dependency once it’s healthy but before anything
depends on it starts. Seeding a database before code touches it means an
init container or an entrypoint script you write and maintain yourself;
in Ratect it’s a config field. The isolation model differs too: a Compose
stack is meant to be brought up once and left running, its network and
containers shared across however many docker compose exec calls you make
against it afterward. Ratect’s network and containers, by default, are
scoped to one task invocation and torn down when it finishes, rather than
persisting for the next run to reach. And a Compose service runs as its image’s
user unless you set user: to a uid yourself, so on a rootful Linux daemon what
it writes through a bind mount is usually root’s, where Ratect’s
identity runs the container as you there, and gives it the same
$HOME on every daemon.
Make
GNU Make — the original. Targets, prerequisites, recipes, and a dependency graph driven by file timestamps — genuinely incremental, in a way nothing else on this page (Ratect included) fully replicates.
Where Make wins: it’s already installed, on nearly every Unix-like system, with zero extra daemon and zero extra dependency — spinning up Docker for a one-line shell command is real overhead Make never pays. Make’s own incremental rebuild — skip a target outright if its prerequisites’ files haven’t changed — is a genuine capability Ratect doesn’t have; a Ratect task always runs, and whether the tool inside the container decides to skip work is between that tool and its own cache, not something Ratect tracks itself.
Where Ratect wins: Make runs on whatever’s already on your host — the exact “works on my machine” problem Ratect exists to remove, and whatever a recipe installs, writes, or leaves running stays on your host too, since Make has no isolation from it at all. It also has no native model for orchestrating dependent services (bring up a database, wait for it, run something against it); that’s shell script bolted onto a recipe, not something the tool understands.
Task
Taskfiles — YAML, explicitly positioned as “inspired by Make, designed for modern workflows.” Closest in spirit to Ratect and Batect’s own “define tasks in a file” model of any tool here — but Task runs on the host by default; Docker is something you can reach for per-task, not the execution model itself.
Where Task wins: far lighter for tasks that don’t need containerizing
at all — no daemon, near-instant startup, and it works the same on Windows
without Docker Desktop in the loop. Its sources/generates fields give
file-based skip-if-unchanged tracking similar to Make’s, which Ratect has
no equivalent of.
Where Ratect wins: the same reproducibility and isolation gap as Make — Task’s default is your host toolchain, so “works on my machine” is back on the table unless you deliberately containerize each task yourself, and even then there’s no built-in service-dependency/readiness model to reach for.
Earthly
Worth naming plainly: Earthly is no longer actively maintained — its own README says so directly, pointing at a post titled “shutting down Earthly Cloud.” Its last tagged release was mid-2025. Comparing against it now is closer to Ratect’s own relationship with Batect than a live rivalry.
While it was under active development, Earthly’s actual design point was a
containerized build framework — Dockerfile-and-Makefile-flavored syntax,
BuildKit-based, with a real target-level build-cache graph more
sophisticated than Ratect’s cache volume mounts for the specific job of
producing cacheable build artifacts identically locally and in CI.
Where Ratect wins today, practically: it’s maintained. Setting that
aside, the two tools’ centers of gravity differ anyway — Earthly is oriented
around building artifacts; Ratect’s health_check/setup_commands/
dependencies model is oriented around running and orchestrating live
services, which was never Earthly’s target.
Dagger
A programmable automation engine, not a config format: pipelines are code, in a real language (Go, Python, TypeScript, and others), compiling down to containers as Dagger’s own primitive. The pitch is portability — the same pipeline runs on your laptop, in CI, or in Dagger’s own cloud — backed by built-in OpenTelemetry tracing.
Where Dagger wins: a real programming language for pipeline logic —
loops, conditionals, functions, tests for the pipeline itself — which
ratect.toml/batect.yml’s declarative shape deliberately doesn’t offer,
and isn’t trying to. For a genuinely complex pipeline that outgrows what a
static config file can express cleanly, that’s a real advantage, not a
rounding error.
Where Ratect wins: simplicity for the common case. Most projects need
“run these containers, in this order, with these dependencies” — a small
TOML/YAML file to read and edit, not SDK code in a general-purpose language
to write and maintain. Ratect’s Batect-compatibility story (an existing
batect.yml keeps working, field-for-field) also has no Dagger analogue —
Dagger is a from-scratch mental model, not a migration path from anything.
just
Its own README calls it “a command
runner, not a build system” — a deliberate, stated distinction from Make,
not an oversight. justfile recipes run on the host, with none of Make’s
dependency-graph or incremental-rebuild machinery.
Where just wins: about as light as this category gets — a single
small binary, no daemon, recipes that are just shell commands with better
ergonomics (parameters, cross-platform support, no .PHONY workarounds).
For “give me short, memorable names for the commands I run all the time,”
reaching for Ratect and its Docker daemon is real overhead for no benefit.
Where Ratect wins: just doesn’t attempt reproducibility or isolation
at all — recipes run in your own shell, on your own machine — and it has no
service-orchestration model whatsoever. Neither is a flaw in just; it’s
explicitly not trying to be either of those things.
If you’re choosing
| Reach for… | when the problem is |
|---|---|
| Ratect | development tasks that need to run identically everywhere, isolated from your host, and/or real services (a database, another API) they depend on actually being ready first |
| Docker Compose | bringing up and living inside a multi-container stack, more than running discrete tasks against it |
| Make | you already have make everywhere you need it, and don’t need containers, isolation, or cross-machine reproducibility |
| Task | Make-like ergonomics without Make’s own syntax, for tasks that don’t need Docker |
| Dagger | a pipeline complex enough to genuinely need a real programming language, not a config file |
just | short, memorable shortcuts for commands you already know how to run |
Earthly isn’t in that table on purpose — recommending an unmaintained tool for new work doesn’t make sense regardless of what it used to be good at; see its own section above for what that was.
Nothing here is exclusive — a real project often uses more than one of
these at once (a justfile that shells out to ratect run, or a Compose
stack a Ratect task talks to). This is a guide to which problem each tool
was built for, not a bracket with one winner.
Coming from Batect? Its own comparison page ranged over shell scripts, Docker
Compose, Dojo, Earthly, CI tools with a
local runner (GitLab CI, CircleCI), and Vagrant — reasonable choices when it
was written. Of those, Docker Compose and Earthly are the two this page also
covers. To move a batect.yml project over, see Migrating a Batect Project
to Ratect.
Starting fresh rather than from a batect.yml? Installation
is next.
Installation
Prebuilt binaries
Every tagged release of ratect-compat or ratect publishes prebuilt
binaries as GitHub Release assets, for five platforms:
| Target triple | Platform | Minimum OS |
|---|---|---|
x86_64-unknown-linux-gnu | x64 Linux | glibc 2.34 or later |
x86_64-unknown-linux-musl | x64 MUSL Linux (Alpine, minimal containers) | No shared libc: statically linked |
aarch64-unknown-linux-musl | ARM64 MUSL Linux (ARM servers, Raspberry Pi) | No shared libc: statically linked |
x86_64-apple-darwin | Intel macOS | macOS 10.12 or later |
aarch64-apple-darwin | Apple Silicon macOS | macOS 11.0 or later |
Ubuntu 22.04, Debian 12 and RHEL 9 and later ship glibc 2.34 or newer. On a
distribution whose glibc is older, such as Ubuntu 20.04, Debian 11 or RHEL 8,
use the x86_64-unknown-linux-musl build, which needs no shared libc at all.
Raising any of these minimums is a breaking change, listed as one in the
changelog.
ratect-compat and ratect are tagged and released independently (see Two
binaries, two formats), so they’re listed as
separate entries on the Releases page
— tags look like ratect-compat/vX.Y.Z and ratect/vX.Y.Z. Find the most
recent tag for the binary you want, then download the archive matching
your platform from that release’s assets.
Each archive extracts to a directory (named after the archive itself)
containing the binary alongside LICENSE/NOTICE/README.md/RELEASES.md
— the binary isn’t at the archive’s top level:
tar -xf ratect-compat-x86_64-unknown-linux-gnu.tar.xz
mv ratect-compat-x86_64-unknown-linux-gnu/ratect-compat ~/.local/bin/
(substitute the archive name for your platform and binary; ~/.local/bin
assumes it’s already on your PATH — use whatever directory you normally
install user binaries into.)
macOS: Ratect’s binaries aren’t code-signed or notarized. If macOS
refuses to run the extracted binary (“cannot be opened because the
developer cannot be verified” or similar — some download methods, like a
browser, mark a downloaded file quarantined; others, like curl, don’t),
clear it:
xattr -d com.apple.quarantine ratect-compat-x86_64-apple-darwin/ratect-compat
Homebrew
Each release also publishes a formula to a shared tap
(or1can/homebrew-tap) for both
binaries:
brew install or1can/tap/ratect-compat
brew install or1can/tap/ratect
Install script
Each release also publishes a shell installer that downloads, verifies, and extracts the right archive for your platform in one step:
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/or1can/ratect/releases/download/ratect-compat/vX.Y.Z/ratect-compat-installer.sh | sh
Substitute the tag (ratect-compat/vX.Y.Z or ratect/vX.Y.Z) for the
release you want, and ratect-compat-installer.sh/ratect-installer.sh for
the matching binary — see the Releases page
for both. Installs to $CARGO_HOME/bin (or $HOME/.cargo/bin), adding
that directory to PATH via your shell profile if it isn’t already there.
Verifying a download
Each release also includes a sha256.sum covering every archive and the
source tarball, and every archive/SBOM/sha256.sum itself carries a
GitHub Artifact Attestation
confirming it was built by Ratect’s own CI from the tagged source, not
tampered with in transit:
# Checksum (Linux: sha256sum -c sha256.sum). A trailing blank line in the
# file itself makes shasum warn "1 line is improperly formatted" — harmless,
# every real entry still verifies.
shasum -a 256 -c sha256.sum
# Provenance (requires the GitHub CLI, `gh`)
gh attestation verify ratect-compat-x86_64-unknown-linux-gnu.tar.xz --repo or1can/ratect
Not yet available
cargo-binstall needs Ratect published to crates.io to discover a
release automatically, which is itself blocked — see
decisions/0010’s
crates.io deferral.
Building from source
The from-source path below is for contributors, or anyone on a platform without a prebuilt binary.
Prerequisites
-
Rust (stable toolchain)
-
Docker, running and reachable via the default local socket (Ratect connects the same way the
dockerCLI does — no extra configuration needed for a standard Docker install).Docker 20.10 or newer. Ratect negotiates the Docker Engine API version against your daemon at connection time, downgrading to whatever it offers, so any recent Docker install works with no extra configuration. 20.10 (December 2020) is Ratect’s own floor below that negotiation — the oldest release its features actually require, for the
host-gatewaysentinel behind proxy support — and a daemon older than that is refused with a clear error naming the API version it supports and the one required, rather than some later request failing for an unexplained reason. Check yours withdocker version --format '{{.Server.APIVersion}}'(API 1.41 corresponds to Docker 20.10).
Build from source
Clone the repository, then build release binaries. The workspace has two binary
crates, ratect and ratect-compat — Two binaries, two
formats says which to pick. Building both
costs little extra, since they share almost all of their code:
git clone https://github.com/or1can/ratect.git
cd ratect
cargo build --release -p ratect -p ratect-compat
The compiled binaries will be at target/release/ratect and
target/release/ratect-compat.
Install the binaries onto your PATH
To make ratect and ratect-compat available as regular commands (one line per
binary, so install only the one you want if that’s all you need):
cargo install --path ratect
cargo install --path ratect-compat
This installs to ~/.cargo/bin (assumed to already be on your PATH, which is the
default for a standard rustup install).
Verify the install
ratect --version
ratect --help
ratect-compat --version
ratect-compat --help
Development builds
If you’re working on Ratect itself rather than just using it, a debug build is faster to compile and sufficient for local testing:
cargo build --workspace
cargo run -p ratect -- tasks list
cargo run -p ratect-compat -- --list-tasks
See AGENTS.md for the full contributor-facing tooling setup (formatting,
linting, tests, coverage, dependency auditing).
Next steps
With a binary on your PATH, Getting Started walks
through writing a first ratect.toml and running a task from it. If your
project is in Rust, Go, Node.js, Python or the JVM, the worked
example for it is a config you can copy instead.
Getting Started
This walks through defining and running your first task with Ratect. It assumes you’ve already installed Ratect and have Docker running.
Which binary? This page uses ratect and its ratect.toml format — the one
to install if you’re new here (see Two binaries, two
formats). If you already have a batect.yml,
see Migrating a Batect Project to Ratect instead,
since this page assumes you’re starting from nothing. Nothing below assumes a
brand-new codebase either: writing a ratect.toml doesn’t touch any of your
existing code, build scripts, or CI — it’s one new file describing how to run
what you already have in a container, alongside whatever else the project does
today.
Every file and transcript on this page comes from a real project checked into this
repository, examples/getting-started
— the page builds it up step by step, and a CI job runs every task in it against a
real Docker daemon on every change, so what you read here is what actually runs.
Clone that directory to follow along without typing anything.
1. Create a ratect.toml
ratect reads its configuration from a ratect.toml file in the current directory
(or wherever you point -f/--config-file — see the CLI reference).
The smallest file that runs something:
ratect_version = "0.13.0"
project_name = "getting-started"
[containers.build-env]
image = "alpine:3.24"
volumes = [{ local = ".", container = "/code" }]
[tasks.hello]
run = { container = "build-env", command = "ls /code" }
This defines one container (build-env, based on the alpine:3.24 image, with the
current directory mounted at /code) and one task (hello, which runs ls /code
inside that container). ratect_version records which Ratect the file was written
for, so a later Ratect can tell you when one of its changes affects it — see
ratect_version.
See the configuration reference for the full schema.
2. Run a task
ratect run hello
ratect run hello -o simple, captured on a terminal in examples/getting-started:
Running hello...
Pulling alpine:3.24...
Pulled alpine:3.24.
Running ls /code in build-env...
README.md ratect.toml
Cleaning up...
hello finished with exit code 0 in 1.9s.
README.md and ratect.toml are ls /code’s actual output, streamed live as the
container produces it — in columns, because the container was given a terminal,
exactly as it would be in a shell. Everything else is Ratect’s own framing. A second run skips the pull, since the image is already local.
On a terminal, ratect defaults to its fancy output style, which draws the same
milestones in place as they happen rather than one line at a time; the capture
above asked for simple so it could be shown on a page. See Output Styles for the others.
3. Prerequisites
Tasks can depend on other tasks, which run first:
[tasks.build]
run = { container = "build-env", command = "echo building..." }
[tasks.test]
prerequisites = ["build"]
run = { container = "build-env", command = "echo testing..." }
Running ratect run test runs build to completion, then test. Within a single
ratect run invocation:
- Each task runs at most once, even if it’s a prerequisite of more than one other task.
- Each container image is pulled at most once, even if multiple tasks use it.
- A prerequisite cycle (e.g.
adepends onb,bdepends ona) is detected and reported as an error rather than hanging.
See Task ordering for the details.
4. Environment variables and expressions
A task’s run (and a container) can set environment variables, and a value can pull
in a host environment variable or a declared config variable instead of being written
as a literal:
[config_variables.environment_name]
default = "dev"
[tasks.greet.run]
container = "build-env"
command = "sh -c 'echo $GREETING in $ENVIRONMENT_NAME'"
environment = { GREETING = "hello-${WHO:-world}", ENVIRONMENT_NAME = "<environment_name" }
Running ratect run greet (with WHO unset in your shell) prints hello-world in dev. Override the config variable from the command line instead of relying on its
default:
ratect run greet --config-var environment_name=staging
which prints hello-world in staging.
Note the sh -c: command is split into arguments with no shell involved, so
$GREETING on its own would reach echo as literal text. Ratect’s own ${WHO:-world}
and <environment_name expressions are a different thing — resolved by Ratect before
the container starts, in environment values and a few other fields, never inside
command. See the FAQ for the three
$-syntaxes that look alike, the configuration
reference for the full
expression syntax (including batect.project_directory, always available without
being declared), and the CLI reference for
--config-var/--config-vars-file.
5. List available tasks
With four tasks in the file now, list them:
ratect tasks list
Tasks in getting-started:
- build
- greet
- hello
- test
A task’s optional description and group fields turn this flat list into a grouped
one, with a line of help per task — see Worked Examples
for what that looks like.
6. Reading the output
Ratect separates two kinds of output:
- stdout: the actual output of your command — this is what your task produces, and
what
tasks listprints. Safe to pipe or redirect. - stderr: everything Ratect itself says — its progress (the lifecycle lines, shaped
by
--output), warnings and errors, and its internal diagnostics, logged viatracing. Only the diagnostics answer to theRUST_LOGenvironment variable, e.g.:
RUST_LOG=debug ratect run hello
debug also surfaces low-level Docker API activity (container create/start/remove),
which is useful when troubleshooting — see Filtering
RUST_LOG for scoping it to Ratect’s own
diagnostics.
Next steps
See Worked Examples for a real build/test/run/lint/shell
task set in Rust, Go, Node.js, Python, or the JVM — a faster starting point than
building one up from scratch if your project is in one of those. Once you have a
container running your own toolchain, Using Ratect With Language
Ecosystems covers what to cache and a couple of correctness
gotchas per ecosystem.
Worked Examples
A real, minimal hello-world project for five common ecosystems — Rust, Go,
Node.js, Python, and the JVM — each with build, test, run, lint, and
shell
tasks using that ecosystem’s own usual tooling and base image. shell starts an
interactive shell in the build environment — no config needed beyond the task
itself, since interactive mode is
automatic. It’s the fastest way to poke around when a build environment isn’t
behaving as expected. The config below each intro is included directly from
the actual project, checked into this repository under
examples/ — what you
read here is exactly what a CI job in this repository runs against a real
Docker daemon on every change, so it can’t silently drift out of date. Clone
the whole directory to run one yourself, or copy the config and adjust the
commands to your own scripts.
Four of the five are ratect.toml; the same containers and tasks work
identically as batect.yml with ratect-compat (see Two binaries, two
formats) — the JVM example below is
batect.yml itself, for reasons its own section explains.
See the
configuration reference for what each field
does, and Getting Started if you haven’t run a task
before.
Every command below that chains two steps with && wraps them in sh -c '...'. command is tokenized into literal argv, with no shell
involved — an unwrapped && doesn’t fail
loudly, it’s just handed to the first program as a literal extra argument,
which several package managers silently ignore rather than reject. The
FAQ walks through it, including
the config-time $VAR syntax that looks the same and isn’t.
Try it
Cloning examples/rust
and running ratect tasks list there prints:
Tasks in example-rust:
Checks:
- lint: Run clippy with warnings denied
Development:
- build: Compile the project
- run: Run the application
- test: Run the test suite
Utilities:
- shell: Start a shell in the build environment
ratect run followed by any task name (build, test, run, lint, or shell)
then actually runs it — see Getting
Started for what that output looks like
against a real Docker daemon.
Rust
examples/rust.
The official rust image doesn’t ship the clippy component by default, so
lint adds it before running; the Cargo registry and the target build
output are each cached separately, so only the first run is cold.
ratect_version = "0.13.0"
project_name = "example-rust"
[containers.build-env]
image = "rust:1.90"
working_directory = "/code"
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "cargo-registry", container = "/usr/local/cargo/registry" },
{ type = "cache", name = "cargo-target", container = "/code/target" },
]
[tasks.build]
description = "Compile the project"
group = "Development"
run = { container = "build-env", command = "cargo build" }
[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "cargo test" }
[tasks.run]
description = "Run the application"
group = "Development"
run = { container = "build-env", command = "cargo run" }
[tasks.lint]
description = "Run clippy with warnings denied"
group = "Checks"
run = { container = "build-env", command = "sh -c 'rustup --quiet component add clippy && cargo clippy --all-targets -- -D warnings'" }
[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }
Go
examples/go.
lint uses go vet, part of the standard toolchain already in the build-env
image — no second tool or container needed for a minimal project like this
one.
ratect_version = "0.13.0"
project_name = "example-go"
[containers.build-env]
image = "golang:1.23"
working_directory = "/code"
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "go-mod", container = "/go/pkg/mod" },
{ type = "cache", name = "go-build", container = "/root/.cache/go-build" },
]
[tasks.build]
description = "Build the binary"
group = "Development"
run = { container = "build-env", command = "go build ./..." }
[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "go test ./..." }
[tasks.run]
description = "Run the application"
group = "Development"
run = { container = "build-env", command = "go run ." }
[tasks.lint]
description = "Run go vet"
group = "Checks"
run = { container = "build-env", command = "go vet ./..." }
[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }
Node.js
examples/node.
A TypeScript project with build/test/lint npm scripts (tsc, vitest,
eslint). Each of build, test and lint runs npm ci itself, and
run gets it through its build prerequisite, rather than relying on a
separate install step — a task’s own container is recreated from scratch every run,
so only what lands in the bind-mounted project directory or a cache mount
survives to the next one. The npm cache mount is what keeps a repeated npm ci fast.
ratect_version = "0.13.0"
project_name = "example-node"
[containers.build-env]
image = "node:22"
working_directory = "/code"
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "npm-cache", container = "/root/.npm" },
]
[tasks.build]
description = "Compile TypeScript"
group = "Development"
run = { container = "build-env", command = "sh -c 'npm ci && npm run build'" }
[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "sh -c 'npm ci && npm test'" }
[tasks.run]
description = "Run the built application"
group = "Development"
prerequisites = ["build"]
run = { container = "build-env", command = "node dist/index.js" }
[tasks.lint]
description = "Run eslint"
group = "Checks"
run = { container = "build-env", command = "sh -c 'npm ci && npm run lint'" }
[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }
Python
examples/python.
A plain script rather than a packaged library, kept deliberately simple;
build byte-compiles it as a minimal stand-in for a real build step (there
isn’t a natural one for a script with no compiled artifact). Same reasoning
as the Node example above for why test/lint each reinstall: the pip
cache mount is what makes that cheap.
ratect_version = "0.13.0"
project_name = "example-python"
[containers.build-env]
image = "python:3.12"
working_directory = "/code"
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "pip-cache", container = "/root/.cache/pip" },
]
[tasks.build]
description = "Byte-compile the project"
group = "Development"
run = { container = "build-env", command = "python -m compileall ." }
[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "sh -c 'pip install -r requirements-dev.txt && pytest'" }
[tasks.run]
description = "Run the application"
group = "Development"
run = { container = "build-env", command = "python hello.py" }
[tasks.lint]
description = "Run ruff"
group = "Checks"
run = { container = "build-env", command = "sh -c 'pip install -r requirements-dev.txt && ruff check .'" }
[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }
JVM (Gradle)
examples/jvm.
Written as batect.yml rather than ratect.toml, deliberately: Batect
itself is a Gradle/Kotlin project, and JVM/Gradle is where its own
conventions and sample projects skew, so an existing Batect-using JVM shop
is likely migrating a batect.yml that already looks close to this one —
ratect-compat reads it unchanged. The task set relies on the project’s own
checked-in Gradle wrapper (./gradlew), so the image itself needs nothing
but a JDK; lint runs Checkstyle, the traditional
choice, via its own Gradle task rather than a separate tool.
project_name: example-jvm
containers:
build-env:
image: eclipse-temurin:25-jdk
working_directory: /code
environment:
GRADLE_OPTS: -Dorg.gradle.daemon=false
volumes:
- local: .
container: /code
- type: cache
name: gradle-cache
container: /root/.gradle
tasks:
build:
description: Compile and assemble
group: Development
run:
container: build-env
command: ./gradlew assemble
test:
description: Run the test suite
group: Development
run:
container: build-env
command: ./gradlew test
run:
description: Run the application
group: Development
run:
container: build-env
command: ./gradlew run
lint:
description: Run Checkstyle
group: Checks
run:
container: build-env
command: ./gradlew checkstyleMain checkstyleTest
shell:
description: Start a shell in the build environment
group: Utilities
run:
container: build-env
command: bash
Only batect.yml ships in examples/jvm/ — the same containers and tasks
would re-spell directly into ratect.toml with no behavior change (run
ratect config convert to generate one), see
extends/list-entry shape
for the syntax differences you’d see in the result.
Next steps
Every example above declares a cache volume or two. Using Ratect With
Language Ecosystems says which directories each
toolchain needs cached and why, plus the couple of correctness gotchas per
ecosystem that aren’t a caching question at all.
Using Ratect With Language Ecosystems
Every toolchain below assumes its own persistence: a package manager expects
its downloaded dependencies to still be there next time, a compiler expects
its incremental build cache to survive between invocations. Ratect’s own
container model doesn’t give you that for free — every task starts a fresh
container, and anything written
outside a mounted volume disappears with it. Without a
cache volume pointed at the right
directory, a toolchain that assumes persistence just re-downloads or
recompiles everything, every single run, as if it were on a brand-new
machine each time.
This page has one section per ecosystem, naming exactly which directories
need to be a cache volume and why, plus the couple of correctness gotchas
that aren’t a caching question at all. Every config referenced here is the
real, CI-proven config under
examples/ — see
Worked Examples for the full files.
Rust
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "cargo-registry", container = "/usr/local/cargo/registry" },
{ type = "cache", name = "cargo-target", container = "/code/target" },
]
Two separate caches, for two separate things Cargo persists:
cargo-registry— the crate index and every downloaded/extracted dependency source. Without this,cargo buildre-fetches your entire dependency tree from crates.io on every run.cargo-target— compiled build artifacts (target/). Without this, every run is a cold, from-scratch compile — the difference between an incremental rebuild and a full one, which for a large dependency tree is minutes rather than seconds.
Go
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "go-mod", container = "/go/pkg/mod" },
{ type = "cache", name = "go-build", container = "/root/.cache/go-build" },
]
Same split as Rust, Go’s own equivalents:
go-mod(GOPATH’s module cache) — downloaded module sources. Without it,go build/go testre-fetches every dependency module fresh.go-build(GOCACHE) — the compiler’s own build cache (compiled packages, keyed by input hash). Without it, every build recompiles the entire dependency graph rather than reusing what hasn’t changed.
A linter with its own cache (golangci-lint’s ~/.cache/golangci-lint/, for
example) would need the same treatment if a project adopts one — examples/go
doesn’t, so there’s nothing to demonstrate it against here, but the pattern
is identical: mount whatever directory the tool itself says it caches into.
Node.js
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "npm-cache", container = "/root/.npm" },
]
npm-cache — npm’s own download cache, not node_modules itself.
node_modules stays a plain, uncached part of the working directory (rebuilt
by npm ci on each run, from what’s in the cache); what needs to persist is
npm’s cache of already-downloaded package tarballs, so a repeat npm ci
doesn’t re-download the same versions from the registry every time.
A long-lived Node process needs enable_init_process
too — this isn’t a caching question, but Batect’s own nodejs.md covers it
for the same reason it belongs here: Node doesn’t handle running as PID 1
correctly, so a container with no init process won’t forward SIGINT/Ctrl+C
to it correctly. examples/node’s own run task doesn’t need this — it
prints a message and exits, nothing to interrupt — but
examples/full-stack’s
app container is exactly the long-lived-server case, and sets
enable_init_process = true for it.
Python
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "pip-cache", container = "/root/.cache/pip" },
]
pip-cache — pip’s own download/wheel-build cache. Without it, every
pip install re-downloads and, for a package with no prebuilt wheel for the
image’s platform, rebuilds it from source from scratch, every run.
JVM (Gradle)
environment:
GRADLE_OPTS: -Dorg.gradle.daemon=false
volumes:
- local: .
container: /code
- type: cache
name: gradle-cache
container: /root/.gradle
gradle-cache (~/.gradle) — Gradle’s dependency cache and its own
build cache, in one directory. Without it, every run re-resolves and
re-downloads the full dependency graph.
Disable the Gradle daemon. This one’s a correctness/performance gotcha
rather than a caching question, and it points the opposite direction from
everything above: Gradle’s daemon exists to stay warm across invocations,
so it can skip reloading and recompiling the build script on the next run.
That benefit depends on the daemon surviving between runs — which never
happens in a Ratect container, disposable per task. Without
-Dorg.gradle.daemon=false, every task pays the daemon’s own startup cost
and then throws it away with the container, strictly worse than never
starting one. examples/jvm sets this on build-env via GRADLE_OPTS.
If a Gradle build under Docker Desktop looks hung or dies without a message, the ceiling is usually Docker’s own, not Ratect’s — see the FAQ.
Not covered
Batect’s own per-ecosystem pages also cover .NET Core and Ruby — both caching-only concerns there, no correctness gotcha like Gradle’s or Node’s. Ratect has no example project for either ecosystem, so there’s nothing real to ground a section in here without inventing untested config; a real worked example for either is its own, larger undertaking than this page.
Next steps
From here, Task Lifecycle is the step-by-step account of
what ratect run actually does — task ordering, per-task setup and cleanup —
and Dependency Readiness is when a dependency counts
as ready and how several dependencies’ waits combine; the FAQ
collects the questions that come up first. When a second project wants the
same containers and tasks, Includes covers pulling in a shared
file or a Git bundle, and Reusable Pipeline Building
Blocks why you’d want to.
Migrating a Batect Project to Ratect
This page is specifically for a project that already has a batect.yml —
see Getting Started instead if you’re bringing Ratect
into a project that doesn’t use Batect at all.
Most task runners assume a clean slate — convert everything, or don’t bother.
Ratect doesn’t: ratect-compat reads an existing batect.yml unchanged, and a
native ratect.toml project can include a batect.yml fragment as-is (see
Two binaries, two formats). That
makes migration a series of independent, optional steps rather than one
all-or-nothing conversion — stop at whichever one matches how much of the
tool you actually want.
Step 1: point ratect-compat at what you already have
The first step usually needs no config changes: run ratect-compat against the
batect.yml you already have, in place of the (now unmaintained) batect
binary itself. Same file, same flags, mostly the same behavior. Some checks
Batect makes only when a task runs are made here when the file loads, so a
latent mistake in a task you never ran can surface — see Load
errors, and Differences from
Batect for the other exceptions. This alone gets a
maintained tool, and is a complete, permanent choice on its own if that’s all
you want.
From here, two paths
Once ratect-compat is in place, there are two ways to move onto the native
ratect.toml format. They aren’t sequential steps — pick one:
ratect config convert only ever reads a Batect-format
root file, so it has to run before the project’s root becomes ratect.toml
(path A below), not after. Once the root is native, finishing off any
remaining .yml includes is a by-hand job (path B). What actually changes
between the two formats is tabulated in the ratect.toml reference — at a
glance and
where the semantics differ
— and between the two binaries in the ratect CLI
reference.
Path A: convert everything in one pass
ratect config convert reads a project’s actual root batect.yml — includes
and all — and converts each file the project owns beside itself: the root to
ratect.toml, every local included file to a .toml with the same name in its
own directory, with each include entry rewritten to match, so every relative
path keeps the directory it resolves against. A Git include stays a Git include.
ratect config convert -f batect.yml, captured in
examples/jvm —
the one example kept as a batect.yml:
Converted batect.yml to ratect.toml.
Review it, then remove batect.yml.
The output is a starting point, not a finished file: config convert doesn’t carry comments over, though it does
check each file round-trips losslessly before writing anything. The same
configuration runs differently in a few respects under ratect: a task’s own
container has no readiness gate (see Dependency
Readiness), an enabled
run_as_current_user becomes identity, the same goal with a mechanism that depends
on the daemon, so its --user may go (see Coming from
run_as_current_user), an
expression in that home_directory or a string-form volumes entry’s host path
is evaluated rather than used as written (see Where the semantics
differ), and a Git
include’s bundle may offer a ratect-bundle.toml or declare Git includes of its
own (see the config convert section). config convert
lists each task container whose health_check or setup_commands the first
affects, each container the second does, each home_directory or volume the third
does, and each Git include the fourth does, after converting and in each converted
file’s own header; a
health check from the image itself can’t be seen without the image. Review each
file against Configuration Reference
before deleting the originals — this is the fastest route to fully native, but
still one diff worth reading closely, not a step to run and forget.
Path B: migrate incrementally
Try the native binary without converting anything
The native format isn’t all-or-nothing either. An include entry is parsed by
its file extension (see Includes), so a
ratect.toml project can pull in an entire existing batect.yml unconverted.
The one adjustment needed: an included file must not declare project_name,
since that’s root-only (see Includes) — move
that one line out into the new root file instead.
# legacy.yml — the old batect.yml, minus its `project_name:` line
containers:
build-env:
image: alpine:3.18.2
volumes:
- .:/code
tasks:
test:
run:
container: build-env
command: echo "Hello from ratect!"
# ratect.toml
project_name = "my-project"
include = [
{ path = "legacy.yml" },
]
ratect tasks list -f ratect.toml and ratect run test -f ratect.toml now
work through the native binary and a native entry point, with zero lines of
the actual configuration translated — mostly the same behavior as before, with
two differences worth knowing:
- A task’s own container has no readiness gate. The native binary doesn’t
wait on the health check of a container a task runs as its own
run.container— whether fromhealth_checkor its image’s ownHEALTHCHECK— and doesn’t run itssetup_commands, wherever that container is declared: the binary running the project decides, not the file’s format (see Dependency Readiness). The same container used as a dependency is still gated. - Nested Git includes need a grant. A Git-included bundle that itself
declares a nested
type: gitinclude is refused under the native format unlessallow_nested_git_includesis set, whereratect-compatallows it unconditionally (see Where the semantics differ). It only bites iflegacy.ymlitself has a nested Git include of that shape.
Migrate one file at a time
From here, migration is as granular as you want it to be. Split legacy.yml
into smaller files along whatever lines make sense (one per container group,
one per pipeline stage — Batect’s own include already supports this), then
convert each piece in turn: since config convert treats the file it’s
pointed at as a root, and gives a root’s conversion a project_name (which an
included file can’t declare), converting one piece means pointing it at a
throwaway root — a batect.yml in a scratch directory, with an include
entry naming the piece — which
writes the piece’s own .toml beside it, and one beside each file the piece
itself includes, their include entries pointing at each other (plus a
ratect.toml beside the throwaway root, to delete with it). Swap that one
include entry from .yml to .toml, and move on whenever you’re ready —
there’s no deadline, and a project can stay a mix of both formats indefinitely.
What decides when a piece has to move is the feature you want. A container
still declared in a .yml is a Batect container wherever it is included, so
it can use no ratect-native field — see Which fields a file may
use. Reaching for ulimits,
extends or stop_signal on a container is therefore the signal to convert
that container to TOML; nothing else in the project has to move with it.
Next steps
Wherever you stopped, Differences from Batect
is what behaves differently from batect itself — the exceptions Step 1
pointed at, in full.
Differences from Batect
Ratect is a from-scratch Rust implementation inspired by Batect (which is itself no longer maintained — the upstream repository was archived in October 2023), not a wrapper or fork. It does not read Batect’s documentation or source at runtime. To move an existing project over, follow Migrating a Batect Project to Ratect; this page is what changes once you have.
Every Batect configuration field and CLI flag is supported, field-for-field and flag-for-flag, unless listed below — see config reference/ CLI reference for the full accepted schema and flags. This page lists the exceptions: a real behavioral divergence, an extension beyond what Batect does, or a restriction narrower than it. It doesn’t restate how a field or flag works — config reference/CLI reference/ task lifecycle are the authoritative source for that; this page only says what’s different and points there for the rest.
Unrecognized fields fail closed: Ratect’s YAML parsing rejects unknown keys — a typo’d field name, or (unlikely, since Batect’s own
includetypes beyondfile/gitare the only thing left genuinely unsupported here) a real gap — fails config loading with an error naming it, rather than silently ignoring it. There’s no partial/best-effort mode.
Configuration format
Top-level fields
Every other top-level field is supported field-for-field — see config reference for the full list. The exceptions:
| Field | Notes |
|---|---|
config_variables | description: is recognized but inert — Ratect has no help/usage output to show one in. |
include | Ratect enforces that a Git include’s path (and anything it transitively includes) stays within that repository’s own clone, and that a bundle’s containers’ host paths (volumes, build_directory, build_secrets, build_ssh) stay inside its clone or your project directory unless your include entry sets allow_host_paths; Batect has no equivalent containment check for either. In ratect.toml specifically, a Git-included bundle also can’t declare further Git includes of its own unless allow_nested_git_includes is set — ratect-compat stays unrestricted, matching Batect. See What a bundle may do. A Git include’s clone is cached under ~/.ratect/incl, keyed by a SHA-256 of the remote and ref with each length-prefixed, with a TOML sidecar — not Batect’s ~/.batect/incl, keyed by a hash of git <remote> @<ref>, which two different remote/ref pairs can share. Neither tool reuses or sweeps the other’s clones. The sweep that removes a clone unused for 30 days counts them as 30 × 24 hours, where Batect counts 30 calendar days in your time zone, so across a daylight-saving change the two can disagree by up to an hour about whether a clone is due. It skips, with a warning, a sidecar it can’t read or parse, and goes on to the rest; Batect’s stops at the first such file, so while it’s there no clone is ever removed. See Git includes. Cloning a Git include is guarded by a lock file, as in Batect, but a lock whose holder has exited (killed during a first clone, say) is taken over by the next load that needs the include, where Batect’s waits 5 minutes and fails until the file is deleted by hand; a lock left by an older Ratect is still waited on. A load waiting on another process’s clone says so on stderr, where Batect’s waits in silence. Where the lock’s proof of exit doesn’t reach every process sharing the cache, such as a host and a container sharing ~/.ratect/incl, two loads can clone the same include at once; the second to finish uses the first’s clone. See decisions/0023 and decisions/0027. The Cloning <repo> <ref>... line, and the blank line after it, are printed only by a load that clones; Batect’s also come from a load that waited out another process’s clone and then skips its own. git’s own output is captured: a failed clone’s is part of the error (except, in ratect.toml, for a Git include a bundle declares, where it goes to RUST_LOG=debug — see Nested Git includes), where Batect prints git clone’s as it runs, its error saying only that git exited with a code, and puts only a failed git checkout’s in its error; and a successful clone’s warnings are dropped, where Batect shows git clone’s. A prompt for credentials still reaches the terminal. Wherever Ratect names an include’s repo, any credentials in its URL are shown as *** (https://***@host/repo.git), as is anything else between :// and the URL’s last @ (https://host/a@b is shown as https://***@b); Batect prints the URL whole. An include written as an object with no type loads as a file include; Batect requires type, and fails to load the file without it. The git checkout after the clone uses none of your Git configuration, nor the clone your init.templateDir, so core.autocrlf doesn’t change a clone’s line endings, no hook runs during the checkout, and a file stored in Git LFS stays a pointer file; Batect’s checkout uses your configuration. Batect’s also searches upward from the clone’s directory for a repository, so when the clone’s .git is missing it checks the ref out in whichever repository holds the cache, and both its commands use the variables naming a repository that git rev-parse --local-env-vars lists, which Ratect’s ignore, such as an exported GIT_WORK_TREE, which makes its clone fail, or the absolute GIT_INDEX_FILE a hook of git commit -a gets, under which it checks out no files. |
forbid_telemetry | Recognized, no effect — Ratect doesn’t collect telemetry, so there’s nothing to forbid. |
Expressions
The syntax and which fields support it match Batect, field-for-field — see Expressions. The exceptions:
- When a task’s values are evaluated. Both evaluate only what a task uses, once the run reaches it, after its prerequisites. Ratect evaluates every container in the task’s graph before starting any of them, where Batect evaluates each as it creates or builds it — so here a value that can’t be evaluated fails the task before its dependencies start, rather than after.
image— see Container fields below.batect.project_directoryhas its.and..components resolved:-f ../proj/batect.ymlgives/parent/proj, where Batect gives/parent/cwd/../proj. Both name the same directory, and a volume path built from either is normalised the same way, so the difference only shows where the value is used as a string — inenvironmentorbuild_args.
Container fields
Every other container field is supported field-for-field — see config reference for the full list. The exceptions:
| Field | Notes |
|---|---|
image | An expression-looking value ($VAR) is rejected when the file loads rather than resolved or used as a literal — Batect resolves nothing here either, but silently treats it as a literal image name that then fails at pull time instead. ratect.toml does resolve them; see config reference. |
volumes | A cache mount’s name must use Docker’s own volume-name character set; Batect doesn’t validate it at all, so an unvalidated name could bind-mount an arbitrary host directory under --cache-type=directory. Breaking change for --cache-type=directory only — --cache-type=volume already enforced this via Docker itself. See Cache volumes. A newly generated .batect/caches/key holds a UUID rather than Batect’s six-character id, under a comment that doesn’t name Batect; each tool reads the other’s key file, so the volume names stay the same. A line of that file that starts with # after leading spaces is a comment, where Batect counts it as a key line: Batect refuses a file holding one beside the key, and takes one on its own as the key, where Ratect refuses the file as having no key line. A key path that is a symbolic link to nothing is refused, where Batect creates the key file wherever the link points. |
ports | A port written with a leading + (+80, '+80-+90', '+80:+80'), or unquoted as a YAML hexadecimal or octal integer (0x50, 0o120), is accepted as the port it denotes; Batect rejects each as a malformed port range. The same holds for a task’s run.ports. |
dependencies | A name that isn’t a declared container is rejected when the file loads — and so is one in a task’s dependencies or run.container. Batect reports the same error in the same words, but only once a task that reaches the reference runs, so a stale reference in a container or task nothing runs never stops Batect and stops every ratect-compat command. A name given twice — here, in a task’s dependencies, or in a task’s prerequisites — is accepted, and that container starts, or that task runs, once; Batect rejects the duplicate when the file loads (The dependency 'X' is given more than once, and likewise for a prerequisite). ratect doctor and ratect config validate warn about it. See config reference. |
capabilities_to_add / capabilities_to_drop | Also accepts BPF/CHECKPOINT_RESTORE/PERFMON — Docker capabilities added after Batect’s last release, so its own Capability enum predates them. A superset: every config Batect itself accepts here still parses identically. |
health_check / setup_commands | A task’s own container’s readiness gate doesn’t fail the task once its main command has exited 0, whatever the failure — typically the container stopped before reporting a health status, before a setup command could exec into it, or while one was running and was killed with it; Batect’s does. A failure of that gate while the main command is still running fails the task as Batect’s does, but cancels the main command up to two seconds later, and is forgiven if the main command exits 0 within that time. That, and the race it leaves open, are in task lifecycle. Under ratect a task’s own container has no readiness gate at all — see Dependency Readiness. |
dockerfile | A Dockerfile that is a symbolic link, or is reached through a linked directory, is refused before the build, since Ratect’s build context doesn’t carry symbolic links and the daemon would report the Dockerfile missing. Batect builds one whose link stays inside the build directory. |
log_driver / log_options | An absent value leaves the daemon’s own default alone; Batect’s config model bakes in a literal "json-file" default explicitly. Immaterial in practice — that’s Docker’s own out-of-the-box default too. |
shm_size | A size whose count times its unit doesn’t fit in a 64-bit number of bytes is an Invalid size error when the file loads, like any other malformed size. Batect’s multiplication overflows silently, and it sends Docker the meaningless size that results. Whitespace around a size string is ignored (' 128m '), as is whitespace that isn’t ASCII, and an unquoted YAML integer is read as the number it denotes, whatever its spelling (+5, 0x10, 0o17); Batect refuses each. Both accept whitespace between the count and its unit ('128 m') or after a bare count ('2 '). |
run_as_current_user | A .toml file refuses it, in favour of identity: the same goal, with a mechanism that depends on the daemon — see Coming from run_as_current_user. A .yml keeps it, and the rest of this row is about that. Host-side uid/gid lookup only works on Unix — see User mapping. A home_directory containing a : or a control character, or with no directory name to create (/, or a path ending in ..), is rejected when the file loads. Batect checks neither: it writes the first into the generated /etc/passwd as it is, where a : shifts the entry’s fields and a newline adds an entry of its own, and passes the second to Docker. A read-only cache mount (options: ro) isn’t given to the mapped user, since nothing can write to it anyway; Batect tries to change its owner like any other cache’s, which the read-only mount refuses, failing the run before the container starts. The generated /etc/passwd, /etc/shadow and /etc/group end their last line; Batect’s don’t, and musl libc (alpine’s) reads an unterminated last line one character short, so on a musl image the user’s shell reads as /bin/s and the group’s member a letter short. |
Task fields
Every task field is supported field-for-field — see config
reference for the full list. The
exceptions are about when a mistake is caught: dependencies naming an
undeclared container, and a name given twice in dependencies or
prerequisites, are under dependencies in Container
fields above, and a customise naming a container the task
doesn’t start is under Load errors.
run fields
Every run field is supported field-for-field — see
TaskRun for the full list. The
exceptions are about when a mistake is caught: container naming an undeclared
container is under dependencies in Container fields
above, and a container also listed in the task’s dependencies is under Load
errors.
Null values
A field given a YAML null (volumes: with nothing after it, ~ or null)
mostly loads as if it were left out — a container’s volumes, ports,
environment, health_check or run_as_current_user, a task’s
prerequisites, dependencies or customise, and the top-level
forbid_telemetry or config_variables, for example. Batect rejects a null on
each of those. Where Batect accepts one — run’s command, entrypoint and
working_directory, a config variable’s default and description,
health_check’s retries — the two tools agree. Some nulls are rejected here
too, such as an environment variable’s value and shm_size, in Ratect’s own
words.
Load errors
Ratect checks a config when the file loads, and the report is its own:
- Some checks Batect makes only once a task reaches them are made when the
file loads here, for any command that loads it —
--list-tasksincluded — and the first hard error stops it, so a config Batect lists, or runs a different task from, can fail to load here. Besides the undeclared names underdependenciesin Container fields, they include arun_as_current_userhome_directorythat isn’t an absolute path, and a relativecachemount destination underrun_as_current_user— Batect checks both as it configures the container, though its message for the cache path is never seen, since Docker has already refused the relative mount when the container was created; and a task’scustomisenaming a container its task doesn’t start, or itsrun.containeralso listed in itsdependencies, checked for every task rather than only the ones run.--tag-imageon a container that uses a pulled image isn’t checked at load, but fails as soon as that container’s image is resolved — after its dependencies have started and its prerequisite tasks have run, but before it runs — where Batect fails once the task using it has finished. - A negative
health_checkduration, such as-2s, is rejected when the file loads. Batect loads one, and the run fails only once Docker refuses it. A negative zero, such as-0s, is zero, and loads in both. - The wording is Ratect’s, not Batect’s —
Configuration file "batect.yml" not found.rather thanThe file '<absolute path>' does not exist., and likewise for malformed volumes, ports, devices and includes, expressions, durations, duplicatebuild_sshids, an undeclared config variable given a value — which names the variable but neither which of--config-varand--config-vars-filegave it nor, for the file, its line — a name defined in more than one file, a file that contains no configuration, and an included file that setsforbid_telemetrytotrue. A file inside a Git include, or a container’s path inside one, is named by its path within the repository plus the remote and ref,'1.yml' from the bundle '<repo>' at '<ref>', where Batect writes<repo>@<ref>: 1.ymlor1.yml from <repo>@<ref>. - A check made once the file has parsed names what it’s about — the container or task — rather than giving Batect’s YAML path, line and column.
- An error raised while the file is parsed gives its line, column and YAML
path in Ratect’s own layout —
deserialization error at line 8, column 23: containers.build-env.not_a_real_field: unknown field: not_a_real_field, under theFailed to parse config file "<path>"line of the cause chain below — where Batect prints<file> (at <path> on line L, column C): <message>. The wording is Ratect’s too:unknown field: Xwith no list of the known ones,missing field: X, and for a value of the wrong type the path and the mismatch, with noValue for 'X' is invalid:prefix — a refused null isinvalid type: null, expected <what the field takes>, as incontainers.app.shm_size: invalid type: null, expected a size like '128', ..., where Batect saysUnexpected null or empty value for non-null field.A null where a mapping of fields is expected is read as an empty one, so it reports any field that mapping must have as missing. An unknown field’s column is its value’s, not its key’s, and so is that of a task, config variable or container name Batect refuses — though the message for one is Batect’s, verbatim. A key given twice in one mapping istasks.t: duplicate key "t" at line 9, column 3, giving only the second occurrence’s line, where Batect’sDuplicate key 't'. It was previously given at line L, column C.also gives the first’s. - The full cause chain is printed:
Error: <message>, then aCaused by:list when there is a cause, where Batect prints one message. A parse error’s own reason is in that list, underFailed to parse config file "<path>". The same holds for every fatal error, not only a config one. - With several problems, the one reported isn’t necessarily Batect’s first.
Of several containers, tasks or
customiseentries failing the same check, the first the files declare is reported, as in Batect, but each check runs over every container before the next check starts, and over containers before tasks, so of two failing different checks the one reported can differ. Every config check runs before an--override-imagecontainer name is looked up, a duplicatebuild_sshid is checked after a container’s image source, a volume’s fields are checked in a different order, and of several undeclared config variables given values, the first by name is reported, where Batect reports the file’s first, in file order, before any--config-var. Acommand,entrypointor setup command that can’t be tokenized is reported after every error raised while the files are parsed, after every container’s image source,imageexpressions,dnsentries and fields its file’s format doesn’t allow are checked, and after the same container’svolumes,build_directoryandbuild_secrets, where Batect reports whichever the file gives first.
CLI flags
Every other flag from Batect’s own CLI reference is supported flag-for-flag — see CLI reference for the full list. The exceptions:
| Flag | Notes |
|---|---|
--version | Prints one line, ratect-compat <version>, rather than Batect’s seven labelled lines (its version, build date and commit, and the JVM, OS, Docker and Git versions) and the help blurb after them. Also gets a -V short form Batect doesn’t have (a clap default). Acts as soon as it’s reached: whatever follows it on the command line is never parsed or checked, and no check across options is made, so --version --bogus and --tag-image app=t --override-image app=i --version exit 0, where Batect checks every option first and rejects them. Given with --help, whichever of the two comes first wins; Batect always shows the help. |
--help / -h | The layout and text are clap’s rather than Batect’s, including <CONFIG_FILE>-style value placeholders and [default: …] for a fixed default. A description never shows an environment variable’s current value or whether batect.local.yml exists — Batect’s say, for example, whether DOCKER_HOST is currently set, and to what. Like --version, acts as soon as it’s reached, without checking what follows it, so --version --help prints the version, where Batect shows the help. Exits 0, as help conventionally does; Batect’s HelpCommand returns 1. See Options and decisions/0016. |
--list-tasks / -T | The listing opens with Tasks in <project>:, followed, when any task has a group, by a blank line before the first group heading. Batect’s opens a flat list with Available tasks:, and a grouped one with its first group heading. The -o quiet listing, the one meant for scripts, has no header in either. |
--config-var | --config-var NAME= sets the variable to an empty value, which Batect rejects as having no value. A value containing = is split at its first =, so --config-var a=b=c sets a to b=c; Batect splits at the last, setting a=b to c. --override-image and --tag-image also split at the first =. |
--tag-image | A TAG Docker would refuse is rejected while the arguments are parsed, as a usage error, on every command, --list-tasks included. Batect rejects it only when that image’s build step starts, after the task’s prerequisites have run. The check is the one docker tag makes, with its reasons, so a digest (app@sha256:…) is refused too; Batect accepts one, and the daemon then refuses the build. Batect’s parser is an older copy of the same grammar: it rejects a name whose first component has uppercase in it (MyOrg/app), which the current one takes as a registry host, and an IPv6 registry host, and it counts the 255-character limit over the whole name rather than the repository path; its uppercase message also doesn’t name the repository. See decisions/0018. |
TASK_NAME (positional) | A misspelled task name’s Did you mean suggestions include every task tied on edit distance; Batect keeps only one name per distance. An unknown task’s error reads Task 'X' not found., where Batect’s reads The task 'X' does not exist., and its closing hint names ratect-compat --list-tasks and ratect-compat --help rather than ./batect’s. No task name at all is a command-line error, as in Batect, reported like any other (see below): exit 125, where Batect exits 255. See Exit codes and error reporting. |
-- ADDITIONAL_ARGS | When neither the task’s run nor its container sets a command, the arguments replace the image’s default CMD, as docker run <image> <args> does; Batect refuses them with an error. Every invocation Batect accepts runs the same here. See Using ADDITIONAL_ARGS in a task command. |
--output / -o | An explicit -o fancy fails up front with a clear error when stdout isn’t a terminal, and so does one on a terminal with TERM=dumb; TERM unset is accepted, as in Batect. Batect accepts both refused cases: when stdout isn’t a terminal it crashes with an unhandled exception on the first repaint, and on a terminal with TERM=dumb it writes cursor movements that terminal can’t perform, garbling the display. all’s status lines also drop Batect’s inner Batect | prefix — the outer prefix already says whose line it is. all’s | separator is unstyled, where Batect bolds and colours it with the name before it: emphasis is for names, never punctuation (decisions/0017). fancy clips a line to the terminal’s width in display columns, so a wide character counts as two; Batect counts UTF-16 units, so a line holding wide characters is clipped earlier here. Choosing a style automatically doesn’t special-case TRAVIS=true, as Batect does by picking simple; that only matters on Travis CI with a real terminal, since a CI runner without one gets simple anyway. See Output Styles. |
--no-color | A superset, not a gap: Batect rejects -o fancy --no-color at parse time (its console couples color and cursor movement under one flag); Ratect’s keeps them independent, so that combination renders colorless fancy instead. Ratect also honours two environment variables Batect ignores: NO_COLOR has --no-color’s full effect, including making simple the auto-selected style, and CLICOLOR_FORCE colours output to a non-terminal. See Colour. |
--no-cleanup, --no-cleanup-after-failure, --no-cleanup-after-success | Batect’s own DontCleanup still stops a started container, just skips removing it; Ratect leaves it genuinely running (not just present-but-stopped) for investigation. With cleanup after success disabled, a task whose own container runs to completion exits with that container’s exit code; Batect exits 255 whatever the code was, 0 included, so a script checking the exit status can’t tell a pass from a fail. |
--docker-cert-path, --docker-tls, --docker-tls-verify, --docker-tls-ca-cert, --docker-tls-cert, --docker-tls-key | Batect’s bare --docker-tls (without -verify) disables all server certificate verification, not just hostname matching. Ratect doesn’t support that mode at all — --docker-tls and --docker-tls-verify behave identically here, the daemon’s certificate always fully verified. See TLS with a private certificate authority for the supported alternative (your own CA). A superset in one respect: Batect requires all of ca.pem, cert.pem and key.pem, and Ratect none of them — without a CA the system trust store is used, and without a cert.pem/key.pem pair no client certificate is presented. A CA that is given is the only one trusted. See TLS through the options. |
--docker-tls-ca-cert, --docker-tls-cert, --docker-tls-key | A file that exists but isn’t a regular file is accepted — a pipe, such as <(…), to keep a key off disk, is read like a file, once. Batect refuses one as refers to something other than a file. A missing file or a directory is refused before any command runs, as in Batect. See TLS through the options. |
--docker-context | A context’s SkipTLSVerify is not honoured: the daemon’s certificate is always fully verified, as with --docker-tls. Batect honours it, skipping verification. See Which daemon is used. |
--docker-host | An https:// host connects over TLS, as if --docker-tls-verify were given — from the flag, DOCKER_HOST, or a Docker context. Batect (and the Docker CLI) connect to such a host without TLS unless the TLS options or the context’s stored files ask for it. See Options. |
--docker-host | A host whose scheme isn’t unix://, tcp://, http:// or https:// — from the flag, DOCKER_HOST, or a Docker context — is refused on connecting, in Ratect’s own words: from the flag or DOCKER_HOST, Failed to connect to Docker host '<host>', caused by URI scheme is not supported: <host>. That includes ssh://, which Batect’s Docker client accepts. Where Batect refuses a host, as it does npipe:// off Windows, its message is protocol not available. |
--docker-context, --docker-config | A Docker CLI config.json that can’t be read or isn’t valid JSON, when the active context would be read from it, is a warning naming the file, and the default context is used, as the current Docker CLI does. Batect fails, as the Docker CLI it was built against did. See Which daemon is used. |
--docker-host, --docker-context | An empty DOCKER_HOST or DOCKER_CONTEXT counts as unset, as in the Docker CLI. Batect takes an empty value as set: an empty DOCKER_HOST still rules out every context and becomes the host, and an empty DOCKER_CONTEXT names a context called "". See Which daemon is used. |
--docker-tls-verify, --enable-buildkit | An empty DOCKER_TLS_VERIFY or DOCKER_BUILDKIT counts as unset, as in the Docker CLI: no TLS, and the daemon’s own builder. Batect rejects an empty value as not a boolean. Both are also read in any case, so True and Yes are accepted; Batect takes only the all-lower and all-upper spellings. An invalid DOCKER_TLS_VERIFY is rejected only when connecting to a host without --docker-tls/--docker-tls-verify, so --list-tasks and a connection through a context never read it; Batect rejects it on every command. See Environment variables. |
--docker-config, --docker-cert-path | A directory given by the flag, DOCKER_CONFIG or DOCKER_CERT_PATH that doesn’t exist or isn’t a directory is refused before any command runs, as in Batect, but in Ratect’s own words, naming the flag or variable, the path and what is wrong with it. ratect doctor reports one as a problem and carries on with its other checks. See Options. |
--enable-buildkit | An invalid DOCKER_BUILDKIT (the flag’s default) is rejected the first time a run builds an image — every run of a task with a build_directory container, since Ratect always builds and leaves Docker’s layer cache to skip unchanged work — rather than on every command. A task that only pulls images, --list-tasks and --clean never read it. Batect, like the Docker CLI, rejects an invalid value on every command. A daemon whose Builder-Version ping header is none of empty, 1 and 2 is reported at the same point, and not at all when DOCKER_BUILDKIT or the flag chooses the builder; Batect fails every run that connects to it, with an unhandled exception. |
--cache-type | Unlike Batect, not forced to directory for Windows containers — Ratect has no Windows support to special-case. A BATECT_CACHE_TYPE that is no cache type is refused, as in Batect, in Ratect’s own words, naming the variable, its value and the two cache types. |
--clean, --clean-cache | Under --cache-type=directory, the Docker daemon is never contacted, so cleaning works while it’s unreachable; Batect checks it can reach the daemon first, under either cache type, and fails without it. A project with no .batect/caches directory has nothing to remove, and Ratect warns that the directory isn’t there, where Batect fails with exit code 255. An entry there that is a symbolic link is skipped rather than followed, with a warning naming it: Batect follows it and deletes the contents of whatever it points to, even outside the project. |
--max-parallelism | Batect’s flag caps every setup/cleanup step, via a step-scheduling model Ratect doesn’t have, but one: a container’s run — its start, then the wait for it to exit — never counts, for any container, dependencies included, since it lasts the container’s whole lifetime; every container’s create counts. Ratect’s caps image pulls/builds, every container’s create (the task’s own included), a dependency’s start, and setup commands. So a dependency’s start is capped where Batect’s isn’t: under a low cap, dependencies start one at a time where Batect starts them together — timing only, the run’s outcome is the same. The task’s own container’s start and run are never gated, as in Batect. Health-check waits and cleanup teardown, which Batect’s cap covers, are deliberately excluded (teardown is concurrent, gated only by dependency order). |
--log-file | Batect’s own default (no --log-file) is a silent NullLogSink, nothing anywhere; Ratect always logs to stderr regardless, so --log-file here tees into a file in addition to stderr, not instead of it. The file is plain text, each record starting on a new line — one carrying a multi-line error, such as why the run failed, continues over the lines after it — where Batect writes one JSON object per message, and logs Ratect’s own records at debug and other crates’ at info unless RUST_LOG says otherwise, where Batect logs every message. The records are Ratect’s own rather than Batect’s, ending, at that default, with why the run failed when it did: the Git include cache sweep, for example, logs only what goes wrong, in its own words, and none of Batect’s No repositories ready for clean up., Deleting repository as it has not been used in over 30 days. or Repository deletion completed. records. |
--generate-completion-script, --generate-completion-task-info | Not accepted — an unrecognized-argument error. Batect’s are hidden flags for its own shell completion, which reaches them only through Batect’s wrapper script. ratect-compat has no shell completion; the native binary prints its own script with ratect completions <shell>. |
--no-update-notification, --upgrade, --no-wrapper-cache-cleanup | Recognized, no effect — permanently inapplicable, since Ratect is a single native binary with no self-updating wrapper script to disable notifications for, clean caches for, or upgrade. Recognized rather than rejected so an existing Batect invocation carrying one doesn’t hard-fail outright. Hidden from --help, where Batect lists all three — --upgrade under its help options, the other two under its execution options. See CLI reference. |
Beyond any one flag:
- A mistake on the command line is reported in
clap’s format: anerror: …line in its own words, sometimes followed by a tip or a usage line, thenFor more information, try '--help'.Batect prints a single message of its own instead, such asInvalid option '--bogus'. Run './batect --help' for a list of valid options.The exit code is125on a line meant to run a task,docker run’s code for its own failure, and2on one that replaces the task with--list-tasks,--clean,--clean-cacheor--upgrade, the usage-error conventionclapand the POSIX utilities share. So is an option value that fails its own check, such as a-for--config-vars-filenaming no file, abatect.local.ymlthat isn’t a file, or aBATECT_CACHE_TYPEthat is no cache type. Batect’s is-1(255) for both, the same as for any other failure (decisions/0016). --helpand--versionexit0even when an option’s value or default is invalid — a--docker-confignaming no directory, abatect.local.ymlthat isn’t a file, or a badBATECT_CACHE_TYPE, say: they act before any value they don’t need is checked. Batect checks its options and their defaults first, so an invalid one makes--helpexit-1(255) instead (decisions/0016).- Short options combine, and take an attached value:
-Tf batect.yml,-fbatect.ymland-oquietare accepted. Batect looks an option up by its exact text up to any=, and rejects each of those as an invalid option. - An option’s value can’t start with
-when it’s given as the next argument:--use-network -xand--clean-cache --list-tasksare usage errors, whose tip is the=form (--use-network=-x), which is accepted. Batect takes the next argument as the value whatever it starts with, so a forgotten value silently swallows the flag after it, while no Docker network, volume or context name and no Batect task name can start with-, and a path that does can be written./-x.
Runtime behavior gaps
Batect behavior not implemented in task execution, beyond what’s covered by the field tables above:
-
The home directory is
$HOMEfirst, when it is set and absolute, then the passwd entry’s, as in the Docker CLI. Batect uses the JVM’suser.home, which is the passwd entry’s whenever there is one, so where it and$HOMEdiffer Batect reads a different~/.dockerfrom the onedocker loginwrote, and the credentials and contexts there go missing. It also expands~in a path to that directory, where a shell would use$HOME. With no passwd entry,user.homedepends on the JDK:$HOMEon Java 21,?on Java 11. Not copied, as a Batect bug, under 0013’s rule 3. -
Cleanup on a termination signal (Ctrl+C,
SIGTERM,SIGHUP): four deliberate differences from Batect, which trapsSIGINTonly:- Ratect also traps
SIGTERMandSIGHUP, down the same cleanup path — a task runner is stopped by more than a keystroke (an editor closing its subprocess,docker stop,systemd, most CI cancel buttons), and under Batect each leaks a container and network. - The exit code names the signal: 128 + the signal’s own number (
130/143/129for Ctrl+C/SIGTERM/SIGHUP). Batect returns-1/255 for an interrupted run, as for any failure other than the task’s own command exiting non-zero. - A further signal during cleanup hurries it, then Ctrl+C stops it: a second
signal of any kind switches whatever is left to forced removal (kill and remove, no
grace period), and a
SIGINTafter that abandons cleanup. Batect instead lets cleanup finish and then prints manual cleanup commands. OnlySIGINTabandons because a keyboard is the one thing that sends it twice — a supervisor’s timed follow-up is aSIGTERM, which only ever means “exit” — so a supervisor that escalatesSIGINT→SIGTERM→SIGKILLon a timer usually gets a finished cleanup before theSIGKILL, though a slow daemon can still lose that race. A run that had already finished when the signal arrived keeps its own exit code, since the signal ended nothing — unless the cleanup is then abandoned with something still to remove, which turns a0into125(decisions/0016). Batect fails such a run with-1(255) whatever its code was. Whatever an abandoned cleanup leaves still carries Ratect’s ownership labels, soratect resources list/cleanfinds it (ratect-only;ratect-compathas no equivalent verb, so from it the sweep isdockeritself, filtering the same labels). - The notice names the signal and the next step: a line on stderr such as
Interrupted; cleaning up. Press Ctrl+C again to force-remove what's left, and Ctrl+C after that to stop cleaning up., printed in every style whateverRUST_LOGsays. Once cleanup ends,Cleanup complete.follows, and noError: Interrupted— the exit code says the run was signalled, and a cleanup that left something behind is reported, in place ofCleanup complete., as the error it is, naming what was left and thedockercommand that removes it. Batect printsTask cancelled: Interrupt received during execution.and that it is waiting for outstanding operations, then its manual-cleanup commands.
SIGKILLremains untrappable by either tool, same underlying OS limitation — the same labels are what a post-hocratect resources cleanneeds to find what it left. - Ratect also traps
-
A closed stdout cleans up: a run whose stdout reader goes away (
| head -n 1) stops its containers, removes them and the task network, and exits141, with a notice on stderr saying why. Batect’s container output is written by its Go wrapper straight to its stdout, and Go’s runtime ends a process whose write to stdout meets a closed pipe bySIGPIPE— from reading its source rather than running it, the same141, with nothing cleaned up. Ratect matches the code and declines the leak (decisions/0013 rule 3). -
A run that fails without its task’s command exiting exits
125: a config that doesn’t load, an unknown task, an unreachable daemon, a failed image pull or build, a dependency that never becomes ready, a setup command that fails.125isdocker run’s own code for its own failure. Batect returns-1(255) for all of these, as for every failure other than the task’s own command exiting non-zero. Every other command —--list-tasks,--clean,--clean-cache— exits1on failure, or2for a usage error or an invalid option value; Batect’s is-1there too. See Exit codes and error reporting and decisions/0016. -
A cleanup that fails after a passing run exits
125; after a failing one, the task’s own code stands: the daemon refusing to remove a container or the task network fails a run whose containers all exited0, and leaves a run that already failed with its own code. Batect fails both with-1(255), so the task’s own code is lost whenever its cleanup fails. See decisions/0016. -
Ownership labels: every container and network Ratect creates carries
eu.orican.ratect.*labels; Batect labels nothing of its own. An additive divergence — changes no behavior. See decisions/0002. -
Task run locks: every task run holds a lock file,
~/.ratect/runs/<run>.lock, for as long as its process drives it, so thatratect resourcescan tell a leftover from a task run still going; Batect writes nothing per run. A task run that cleans up fully deletes its file. A run with no home directory, or one it can’t write, takes none and runs as before. Seeresourcesoptions and decisions/0025. -
Interactive mode: two known divergences. Batect’s real-TTY gate checks only whether its output is a real terminal; Ratect’s requires both stdin and stdout to be real terminals. Live terminal-resize tracking is also Unix-only — synced once at session start elsewhere, not tracked further. See Interactive Mode.
-
Proxy support: three deliberate differences — see Proxies for the full mechanics.
- A
localhostproxy is rewritten on Linux too. Batect rewrites on macOS/Windows only; on Linux it propagates the URL verbatim, wherelocalhostmeans the container itself. This is Batect’s oldest open issue, eight years old. - A proxy bound to loopback only is diagnosed, not left to fail — Batect’s own roadmap notes the same warning is needed and never shipped one.
--no-proxy-varskeeps the proxies in Docker’sconfig.jsonout of a build too. Batect’s flag only stops its own proxy build arguments; its Docker client adds theconfig.jsonones to every build regardless.
Batect’s Docker-version-gated hostname fallback chain, which reaches back to Docker 17.06, isn’t ported: its first choice,
host.docker.internal, is the one for Docker 18.03 and later, so every Docker release Ratect connects to would get it (see the Docker 20.10 entry under Runtime behavior gaps). - A
-
Private registry credentials: on a pull or a classic build, Batect’s own Go client swallows a credential-helper error (under BuildKit, BuildKit’s own auth provider passes it back to the daemon instead); Ratect warns, naming the registry that failed to resolve, or, for a build, the
credsStorewhose helper couldn’t list what it holds. See Private registry credentials. -
A dependency exiting unexpectedly is reported, not silent. Batect has no equivalent: a dependency that dies after becoming ready — while the task’s own command, or a later dependency’s own health/setup wait, is still going — is otherwise invisible until whatever depended on it fails for a confusing, unrelated-looking reason (a connection refused, a timeout). Ratect prints a progress line naming the container and its exit code instead, in every output style except
quiet. See Dependency Readiness. -
A control character from your configuration is printed escaped. In a name or value from your configuration (a task, container, image or cache name, a path, a command, a Git include’s
repoorref), in image build output, and in a value an error message quotes, ESC prints as\u{1b}and a carriage return as\r, so neither a config file nor a Git bundle can send your terminal escape sequences. Batect prints them as they are. A container’s own output is printed as written. Which line breaks and tabs are escaped as well is in Output Styles. -
allmode splits on a lone carriage return too, not just\n. Batect’sInterleavedContainerOutputSinksplits on\nonly, so a container using\rto redraw progress in place (pip/curl/apt-style) produces no output at all until its next\n, then dumps everything since as one giant concatenated line — or produces none at all, if the stream ends first. A deliberate divergence: Ratect also ends a line at a lone\r(one not immediately followed by\n— a CRLF pair still folds to a single line break), so a real progress bar prints one interleaved line per redraw tick instead of staying silent — spammier, but never silent-then-dumped. The split never adds an empty line: a\rwith nothing before it since the last line ended — a line’s first byte, or one of a run of them — ends no line, and an empty line is printed only if no\rhas ended a line since the previous\n. So10%\r\r20%prints10%and20%, and Ratect prints as many empty lines as Batect. A setup command’s output and an image build’sImage build |lines follow the same rule; a failed classic build’sBuild output:keeps each\ras Docker sent it. -
allmode prints a container’s last line even without a trailing newline. Batect prints a line only once its\narrives, so a container whose output ends without one loses that last line. Image build output follows the same rule. -
BuildKit build output leaves out plain-progress’s clock. Like Batect, Ratect shows a BuildKit build in BuildKit’s plain-progress form: a
#N <step>header as each step starts, steps that start together in docker-client’s order,#N CACHEDand#N ERROR: …, and every line of a step’s output labelled with its#N. It leaves out elapsed times (#4 0.412 …),DONE <duration>lines and status lines (transferring context: …), so a build prints the same lines from run to run. A failed BuildKit build’sBuild output:is the same labelled lines, so in it, unlike a classic build’s, a lone\rends a line. -
Failure messages are Ratect’s own. A task fails at the same step as under Batect — an image that won’t pull or build, a task network that can’t be created, a container that can’t be created, set up for
run_as_current_user, or started, a dependency that doesn’t become healthy, a failing setup command, a dependency cycle — but Batect’s headline and wording aren’t reproduced:Failed to pull image Xand itsCaused by:list, for example, rather thanCould not pull image X.and the daemon’s message — which, where the daemon refused a request, followsDocker responded with status code N:rather thanError response from daemon:— a failed build’s output underBuild output:rather thanOutput from Docker was:, andFailed to start container 'X'rather thanCould not run container X.. Arun_as_current_useror network failure is reported as itself, not, as Batect frames it, as a failure to create the container; either way the container is named as configured. See Load errors for the cause chain. The message is an unprefixedError: …line on stderr in every output style,allincluded, where Batect’sallprints<task> !or<container> !lines on stdout; andallreports a failed setup command or network check, two failures Batect’salldoesn’t print at all. A setup command’s output is trimmed, so output that is only whitespace counts as none. -
A failed task ends with a summary line, not Batect’s footer. Where Batect ends a task that failed to run with a red
The task X failed. See above for details.(on stderr, or on stdout as a<task> !line underall), Ratect ends it with<task> failed after <duration>., the counterpart offinished with exit code N, in the same place: the progress console, on the task’s prefix underall, and not at all underquiet. Nor does Ratect print Batect’s blank line before the error: the bold redError:marker separates it, and underquieta leading newline would be the first byte on stderr. -
No white text. Batect paints its
simplestatus lines,all’s task-level prefix,all’s innerSetup command N |andImage build |labels, and every linefancydraws (the startup block, the cleanup line,Running <task>...and the summary), in the terminal palette’s white (SGR 37) — light grey on a dark theme, near-invisible on a light one. Ratect’s own lines are the terminal’s default foreground, with bold for emphasis, and it never sets the palette’s white or black (decisions/0017). The interrupt notice, the--no-cleanup*reminder and a cleanup that left something behind are printed on stderr in every style rather than logged; Batect prints its equivalents on stderr too, except underall, which prints them on stdout with the task’s prefix, andquiet, which prints the interrupt notice and a failed cleanup’s error but no cleanup instructions. -
Cleanup says what it follows, and
allreports every step. After a failure,simpleandallopen cleanup by naming it —Cleaning up after <task> exited with code <N>..., or the step and container that failed, such asCleaning up after db did not become healthy...— rather than Batect’sCleaning up.... Underall, each container the run started saysContainer stopped.and thenContainer removed.on its own prefix, and the task’s prefix saysRemoving task network...andTask network removed.; Batect’sallprints each container’sContainer stopped.only (decisions/0017). -
all‘s prefix colours. Container prefixes cycle five colours — cyan, yellow, green, magenta, blue — assigned by the containers’ sorted names, so a container keeps its colour whatever order its task’s graph lists it in, and the task’s own prefix is bold in the default foreground. Batect cycles six starting at black, assigns them in its dependency graph’s order, and paints the task prefix white (decisions/0017). -
An unhealthy dependency’s error can lack the last health check’s details. If the container, or the daemon, goes away between Docker’s unhealthy verdict and Ratect looking up that check’s exit code and output, the error gives the verdict alone. Batect reports the failed lookup instead, or crashes.
-
A startup failure drops the rest of startup at once. When one of a task’s containers can’t be started — its image won’t pull or build, or it doesn’t become ready — whatever else was starting alongside it is dropped there and then, and cleanup begins. Batect cancels that work and waits for it to wind down first. A container whose create the daemon already had is still removed: cleanup waits for that create’s answer before it removes anything, as Batect waits for its creates to finish. A further signal ends that wait as it would a graceful stop — everything else is force-removed — and a warning names the container and the run label that finds it.
-
Docker 20.10 or newer is required. Ratect refuses a daemon whose API is older than 1.41 (Docker 20.10) when it connects — before any task runs, whether or not BuildKit is asked for — because its proxy support needs 20.10’s
host-gatewayaddress (see Installation). Batect’s floor is API 1.37 (Docker 18.03), so Docker 18.03 to 19.03 runs under Batect and is refused by Ratect. Below API 1.37 both refuse, in different words: Ratect’s error names the API version the daemon supports and the 1.41 it requires; Batect’s, in red, names the daemon’s Docker version. The exit code is any failure’s (see Exit codes and error reporting) —125on a run — where Batect’s is-1(255). Batect’s refusals of BuildKit on a daemon too old for it, or without experimental features turned on, apply only below Docker 18.09, so none could fire on a daemon Ratect accepts, and they aren’t ported. -
A task network name collision on Docker 20.10 to 24 fails later, and leaves the second run’s network behind. Batect sets the network create request’s
CheckDuplicateoption, which has the daemon refuse a second network with the same name. Ratect’s Docker client has no such option: API 1.44 deprecated it, since Docker 25’s daemon refuses a duplicate name without being asked. So on an older daemon a run that draws another run’s suffix creates a second network of that name, then fails at container creation or start rather than at network creation. Its network stays, anddocker network rm <name>refuses to remove either. Docker 25 and later refuse the duplicate network under Batect and Ratect alike. See Cross-task isolation. -
The daemon is first asked for its version, not pinged. Ratect’s first request is
/version; Batect sends/_pingand then asks for the version, before running anything. The image builder — BuildKit or the classic one — is chosen only once a run first builds an image, from a/_pingmade then (see--enable-buildkitunder CLI flags). And a daemon that can’t be reached, or is too old, is reported in Ratect’s own words, not Batect’sDocker is not installed, not running or not compatible with Batect: …— for an unreachable one, naming the host tried (see What is checked on connecting). -
A daemon running Windows containers is refused. Ratect checks the operating system the daemon reports and refuses
windowsbefore running anything, since it only supports Linux containers. Batect accepts a Windows daemon, and refuses only one reporting neither Linux nor Windows, which Ratect doesn’t check. -
The task network is ready before any image work starts. Ratect creates it — or, under
--use-network, checks that it exists — and only then pulls or builds an image, where Batect does both at once. So a network problem, such as a missing--use-networknetwork or an exhausted address pool, fails the task straight away, rather than once the pulls and builds already in flight have finished. -
Cleanup carries on past a container it fails to stop or remove. A container whose stop fails isn’t removed, as under Batect, but cleanup still stops and removes the task’s other containers, including the ones it depends on; Batect’s cleanup stalls there and leaves them running. Ratect also still goes on to remove the task network, where Batect keeps it and lists it among the manual cleanup commands it prints. While that container is still attached to the network, Docker refuses, and that refusal is reported in the same
Cleanup failed:error as the container’s, which lists both as left behind. -
A container or network already gone at cleanup isn’t a failure. When something else has already removed one — a dependency
docker rm -f’d mid-run, say — Docker answers cleanup’s stop or removal with404, and Ratect counts it as removed, since nothing is left behind: a passing run still exits0, andratect resources cleancounts one that disappears mid-sweep as removed. Batect fails the task’s cleanup on any error from that stop or removal,404included. -
A task with only
prerequisitessays so in every style butquiet. Once its prerequisites have run,The task <name> only defines prerequisite tasks, nothing more to do.is printed as under Batect, but not under-o quiet, which prints only errors, warnings and notices; Batect prints it in every style. -
What cleanup leaves is reported in one line, in every style. A
--no-cleanup*run reportsLeft in place (--no-cleanup): …, and a cleanup that failedError: Cleanup failed: …; left behind: …, each naming the containers by config name and short id and endingRemove with:onedocker rm -f -vfor every container, thendocker network rmfor the network. After a--no-cleanup*run, a line per kept container gives Batect’sdocker logsanddocker exec -ithints, withdocker startfirst for one that isn’t running. Where they differ from Batect’s:- They are printed under
-o quiettoo; Batect’squietprints none of them. - After a failed cleanup only what was actually left behind is listed; Batect lists a command for every container and network the run created, removed or not, and says “some or all” of them may be needed.
- Containers are named by the twelve-character id
docker psshows, and the network by its name; Batect gives each container’s full id and the network’s id, onedocker rm --force --volumesper container. - Under
-o alla failed cleanup is that oneError:line, with no container prefix; Batect printsCould not stop container <name>.orCould not remove container <name>.on each container’s own prefix, andCould not delete the task network.on the task’s.
- They are printed under
-
A crash skips cleanup. If Ratect itself crashes mid-run — a bug, which exits
101and asks for a report — the run’s containers and network are left behind. Batect catches an internal error in a step and still cleans up. What a crash leaves carries Ratect’s ownership labels:ratect resources cleanremoves it (ratect-only), and fromratect-compat, which has no such command,dockerdoes, filtering on the project’s label —docker rm -f -v $(docker ps -aq --filter label=eu.orican.ratect.project=<project>), then the same filter ondocker network ls -qfordocker network rm. -
No pull lines for an image that’s already local. Under
image_pull_policy: IfNotPresent, an image that’s already present prints noPulling X.../Pulled X.lines; Batect prints both even though nothing is pulled. See Task Lifecycle. -
Under
image_pull_policy: Always, an image is pulled once per run, not again for each task in a prerequisite chain that uses it, as Batect does. Abuild_directoryimage is likewise built once per run, where Batect builds it again for each task — and, underAlways, pulls its base image again each time. See Task Lifecycle. -
fancymode draws a fresh block after the terminal’s width changes. The terminal has re-wrapped the old lines by then, so moving the cursor back up over as many lines as were drawn, as Batect does, lands it in the wrong place on common terminals and corrupts the display. Ratect leaves the old block where it is and draws the new one below it, at the cost of that leftover block. -
fancymode names the image it pulls, and calls a ready dependencyready. A container’s line readsready to pull image <image>and thenpulling image <image>..., where Batect’s readsready to pull imageandpulling <image>.... A dependency that has passed its readiness gate — healthy, and its setup commands done — readsready, where Batect’s readsrunning, which would fit a container that has started but isn’t yet healthy just as well. -
fancymode shows no cleanup line when cleanup is off. Under--no-cleanupor--no-cleanup-after-success, Batect briefly showsCleaning up: N containers (...) left to remove...when the task’s container exits, though nothing will be removed. Ratect shows none. -
fancymode draws a multi-line setup command on one row. Each line break in it is shown as a space, and the command runs as usual. Batect can’t draw it, and fails the task with an unexpected-exception error and exit code 255 before the command runs — which a|block’s trailing newline is enough to cause, even for a one-line command. -
fancymode treats a reported terminal width of 0 as unknown. Some pseudo-terminals report it (script‘s, some CI runners’), and lines are then printed unclipped; Batect clips every line to nothing. -
Under
run_as_current_user, a mount point nested inside alocalmount is created with the type its source needs. For a file or socket mounted inside alocalmount —./config.jsonat/code/config.jsonunder.at/code— Ratect creates an empty file at the mount point, and the mount works. Batect always creates a directory there, which fails the run: a file or socket can’t be mounted over a directory, and an existing file at the mount point fails the creation itself. Ratect also follows a symlink on the way to a mount point only while it stays inside the enclosing mount’s host directory, leaving the mount point to the daemon otherwise; Batect follows it even out of that directory, creating the mount point outside the project. See User mapping.
Next steps
The behaviour both binaries share is documented in its own right rather than against Batect: Task Lifecycle for what a run does step by step, Dependency Readiness for when a dependency counts as ready, Includes for how included files combine and what a Git bundle may do, and the FAQ.
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.
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.
Includes
A project is one root configuration file and everything it includes. An
include entry pulls in either another file from your own tree or a bundle
— a Git repository holding a configuration file — and the result is one flat
set of containers, tasks and config variables, as if it had all been written
in the root file. This page is the one place for how included files combine,
where their relative paths end up, and what a file that arrived through a Git
include is and isn’t allowed to do. The entries’ own fields — repo, ref,
path, the clone cache and how to refresh it — are in the batect.yml
reference, and mean the same in
a ratect.toml; what the native format adds is in the ratect.toml
reference. Why you’d share a bundle
across projects at all is Reusable Pipeline Building
Blocks.
Every rule here holds in both formats: the two parse into one model, and an
include is resolved the same way whichever file declared it. The one exception
— what a bundle’s own Git includes are allowed to do — is
marked where it comes up. The examples are ratect.toml,
with the batect.yml spelling shown where the syntax differs.
Two kinds of include
A file include names another configuration file in your own tree, by a path
relative to the directory of the file that declares it — not the root project
directory — so a file in a subdirectory can include more files relative to its
own location. A path whose first component is ~ means your home directory
instead, by the same rule as a volume’s host
path. A Git
include names a repository and a ref, and Ratect clones it into
~/.ratect/incl (so it is refused with no home directory) and includes one file
from the clone — the bundle’s
batect-bundle.yml unless the entry’s path says otherwise, with a
ratect.toml project looking for ratect-bundle.toml first (the ratect.toml
reference has the lookup). A Git
include’s path is taken as written within the clone, a leading ~ included.
In a ratect.toml project both kinds may mix, and each included file is parsed
by its own extension, so a native project can pull in an existing batect.yml
fragment or bundle unchanged:
include = [
{ path = "ci/tasks.toml" }, # a file include
{ path = "shared/legacy.yml" }, # still YAML
{ type = "git", repo = "https://example.com/bundle.git", ref = "v2" },
]
A batect.yml spells the same three entries as a bare path, an object with
type: file, or an object with type: git:
include:
- ci/tasks.yml
- path: shared/other.yml
type: file
- type: git
repo: https://example.com/bundle.git
ref: v2
How included files combine
Every loaded file’s containers, tasks and config_variables are merged
into one flat set. A name defined in more than one file is a hard error naming
every file that defines it — it is never treated as one file overriding another,
so a project can’t redefine a container that came from a bundle (see what a
consuming project can and can’t
change
for the two narrower ways to adapt one). An included file may include
further files of its own.
Includes are walked breadth-first: every entry in the root file is reached before any included file’s own, and each file is loaded exactly once, by its resolved absolute path, however many entries name it. So two files may both include a common third without it being read twice — and, for a Git include, the first entry to reach a file is the one whose settings that file is loaded with, which is what a grant goes on the entry that reaches the file first rests on.
Which fields a file may use
A file’s own format decides which fields a container may use and which
rules its file loads under — not the project that includes it. A .yml is
Batect’s format, so a container written in one may use no ratect-native
field (extends, ulimits, stop_signal/stop_grace_period,
dns/dns_search/dns_options,
network_mode, user/group/groups, identity, run_to_completion,
external_health_check, a cache’s scope, a setup command’s run_in) and
gets Batect’s own semantics: no expressions resolved in image, and exactly
one of image/build_directory. That holds even when a ratect.toml
project is what pulled the file in, and it holds for a YAML root file too
— ratect -f batect.yml reads a Batect file, and reads it as one.
A native field fails the load whatever its value, as an unknown field does
in Batect: run_to_completion: false is refused like true, and a
malformed value is reported as the field that doesn’t belong, not as a bad
value.
The same goes for a Git include entry’s native-only fields,
allow_nested_git_includes and
reviewed_ratect_version: a .yml
that sets either one fails to load, under either binary, whatever its value.
Under ratect the error names the field and the file, and the way out that
file has: a root .yml needs the project converted (ratect config convert), since a YAML root can’t include a TOML file,
and so does a .yml it includes; a .yml a TOML root includes can move that
Git include into a TOML file; and a bundle file needs its author to, plus the
project converted if its root is YAML.
allow_host_paths isn’t one of them — both formats accept it.
What a container does at run time follows the binary instead, not the file:
under ratect, a task’s own container has no readiness gate, whichever file
declares it — a .yml task container in a native project, or in ratect -f batect.yml, gets no health wait and runs no setup_commands, exactly as a
TOML one. Under ratect-compat it has Batect’s. See The task’s own
container.
To use a native field on a container, move that container into a .toml
file. Under ratect the error gives the same ways out, for that container.
Incremental migration exists so a project needn’t be converted in one go (see Migrating a Batect
project), not so a YAML file can grow native
features — and the unit you convert is a container, which is smaller than a
file.
The flow between them is one-way, which is what makes this workable: a
native container may extends
a container declared in a YAML file, because the container namespace is flat
once includes are merged. The reverse — a YAML-declared container extending
anything — is the rejected case above.
For a bundle author, the same rule is why a Git bundle can ship
ratect-bundle.toml and batect-bundle.yml side by side (see Two kinds of
include): the YAML one stays consumable by Batect
and ratect-compat, and the TOML one is free to use native fields.
Where relative paths resolve
A relative path within a container — a volume’s host path, build_directory,
a build_secrets entry’s path, a build_ssh entry’s paths — resolves
against the directory of the file that declares the container, not the root
project directory. For a file reached through a Git include that is the file’s
own directory inside the clone — the same rule, rooted in the clone rather than
in your project. The built-in batect.project_directory
config variable always resolves to the root file’s directory, whichever file it
is written in, and is how an included file names the project directory
explicitly.
A project laid out as:
myproject/
├── ratect.toml
├── scripts/
└── containers/
├── extra.toml
└── data/
with a root ratect.toml of:
project_name = "myproject"
include = [{ path = "containers/extra.toml" }]
[tasks.my-task]
run = { container = "my-other-container" }
and a containers/extra.toml of:
[containers.my-other-container]
image = "alpine:1.2.3"
volumes = [
# containers/extra.toml's own directory is containers/, so this
# resolves to myproject/containers/data — not myproject/data.
{ local = "./data", container = "/data" },
# Always the root project directory, regardless of which file this
# is written in — so this is myproject/scripts, not
# myproject/containers/scripts.
{ local = "<{batect.project_directory}/scripts", container = "/scripts" },
]
runs my-other-container with those two volumes mounted exactly as resolved
in the comments. my-task lives in the root file, but the container it runs
could equally have been declared there instead; only the volume paths’
resolution depends on which file declares the container. In a batect.yml
project the included file is containers/extra.yml and its
two entries are ./data:/data and an object whose local is
<{batect.project_directory}/scripts — not the string form
<{batect.project_directory}/scripts:/scripts, whose host path a batect.yml
uses as written (see Volume path
resolution). (This project is
illustrative; the nearest real one is
ratect-compat/tests/fixtures/include.yml,
whose included file mounts its own directory for exactly this reason.)
Owned files and bundle files
What a file may do depends on how it was reached, not on what kind of include
named it last, and not on its extension. A file reached from the root without
passing through a Git include is owned: yours, unrestricted, the same
trust as the root file itself. A file reached by passing through a Git include
is a bundle file — including any file the bundle then includes with a
plain file include, since that is still the bundle choosing what to load. A
local .yml your ratect.toml includes is owned; a .toml a bundle includes
from its own clone is not. (CONTEXT.md is the glossary for
these terms.)
An owned file is subject to none of what follows. A bundle file is loaded under a boundary: the containment it must stay within, together with whatever grants the include entry that reached it carried.
What a bundle may do
A bundle defines both a container and the command that runs inside it, which
is the combination that matters: without a check, a bundle could declare a
container mounting ~/.ssh or ~/.aws and a command that reads it, and a
project including that bundle would have no way to know from its own
configuration alone. decisions/0004
has the full reasoning; the rules it settled on are these.
Containment
Two things are contained, and both are a deliberate divergence from Batect, which has no equivalent check.
Which files a bundle can make part of your configuration. A Git include’s
path, and every include entry declared (transitively) by the file it names,
must resolve to somewhere inside that repository’s own clone — an absolute
path, a ../.. traversal, or a symlink pointing back out are all rejected with
a clear error rather than silently reading a file elsewhere on the machine
running Ratect. A file include in an owned file has no such restriction, since
it always names something already in your own checkout. A bundle can declare
a further type: git include of its own — a fresh repository with its own
boundary, not an escape from this one — in a ratect-compat project; a
ratect project refuses that unless you opt in, see Nested Git
includes below.
Where a bundle’s containers can reach on your machine. A volumes host
path, build_directory, build_secrets path or build_ssh paths declared
by a container in a bundle file must resolve to somewhere inside that repository’s own clone, or
inside your project directory; an absolute path, a ../.. traversal, or a
symlink pointing back out of both is rejected the same way. A path Ratect
cannot resolve at all is also rejected rather than assumed harmless: if a
directory along it can’t be searched, or a symlink loops, where the path really
leads can’t be established — and the Docker daemon that would dereference it
runs as root, under no such restriction. A path that simply doesn’t exist yet
is fine; Ratect or Docker creates it. The project directory is allowed as a
second root, rather than requiring pure containment within the clone, because
referencing it explicitly via batect.project_directory (say,
<{batect.project_directory}/output) is a legitimate, common thing for a
shared bundle to do — the project directory is your own fully-trusted tree,
distinct from the repository the container definition itself came from.
Vouching for a bundle
Some bundles legitimately need a path outside both roots — most often a shared
tool cache under your home directory, like ~/.cache/trivy, so a security
scanner’s own database is reused across every project rather than re-fetched
per project. Since neither customise nor a local redefinition can add a
volume to someone else’s container, there would otherwise be no way to use
such a bundle at all. Setting allow_host_paths on your own include entry
lifts the restriction for that bundle:
[[include]]
type = "git"
repo = "https://github.com/my-org/infra-bundle.git"
ref = "1.2.3"
allow_host_paths = true
include:
- type: git
repo: https://github.com/my-org/infra-bundle.git
ref: 1.2.3
allow_host_paths: true
It applies only to the bundle named there — never to bundles it includes in turn — and is honoured only in your own configuration: the same flag written inside a bundle file is ignored, so a bundle can neither grant itself the permission nor pass along one you gave it. It doesn’t relax the file containment above either; that governs which files become part of your configuration, a separate question from where a container may mount. What a future allowlist form would have to preserve is in decisions/0004.
For a native bundle whose whole purpose is a shared cache, a shared cache
volume says the same thing without
asking any consumer for host filesystem access — reach for that before
allow_host_paths.
Nested Git includes
batect.ymldiffers here. In aratect-compatproject a bundle’s owntype: gitincludes are always allowed, matching Batect, and the field below is rejected rather than ignored. Everything in this section is theratectbinary’s behaviour, and the field goes in a TOML file: a.ymlthat sets it fails to load underratecttoo (see Which fields a file may use).
A bundle can declare include entries of its own, and under ratect-compat
those may be further Git includes naming any remote, with the same trust your
own includes get. Under ratect that is refused by default:
The bundle 'https://github.com/my-org/infra-bundle.git' at '1.2.3' declares a
Git include of its own ('https://elsewhere.example/other.git'), which would
fetch and run configuration from a remote you have not named. Set
'allow_nested_git_includes' to true on that bundle's own include entry to
accept this; only a TOML file can set it.
You chose the bundle; you did not choose whatever it decides to pull in next,
and that choice can change under you the next time its ref moves. Opt in per
bundle by setting allow_nested_git_includes on the entry:
[[include]]
type = "git"
repo = "https://github.com/my-org/infra-bundle.git"
ref = "1.2.3"
allow_nested_git_includes = true
The entry doesn’t have to be in the ratect.toml itself — an entry in a local
file the project includes is just as much your own configuration, because that
file is owned. It does have to be a .toml
file: the field is native-only, so a .yml that sets it fails to load. To
grant from a shared .yml, move that Git include into a .toml file and
include that instead. ratect config convert
converts a whole Batect-format project from its root, not one included file.
The grant is one level deep. It admits that bundle’s own Git includes; it
does not let those bundles declare further ones. Like allow_host_paths, it
counts only in configuration you control — written inside a bundle file it is
ignored, so a bundle can neither grant itself the permission nor pass on the
one you gave it. If a bundle genuinely needs a chain deeper than that, include
the second repository yourself, where you can see it.
The refusal happens before anything is cloned, so a bundle can’t use a nested
include to probe for a remote it names. When a nested include is admitted
and its clone fails, the error names both repositories but keeps git’s own
transport detail behind RUST_LOG=debug — see the ratect.toml
reference for why.
A grant goes on the entry that reaches the file first
A repository is cloned once and each file in it read once, however many entries reach it, so whichever entry gets there first decides what that file is allowed — and a grant on the loser would quietly do nothing. Entries in the root file are always reached before any bundle’s own, so declaring the include yourself beats a bundle to it; between two entries in the same file, the earlier one wins. Where two entries reach the same file and the losing one carries a grant, Ratect refuses to load, names the repository and gives the ordering rule above, rather than leaving you to wonder why the flag had no effect. It can’t name the winning entry for you, and that entry is often inside a bundle you can’t edit — in which case the move is to declare the include yourself, in your root file, where it gets there first. Both grants follow this rule.
It is the file that races, not the repository: two entries naming the same
repository with different paths pull in two different files, and each keeps
the grant written on its own entry.
That is a different case from a grant written inside a bundle, which two words could easily blur. A grant written inside a bundle file is ignored — accepted by the parser and worth nothing, because honouring it would let a bundle grant itself. A grant in your own configuration that loses the race above is refused — the load stops, because you wrote something that cannot take effect and nothing else would tell you.
The version a bundle was written for
In a ratect.toml project, a bundle is checked the way the project itself is
by its ratect_version:
ratect refuses it when a later release has changed what its configuration
means, and lists those changes. The project’s own ratect_version doesn’t
cover it — raising yours says you reviewed your configuration, not every
bundle it includes. Either of two fields covers a bundle, and whichever names
the later version counts:
-
The bundle’s own
ratect_version, set by its author in the file the Git include names — its entry file. It covers every file reached from there, as a root’s covers its project. It is refused in any other file a bundle loads, and in a YAML file. -
The include entry’s
reviewed_ratect_version: you, as the author of the include, saying you reviewed the bundle against the changes up to that version. It lets you answer a refusal for a bundle you don’t own without waiting for its author. Like the grants it is native-only, so the entry has to be in a.tomlfile:[[include]] type = "git" repo = "https://github.com/my-org/infra-bundle.git" ref = "1.2.3" reviewed_ratect_version = "0.13.0"
A bundle that sets neither counts as written for 0.3.0, the first release
with ratect.toml, so it is refused under any release that has changed what a
configuration means since. The refusal names the bundle’s repository, ref and
entry file, and the file declaring the include, and offers both ways out —
when that file is a .yml, the second starts with getting that include into
TOML, the way that file allows. Like a
project’s, it says for each change whether it touches the
bundle,
looking only in the bundle’s own files — or, if the project doesn’t load, in
its entry file alone; whether it loads is the whole project’s answer.
- Every entry is checked on its own. Two entries reaching one bundle each
need covering, by the bundle’s version or their own
reviewed_ratect_version— unlike a grant, no entry wins. - A nested bundle is a bundle of its own, covered by neither its parent’s
version nor yours. The parent bundle’s entry for it may set
reviewed_ratect_versionif that bundle file is TOML: it widens no permission, so unlike a grant it counts in a bundle file too. A YAML bundle file can’t set it, so a TOML bundle it nests is covered only by its ownratect_version. - A YAML entry file follows Batect’s rules, as a
batect.ymlroot does: it can’t setratect_version, and a bundle whose files are all YAML loads whatever has changed. That includes a change to how Ratect reads YAML: such a change brings Ratect’s reading closer to Batect’s, which is what the bundle was written for. Once a YAML entry file includes a.tomlfile, the bundle counts as written for 0.3.0, until its include setsreviewed_ratect_version. - A version newer than
ratectis refused, on either side. A bundle written for a newer Ratect is refused before anything but that field is read, rather than for a field this one doesn’t know: upgraderatect, or point the include’srefat a release of the bundle written for this one. Areviewed_ratect_versionnewer thanratectis refused too, since it can’t check a review against changes it doesn’t know.
The acknowledgement isn’t tied to a ref: it still counts after you change the
include’s ref, which is itself a change to review. No command writes it —
ratect config convert never does. ratect-compat rejects
reviewed_ratect_version as a ratect-native field, and checks no bundle.
What this does and doesn’t buy you
None of this makes a bundle safe to include blindly — it still runs code you
didn’t write, the same as adding any dependency does. What it buys you is that
the one attack this project has specifically hardened against (a bundle
quietly reaching for your credentials via a host mount) needs an explicit,
visible grant in your own file rather than working by default. Anything that
lets a bundle read or write outside its clone or the project directory without
that grant is a security bug — see SECURITY.md for how to
report one.
Reusable Pipeline Building Blocks
This is about why you’d reach for a Git include, not the mechanics of one —
those are on Includes, with the entries’ own fields in the
batect.yml and
ratect.toml references. This page
motivates the use case first, then the trust model it depends on, since a
bundle is code you didn’t write, running in your own environment.
The use case
Several projects that share a stack tend to end up wanting the same handful of things: the same linter run the same way, the same base image with the same hardening applied, the same “scan this for vulnerabilities” task. Copying a container/task definition into every project’s own config works, right up until the definition needs to change — then it’s a find-and-replace across however many repositories remembered to keep it in sync, and however many didn’t.
A bundle — a Git repository holding a configuration file, meant to be
imported rather than run on its own — is Ratect’s answer: define the
containers and tasks once, version the repository like any other code (tags,
releases, a changelog), and let every consuming project pull in a pinned
version with one include entry. Bump the pin when you’re ready to take a
change; every consumer bumps on its own schedule, not in lockstep.
# ratect.toml
include = [
{ type = "git", repo = "https://github.com/my-org/lint-bundle.git", ref = "v2.1.0" },
]
[tasks.lint]
prerequisites = ["shared-lint"]
Here shared-lint isn’t defined anywhere in this project’s own file — it
came from the bundle, merged in exactly as if it had been written locally
(see how included files combine). The
project’s own lint task just sequences it in as a
prerequisite.
A bundle is untrusted code by default
A bundle doesn’t just define a container — it also controls the command that
runs inside it, so Ratect loads it under a boundary: its containers may mount
only inside the bundle’s own clone or your project directory unless you
vouch for it with allow_host_paths, a grant counts only when written in your
own configuration, and (in ratect.toml) its own Git includes are refused
until you opt in per bundle. The rules, the two grants and what they do and
don’t buy you are on Includes;
decisions/0004
covers the full reasoning.
What a consuming project can and can’t change
A project can’t redefine a container that came from an include — declaring a container with the same name in your own file is a hard error, not an override. Two narrower ways to adapt a bundle’s container to your own project without forking it:
customise(both formats) — a task can override a non-main container’senvironment,ports, andworking_directory. Deliberately notvolumes: letting a consumer silently add a mount to someone else’s container would undercut the containment above at the one place it actually matters. See TaskContainerCustomisation.extends(ratect.tomlonly) — a container in your own file can inherit from one defined in an included bundle and layer its own fields on top, shallow-merged per field. Useful when a bundle ships a base image and expects projects to build on it rather than use it as-is. Seeextends.
A cache shared across projects, without a host mount
ratect.toml’s shared caches
(scope = "shared" on a cache volume) are worth calling out specifically
for a bundle that wants one Cargo registry or npm cache reused across every
project that includes it. The alternative is a host path —
local: ~/.cache/cargo — which means asking every consumer for
allow_host_paths. A shared cache says the same thing directly, grants no
host filesystem access, and stays under Ratect’s own control
(ratect-shared-cache-<name>, alongside ~/.ratect/incl where Git includes
themselves are cloned). If you’re authoring a native bundle whose whole
purpose is a shared tool cache, reach for this before reaching for
allow_host_paths.
Pinning and updating a bundle
A bundle’s (repo, ref) is cloned once and cached forever at
~/.ratect/incl — never re-fetched, even if ref later moves. This is why
ref must be an immutable tag or a pinned commit SHA, never a branch: a
branch ref would look like it updates and never actually would, which is
worse than a pin that’s honest about being frozen. To take a bundle change,
bump ref to a new tag (the versioning story that makes bundles worth
having in the first place). If ref itself moved (a branch, or a re-pushed
tag) rather than your own config changing, ratect has a purpose-built
command for that: ratect includes refresh discards every cached clone and
re-fetches it — see the CLI reference.
ratect-compat has no equivalent subcommand, but both binaries share
~/.ratect/incl, so ratect includes refresh refreshes what a
ratect-compat run cached too; failing that, delete the corresponding
directory under ~/.ratect/incl by hand.
Authoring a bundle that supports both formats
A bundle repository is just a config file at a path, so there’s nothing
format-specific about being a bundle. ratect.toml’s own Git-include
resolution looks for ratect-bundle.toml first, then falls back to
batect-bundle.yml when no path is given — so a bundle author can ship
both files, and a project on either format includes the same repository and
gets the file meant for it. See Includes
for the exact lookup order.
Output Styles
--output/-o controls how much Ratect says about its own progress, and never
where anything goes. What the task’s command prints streams through as written
in every style but all, which prefixes each of its lines with the container’s
name, as it does every other line. Both binaries take it (ratect on every
command, ratect-compat on every invocation) and render each style with the
same code
(ui.rs),
so this page is the one
description of the four styles; the ratect
and ratect-compat CLI references only link
here.
Streams
Stdout is the result; stderr is everything said about producing it
(decisions/0017).
For a run, the result is the task container’s own output. Everything else —
progress, the summary line, notices, warnings and errors — is about the run,
and -o shapes how much of it is said, not which stream it is said on.
The two binaries differ in one thing: where their progress goes.
ratectwrites its progress — the milestones, the summary line, and underallthe prefixed lines of every container but the task’s own — to stderr. Its stdout is the task container’s output and nothing else, in every style (underall, each line prefixed with the container’s name), soratect run test > out.txtcaptures the result alone and2>/dev/nullsilences the conversation without touching it.ratect-compatwrites its progress to stdout, where Batect does, because a Batect project’s scripts may read it. Undersimplethose lines share stdout with the task’s own output, unmarked, exactly as under Batect;-o quietis the escape for a script that needs stdout to be the container’s output alone, and-o allprefixes every line.
Three kinds of line reach stderr in every style, quiet included, from
both binaries, whatever RUST_LOG is set to: an error (Error: in bold red,
then the message), a warning (Warning: in bold yellow — a deprecated flag,
a proxy bound to loopback that containers can’t reach, a credential helper
that failed), and a notice (unmarked: the interrupt notice with its “press
Ctrl+C again” instructions, the Cleanup complete. that follows it once
cleanup is over, and what --no-cleanup* left in place and how to remove it).
Only the fourth kind, progress, is shaped by -o.
RUST_LOG filters Ratect’s internal diagnostics
(Filtering RUST_LOG), which are a
separate stream of breadcrumbs on stderr; nothing a user needs to act on is
behind it.
A task’s own non-zero exit is reported by the exit code and, outside quiet,
by the summary line — never by an Error: line; a run ended by a signal is
reported by the interrupt notice and its exit code, and ends with Cleanup complete. (or the error saying what cleanup left behind) rather than a
trailing Error: Interrupted. Error: is reserved for Ratect’s own failures: it could
not run the task, or could not clean up after it. A failure to run a task that
has started — an image that won’t pull, a dependency that never becomes
healthy — is reported when it happens, before any cleanup line, and outside
quiet the run then ends with the summary line’s other form, <task> failed after <duration>., where finished with exit code N would have gone. So
does a run whose command exited 0 but whose cleanup then failed, after the
error saying what was left behind; a command that exited non-zero keeps its
finished with exit code N line whatever cleanup does. A
failure before any task starts, such as a config that doesn’t load, is printed
as the run exits, with no summary line, as is a prerequisite’s failure for the
task waiting on it: the prerequisite’s own line is the one printed.
In every style, and in every command’s own output, a control character in a
name or value from your configuration (a task, container, image or cache
name, a path, a command, a Git include’s repo or ref), or in image build
output, is printed escaped: \u{1b} for ESC, \r for a carriage return. A
Git bundle or a config file can’t send your terminal escape sequences that
way. A name’s or value’s line breaks and tabs are escaped too (\n, \t),
error messages included, so neither can add a line of its own. A command and
image build output keep theirs, as does the output of a program an error
quotes, such as git’s. A container’s own output is printed as it was written.
Each style is shown below from the same real run — ratect run journey-test
against
examples/full-stack
— so you compare styles rather than projects.
When --output isn’t given, Ratect auto-selects: fancy on an interactive
console (the stream its progress goes to — stderr for ratect, stdout for
ratect-compat — is a real terminal, TERM is set and not dumb, the
terminal size is queryable, and there is no --no-color); simple
otherwise. quiet and all are never auto-selected; ratect services up is the
exception, which always uses all and refuses any other -o. So ratect run test > out.txt on a terminal still gets fancy — the pipe took the result, not the
conversation — where ratect-compat test > out.txt gets simple.
fancy
The same real recording as the homepage, unedited — static text can’t convey an in-place repaint:
What the recording can’t tell you: there is no spinner — the animation is
purely rewriting the block’s lines in place, as Batect’s is — and lines are
clipped to the terminal’s current width. After that width changes, the block is
drawn afresh below the old one rather than over it, since the terminal has
re-wrapped the old lines. Because it repaints, it needs a terminal: an explicit
-o fancy asks less than auto-selection does — TERM may be unset, but not
dumb — and fails up front, with an error naming the reason, when the stream it
checked isn’t a terminal, TERM is dumb, or the terminal size can’t be
determined (Batect instead accepts it, then crashes on the first repaint when
stdout isn’t a terminal, or garbles a TERM=dumb terminal with cursor movements
it can’t perform). Works with
--no-color — the repaint stays; bold/color go — a combination
Batect rejects.
simple
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.
Append-only, with no live-updating progress detail at all, so it is safe for
CI logs and redirected output. A dependency that exits on its own while the
task runs is reported as a milestone (db exited unexpectedly with exit code 137.), not a warning — the run’s failure, if one follows, is what explains
it. The health/setup-command milestones are shown
for dependency containers only. Under ratect the task’s own container has
no readiness gate to report (see Dependency
Readiness); under
ratect-compat its readiness runs concurrently with its command (see task
lifecycle), so
printing them would drop a line into the middle of that command’s own output
— all shows them. A readiness failure is still reported, on stderr,
in every style.
Cleanup opens with Cleaning up..., or, when it follows a failure, names it —
Cleaning up after journey-test exited with code 3..., or, when the task
couldn’t run, the step and container that failed: Cleaning up after db did not become healthy..., Cleaning up after db's setup command 1 exited with code 3..., Cleaning up after cache's image failed to pull.... The Error: above
it says why. all opens it the same way.
quiet
ratect run journey-test -o quiet, captured the same way:
added 6 packages, and audited 7 packages in 1s
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
No progress at all: stdout is exactly the task container’s own output (under
ratect it is in every style but all, which prefixes each line with the
container’s name; quiet is where ratect-compat matches it),
and stderr carries only errors, warnings and notices. Nothing
from app/db/cache — a dependency’s own stdout is never shown outside
all, whatever the style.
quiet also switches a task listing (ratect tasks list, ratect-compat --list-tasks) to a machine-readable format: one task per line, sorted by
name, as name alone or name<TAB>description — no header, no
grouping. The ratect
commands with a listing of their own (services list, caches, includes,
resources, doctor) each have a quiet form of the same kind, described with the
command in the ratect CLI reference.
all
ratect run journey-test -o all, captured the same way — long, because every
line db, cache and app wrote during the run is here too:
journey-test | Running journey-test...
db | Starting container...
cache | Starting container...
db | Container started.
cache | Container started.
db | ********************************************************************************
db | WARNING: POSTGRES_HOST_AUTH_METHOD has been set to "trust". This will allow
db | anyone with access to the Postgres port to access your database without
db | a password, even if POSTGRES_PASSWORD is set. See PostgreSQL
db | documentation about "trust":
db | https://www.postgresql.org/docs/current/auth-trust.html
db | In Docker's default configuration, this is effectively any other
db | container on the same system.
db |
db | It is not recommended to use POSTGRES_HOST_AUTH_METHOD=trust. Replace
db | it with "-e POSTGRES_PASSWORD=password" instead to set a password in
db | "docker run".
db | ********************************************************************************
cache | 1:C 28 Oct 2026 19:12:43.874 * oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
cache | 1:C 28 Oct 2026 19:12:43.874 * Redis version=7.4.11, bits=64, commit=00000000, modified=0, pid=1, just started
cache | 1:C 28 Oct 2026 19:12:43.874 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
cache | 1:M 28 Oct 2026 19:12:43.874 * monotonic clock: POSIX clock_gettime
cache | 1:M 28 Oct 2026 19:12:43.874 * Running mode=standalone, port=6379.
cache | 1:M 28 Oct 2026 19:12:43.874 * Server initialized
cache | 1:M 28 Oct 2026 19:12:43.874 * Ready to accept connections tcp
db | The files belonging to this database system will be owned by user "postgres".
db | This user must also own the server process.
db |
db | The database cluster will be initialized with locale "en_US.utf8".
db | The default database encoding has accordingly been set to "UTF8".
db | The default text search configuration will be set to "english".
db |
db | Data page checksums are disabled.
db |
db | fixing permissions on existing directory /var/lib/postgresql/data ... ok
db | creating subdirectories ... ok
db | selecting dynamic shared memory implementation ... posix
db | selecting default max_connections ... 100
db | selecting default shared_buffers ... 128MB
db | selecting default time zone ... Etc/UTC
db | creating configuration files ... ok
db | running bootstrap script ... ok
db | performing post-bootstrap initialization ... ok
cache | Container became healthy.
db | syncing data to disk ... ok
db |
db |
db | Success. You can now start the database server using:
db |
db | pg_ctl -D /var/lib/postgresql/data -l logfile start
db |
db | initdb: warning: enabling "trust" authentication for local connections
db | initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.
db | waiting for server to start....2026-10-28 19:12:44.910 UTC [54] LOG: starting PostgreSQL 16.15 (Debian 16.15-1.pgdg13+2) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
db | 2026-10-28 19:12:44.911 UTC [54] LOG: listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db | 2026-10-28 19:12:44.913 UTC [57] LOG: database system was shut down at 2026-10-28 19:12:44 UTC
db | 2026-10-28 19:12:44.915 UTC [54] LOG: database system is ready to accept connections
db | done
db | server started
db |
db | /usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/01-schema.sql
db | CREATE TABLE
db | INSERT 0 1000000
db | CREATE INDEX
db |
db |
db | waiting for server to shut down....2026-10-28 19:12:46.289 UTC [54] LOG: received fast shutdown request
db | 2026-10-28 19:12:46.290 UTC [54] LOG: aborting any active transactions
db | 2026-10-28 19:12:46.291 UTC [54] LOG: background worker "logical replication launcher" (PID 60) exited with exit code 1
db | 2026-10-28 19:12:46.291 UTC [55] LOG: shutting down
db | 2026-10-28 19:12:46.292 UTC [55] LOG: checkpoint starting: shutdown immediate
db | 2026-10-28 19:12:46.435 UTC [55] LOG: checkpoint complete: wrote 10152 buffers (62.0%); 0 WAL file(s) added, 0 removed, 10 recycled; write=0.057 s, sync=0.071 s, total=0.144 s; sync files=45, longest=0.028 s, average=0.002 s; distance=174130 kB, estimate=174130 kB; lsn=0/BEFF470, redo lsn=0/BEFF470
db | 2026-10-28 19:12:46.440 UTC [54] LOG: database system is shut down
db | done
db | server stopped
db |
db | PostgreSQL init process complete; ready for start up.
db |
db | 2026-10-28 19:12:46.509 UTC [1] LOG: starting PostgreSQL 16.15 (Debian 16.15-1.pgdg13+2) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
db | 2026-10-28 19:12:46.510 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432
db | 2026-10-28 19:12:46.510 UTC [1] LOG: listening on IPv6 address "::", port 5432
db | 2026-10-28 19:12:46.513 UTC [1] LOG: listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db | 2026-10-28 19:12:46.517 UTC [77] LOG: database system was shut down at 2026-10-28 19:12:46 UTC
db | 2026-10-28 19:12:46.521 UTC [1] LOG: database system is ready to accept connections
db | Container became healthy.
db | Running setup command psql -U postgres -c "ANALYZE visits;" (1 of 1)...
db | Setup command 1 | ANALYZE
db | Container has completed all setup commands.
app | Starting container...
app | Container started.
app |
app | added 99 packages, and audited 100 packages in 993ms
app |
app | 18 packages are looking for funding
app | run `npm fund` for details
app |
app | found 0 vulnerabilities
app | npm notice
app | npm notice New major version of npm available! 10.9.8 -> 12.2.1
app | npm notice Changelog: https://github.com/npm/cli/releases/tag/v12.2.1
app | npm notice To update run: npm install -g npm@12.2.1
app | npm notice
app |
app | > full-stack-app@1.0.0 start
app | > node server.js
app |
app | Listening on port 8080
app | Container became healthy.
journey-test | Running sh -c 'npm ci && node test.js'...
journey-test |
journey-test | added 6 packages, and audited 7 packages in 906ms
journey-test |
journey-test | found 0 vulnerabilities
journey-test | app responded: {"message":"Hello from Ratect!","visit_id":1000001,"total_visits":1000001,"count_source":"database"}
journey-test | cache holds visits:count=1000001, confirming app and this container share the same cache
journey-test | journey test passed
journey-test | Cleaning up...
journey-test | Container stopped.
journey-test | Container removed.
app | Container stopped.
app | Container removed.
db | 2026-10-28 19:12:50.860 UTC [1] LOG: received fast shutdown request
cache | 1:signal-handler (1793214770) Received SIGTERM scheduling shutdown...
db | 2026-10-28 19:12:50.861 UTC [1] LOG: aborting any active transactions
db | 2026-10-28 19:12:50.862 UTC [1] LOG: background worker "logical replication launcher" (PID 80) exited with exit code 1
db | 2026-10-28 19:12:50.862 UTC [75] LOG: shutting down
db | 2026-10-28 19:12:50.864 UTC [75] LOG: checkpoint starting: shutdown immediate
db | 2026-10-28 19:12:50.883 UTC [75] LOG: checkpoint complete: wrote 14 buffers (0.1%); 0 WAL file(s) added, 0 removed, 0 recycled; write=0.001 s, sync=0.013 s, total=0.021 s; sync files=12, longest=0.002 s, average=0.002 s; distance=20 kB, estimate=20 kB; lsn=0/BF044A8, redo lsn=0/BF044A8
db | 2026-10-28 19:12:50.884 UTC [1] LOG: database system is shut down
cache | 1:M 28 Oct 2026 19:12:50.933 * User requested shutdown...
cache | 1:M 28 Oct 2026 19:12:50.933 * Saving the final RDB snapshot before exiting.
cache | 1:M 28 Oct 2026 19:12:50.936 * DB saved on disk
cache | 1:M 28 Oct 2026 19:12:50.936 # Redis is now ready to exit, bye bye...
db | Container stopped.
db | Container removed.
cache | Container stopped.
cache | Container removed.
journey-test | Removing task network...
journey-test | Task network removed.
journey-test | journey-test finished with exit code 0 in 7.6s.
The only style that shows dependency containers’ stdout/stderr,
setup-command output, and full image-build output (Image build | ...) —
everything the other styles discard. In exchange, no container is
interactive in this mode: the task container gets no
TTY and no stdin, and every container gets TERM=dumb (matching Batect — a
full-screen program can’t render into line-prefixed output). That is why, next to simple’s capture, npm draws no
spinner here.
Nothing in examples/ builds from a Dockerfile (every container uses a
prebuilt image), so Image build | ... output has no real capture to
point at here.
Colour
Colour in Ratect’s own output (the exit code in the summary line, all’s
per-container prefixes, the Error:/Warning: markers, and the bold that
picks out task, container and image names and commands in simple
and fancy progress) is, by default,
emitted only when the stream being written to is a terminal — each stream
decides for itself, so with ratect run test > out.txt the progress on stderr
is still coloured while a 2>err.txt gets plain text, RUST_LOG lines
included — and a task command’s own output is never touched either way. No
message depends on its colour to be read: colour only distinguishes one
container’s prefix from another’s or emphasises a marker word, a name or the
exit code, and Ratect never paints text in the terminal’s own white or black,
which some themes render invisible. Three controls adjust that, and their
precedence is fixed:
| Control | Effect |
|---|---|
--no-color | Disables colour in Ratect’s own output, on both streams. Since colour is already skipped when a stream isn’t a terminal, this only matters on an interactive console — unless CLICOLOR_FORCE is also set, which it overrides. Also makes simple, not fancy, the auto-selected style; an explicit -o fancy --no-color still gets a colourless fancy. |
NO_COLOR | If set — to anything, even empty, per no-color.org — exactly the same effect as --no-color. |
CLICOLOR_FORCE | If set to anything other than 0, forces colour even when a stream isn’t a terminal (a CI log viewer that renders ANSI despite the pipe). Never affects which style is auto-selected. |
--no-color/NO_COLOR always win: if either is set, CLICOLOR_FORCE is
ignored.
Connecting to Docker
Every command that reaches a Docker daemon takes the same set of connection
options, on both binaries: ratect run, ratect caches, ratect resources
and ratect doctor each accept them (ratect tasks list, ratect includes
and ratect config never connect, so they don’t), and ratect-compat accepts
them on every invocation and uses them whenever the invocation actually
connects (a --list-tasks run never does) — though it checks a Docker config
or certificate directory given by an option or DOCKER_CONFIG/DOCKER_CERT_PATH,
and a file given to a TLS option, on every one. On both binaries, --docker-context beside --docker-host or a
TLS option is refused whether or not the command connects — ratect caches
with the directory store, or a ratect-compat --list-tasks, included — and
ratect doctor reports it as a problem. This
page is the one description
of those options; the ratect and
ratect-compat CLI references only
link here.
With none of them given, Ratect connects to DOCKER_HOST if it is set,
otherwise through a Docker context if one resolves (DOCKER_CONTEXT, then the
active context), otherwise to Docker’s own platform default, the Unix socket
unix:///var/run/docker.sock — see Which daemon is used.
Options
| Flag | Default | Description |
|---|---|---|
--docker-host <HOST> | DOCKER_HOST | Docker host to connect to, e.g. unix:///var/run/docker.sock or tcp://1.2.3.4:5678. An https:// host connects over TLS as if --docker-tls-verify were given. Cannot be combined with --docker-context. |
--docker-context <NAME> | DOCKER_CONTEXT, then the active context, unless a host is set | Docker CLI context to connect through — read from the Docker CLI’s own context store (~/.docker/contexts/, or --docker-config’s directory). The active context is ~/.docker/config.json’s currentContext. Cannot be combined with --docker-host or any of the TLS options below. Errors clearly if the named context doesn’t exist in the store. |
--docker-config <PATH> | DOCKER_CONFIG, then ~/.docker | Directory containing the Docker CLI’s own configuration files (context store, config.json). A directory given here or by DOCKER_CONFIG must exist and be a directory; ~/.docker needn’t exist. |
--docker-tls | — | Use TLS when connecting to the Docker host. Behaves identically to --docker-tls-verify — the daemon’s certificate is always fully verified; there is no way to skip verification. |
--docker-tls-verify | DOCKER_TLS_VERIFY | Use TLS when connecting to the Docker host, verifying its certificate. Needs a host: --docker-host or DOCKER_HOST. |
--docker-cert-path <PATH> | DOCKER_CERT_PATH, then --docker-config/DOCKER_CONFIG, then ~/.docker | Directory containing any of ca.pem/cert.pem/key.pem to authenticate to the Docker host and verify it, unless overridden individually by the three options below. A directory given here or by DOCKER_CERT_PATH must exist and be a directory, whether or not TLS is used. None of the three files has to be there — see TLS through the options. |
--docker-tls-ca-cert <PATH> | ca.pem in the certificate directory | The TLS CA certificate used to verify the Docker host’s own certificate — the only certificate authority it is checked against. The file must exist. Without this option and without a ca.pem, the system trust store is used. |
--docker-tls-cert <PATH> | cert.pem in the certificate directory | The TLS certificate used to authenticate to the Docker host. The file must exist, and so must the key. |
--docker-tls-key <PATH> | key.pem in the certificate directory | The TLS key used to authenticate to the Docker host. The file must exist, and so must the certificate. |
A path given to --docker-config, --docker-cert-path, --docker-tls-ca-cert,
--docker-tls-cert or --docker-tls-key, or by DOCKER_CONFIG or DOCKER_CERT_PATH,
has a leading ~ expanded to your home directory, and . and .. removed, before it
is used, as in Batect. The Docker CLI takes the two variables as written. Your home
directory, here and for ~/.docker, is $HOME when it is set and absolute, else
your passwd entry’s: the Docker CLI’s rule, so Ratect reads the ~/.docker that
docker login writes to. The Docker CLI also takes a relative $HOME; Ratect
doesn’t. With no home from either, as under a numeric docker run -u with HOME
unset, there is no ~/.docker: Ratect connects with no stored credentials, and
refuses a named context or TLS that would read its certificates from there
unless --docker-config or DOCKER_CONFIG names a directory instead.
TLS through the options
With --docker-tls or --docker-tls-verify (or DOCKER_TLS_VERIFY), or an
https:// host, the certificate directory is --docker-cert-path, then DOCKER_CERT_PATH, then
the Docker config directory if one was given (--docker-config, then
DOCKER_CONFIG), then ~/.docker (an empty DOCKER_CERT_PATH counts as
unset). A directory given by any of those four sources must exist, and every
command that connects checks it first; ~/.docker must exist unless all
three files are named by their own options. What it holds
decides how the connection is made:
--docker-tls-ca-cert, or else the directory’sca.pem, is the only certificate authority the daemon’s certificate is checked against. With neither, the system trust store is used — for a daemon whose certificate a public certificate authority signed.--docker-tls-certand--docker-tls-key, or else the directory’scert.pemandkey.pem, are presented as the client certificate. With neither option and neither file, none is presented. Only one of the two files in the directory is an error, and so is giving one option when the directory doesn’t hold the other file.- A file named by an option must exist and not be a directory, whether or not
TLS is used: every command that takes the option checks it before it runs.
It needn’t be a regular file — a pipe, such as
<(cat key.pem), is read like one, once. - An encrypted key, or one that doesn’t match the certificate, is an error naming the option or the directory, and the file.
- Only a
tcp://orhttps://host, or a barehost:port, can be connected to over TLS.
If the daemon’s certificate fails verification and no certificate authority
was given, the error says where a ca.pem was looked for. A daemon with a
self-signed or privately signed certificate needs one — see
TLS with a private certificate authority.
A Docker context follows the same file rules with the files it stores — see below.
Which daemon is used
A flag always wins over its environment variable. Between the two ways of naming a daemon, the order is:
--docker-context <NAME>on the command line, if given.- Otherwise, a host —
--docker-host, thenDOCKER_HOST— if either is set. No context is consulted at all. - Otherwise a context, if one resolves:
DOCKER_CONTEXT, then the active context. - Otherwise Docker’s own platform default.
This is the Docker CLI’s own order. A context named default — from any of the
three sources — means “no context”, as in the Docker CLI: Ratect connects to
DOCKER_HOST if it is set, otherwise to the platform default. An
empty DOCKER_HOST or DOCKER_CONTEXT counts as unset, also as in the Docker
CLI.
The active context is the currentContext in the Docker config directory’s
config.json, read only when step 3 gets that far. A config.json that can’t
be read, or isn’t valid JSON, has none to give: Ratect warns, naming the file,
and goes on to step 4, as the current Docker CLI does.
A connection through a context uses the endpoint that context stores; the TLS
options only apply to a host connection. Naming one alongside
--docker-context is an error; when step 3 picks the context instead, the TLS
options are ignored, as in Batect.
A context brings its own TLS settings instead — the ones docker context create
stored for it — used as the Docker CLI uses them:
- The context connects over TLS if it stores a
ca.pem, acert.pem/key.pempair, or setsSkipTLSVerify. Otherwise it connects without TLS. - A stored
ca.pemis the only certificate authority the daemon’s certificate is checked against. Without one, the system trust store is used. - A stored
cert.pem/key.pempair is presented as the client certificate. Without one, none is. Storing only one of the two is an error. - An encrypted
key.pem, or one that doesn’t matchcert.pem, is an error naming the context and the file. - Only a
tcp://orhttps://host can be connected to over TLS.
A context naming an https:// host also connects over TLS, storing TLS material
or not — the same as --docker-host https://…, and unlike the Docker CLI, which
connects to such a host without TLS unless the context stores some.
SkipTLSVerify is not honoured: the daemon’s certificate is always fully verified,
as with --docker-tls. If verification fails for a context that sets it, the error
says so — see TLS with a private certificate authority
for making the certificate verifiable instead.
What is checked on connecting
Before asking the daemon for anything else, Ratect checks three things, and stops with an error if any fails:
- That it answers. When no connection can be made at all — nothing
listening, a host name that doesn’t resolve, no route to it — the error says
the daemon couldn’t be reached, names the host tried and what chose it
(
--docker-host,DOCKER_HOST, a context, or the platform default), and suggests checking that Docker is running and that the host or context is the right one. The underlying reason follows as its cause. - That it is Docker 20.10 or newer (API 1.41) — see Installation for why.
- That it runs Linux containers. A daemon in Windows containers mode is refused, naming the operating system it reports: switch Docker to Linux containers to use Ratect.
Environment variables
| Variable | Effect |
|---|---|
DOCKER_HOST | Docker host to connect to — the default for --docker-host. Setting it means no context is used unless --docker-context is given. Empty counts as unset. |
DOCKER_CONTEXT | Docker CLI context to connect through — the default for --docker-context. Ignored when a host is set. Empty counts as unset. |
DOCKER_CONFIG | Directory containing the Docker CLI’s own configuration files — the default for --docker-config, and for --docker-cert-path when DOCKER_CERT_PATH is unset. Must exist and be a directory when set and not empty. A leading ~ is your home directory, as for the option. |
DOCKER_CERT_PATH | Directory containing any of ca.pem/cert.pem/key.pem for TLS — the default for --docker-cert-path. Empty counts as unset; otherwise it must exist and be a directory. A leading ~ is your home directory, as for the option. |
DOCKER_TLS_VERIFY | 1, yes or true enables TLS, fully verified, and 0, no or false leaves it off, in any case — the default for --docker-tls-verify. Empty counts as unset. Any other value is an error when connecting to a host, unless --docker-tls or --docker-tls-verify is given; a command that doesn’t connect, or connects through a context, never reads it — though ratect doctor reports one as a problem whichever way it connects. |
TLS with a private certificate authority
--docker-tls/--docker-tls-verify always fully verify the Docker daemon’s
certificate — there is no flag or environment variable that skips verification, unlike
Batect’s own bare --docker-tls (which sets Go’s tls.Config.InsecureSkipVerify,
disabling chain-of-trust, expiry, and hostname checks all at once, not just the
hostname check). This isn’t just inherited from a missing feature: rustls, the
library Ratect’s TLS support is built on, takes the same position deliberately —
there’s no boolean toggle for skipping verification in rustls either, only a
dangerous() accessor that requires implementing the ServerCertVerifier trait from
scratch to bypass it. Ratect doesn’t reach for that. If you reach for --docker-tls
(skip-verify) because your daemon’s certificate is self-signed —
including for local development or CI — the fix isn’t to skip verification, it’s to
make the certificate verifiable: run your own certificate authority, and trust that,
rather than trusting nothing.
The daemon side of this (configuring dockerd to require TLS, generating its
server certificate) is standard Docker documentation, not Ratect-specific — see
Protect the Docker daemon socket.
What follows is the client side: a self-contained, worked example of generating a
private root CA, signing a server certificate for the daemon with it, and pointing
Ratect at the result.
-
Create a root CA. This is the one certificate you’ll trust from now on — keep
ca-key.pemprivate; it’s the only thing standing between “verified” and “not”.openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \ -keyout ca-key.pem -out ca.pem -subj "/CN=my-docker-ca" -
Generate and sign the daemon’s own certificate, naming every hostname/IP clients will actually connect through as a Subject Alternative Name (SAN) — verification checks this, not the certificate’s
CN:openssl req -newkey rsa:4096 -sha256 -nodes \ -keyout server-key.pem -out server-req.pem -subj "/CN=docker-daemon" openssl x509 -req -in server-req.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial \ -out server-cert.pem -days 3650 -sha256 \ -extfile <(printf "subjectAltName=DNS:docker-daemon.example.com,IP:203.0.113.10") -
Configure
dockerdto require TLS with this certificate (/etc/docker/daemon.jsonor the equivalentdockerdflags — see the Docker documentation linked above), usingca.pem/server-cert.pem/server-key.pemfrom steps 1–2. -
Point Ratect at the CA (client certificate/key are only needed if the daemon itself also requires client auth — generate a second cert signed by the same CA for that, following step 2’s pattern):
ratect run test \ --docker-host tcp://docker-daemon.example.com:2376 \ --docker-tls-verify \ --docker-tls-ca-cert ./ca.pemratect-compattakes the same three options, before the task name. Or set--docker-cert-pathto a directory containingca.pem(andcert.pem/key.pem, if the daemon requires client auth) instead of naming each file individually — see Options. Leave the CA out altogether and the daemon is checked against the system trust store, which a private CA is not in: verification fails, and the error says where aca.pemwas looked for. A Docker context created with the same files (docker context create my-daemon --docker "host=tcp://docker-daemon.example.com:2376,ca=./ca.pem") works too, through--docker-context my-daemon— see Which daemon is used.
If verification fails, the error names the problem (expired, wrong host, untrusted issuer) rather than silently connecting anyway — that’s the entire point of not supporting skip-verify. Regenerate whichever certificate is actually at fault, rather than reaching for a flag Ratect doesn’t have.
File Ownership and the Home Directory
A task that writes through a bind mount, such as a build writing its output or
a formatter its fixes, writes onto your machine. Who owns those files on the
host depends on the daemon and on the user the container runs as. On a rootful
Linux daemon, an image with no USER writes them as root: files you can’t edit,
and directories you can’t remove.
Separately, a program inside the container that looks under ~ for its
configuration finds the home of the image’s user, which differs from image to
image.
identity
does both jobs. What a container writes through a bind mount is yours wherever
the daemon allows it, and $HOME is the path you name, on every daemon and in
every image, so ssh configuration and caches can be mounted below it once:
[containers.as-you]
image = "alpine:3.24"
working_directory = "/code"
identity = { home = "/home/me" }
groups = ["users"]
volumes = [
{ local = ".", container = "/code" },
{ local = "ssh", container = "/home/me/.ssh", options = "ro" },
]
That container is from
examples/identity,
which the rest of this page walks through. The reference has every rule
identity follows; this page is what those rules add up to on each daemon.
Who owns what a container writes
Which kind of daemon you have is the Docker daemon class line of
ratect doctor. On each, a container writing to a
directory of yours through a bind mount gives this:
| Daemon class | Image’s USER | Runs as | Owner on the host, without identity | Owner on the host, with identity |
|---|---|---|---|---|
rootful Linux | root, or none | root, or you with identity | root | you |
rootful Linux | non-root, such as app | that user, or you with identity | that user’s uid, where the directory lets others write | you |
desktop | any | the image’s USER, or root | you | you |
rootless | root, or none | root | you | you |
rootless | non-root | that user | a subordinate uid, where the directory lets others write | the same, and the run warns |
userns-remap | any | the image’s USER, or root | a subordinate uid, where the directory lets others write | the same, and the run warns |
How each daemon gets there:
- On a rootful Linux daemon a file’s owner is the uid of the process that
wrote it, so
identityruns the container as your uid and gid. Without it, a non-root imageUSERcan only write where the directory lets anyone write, and a directory you created with the usual0755refuses it. - Docker Desktop, OrbStack and similar on macOS or Windows share files with
the host as you, whoever wrote them in the container.
identityleaves the image’sUSERrunning. - A rootless daemon maps root in the container to you, so an image that runs
as root writes your files without
identity. Any other container user maps to a subordinate uid, which has only other users’ access to your directory. - A userns-remap daemon maps every container user to a subordinate uid,
root included. Root in the container writes as uid
100000, say, so a directory you own with0755refuses it.
Where the owner is a subordinate uid, nothing Ratect can apply makes it yours, so
a run warns about each identity container that meets it, naming the container,
and ratect doctor reports the userns-remap case. That ownership has to be
arranged on the host. The home is still guaranteed there.
Writing through a bind mount
The example has a second container, the same image and mount without
identity, and a task that writes through each:
[containers.as-image]
image = "alpine:3.24"
working_directory = "/code"
volumes = [{ local = ".", container = "/code" }]
[tasks.write-as-you]
description = "Write out/as-you/ through the bind mount, with identity"
run = { container = "as-you", command = "sh -c 'mkdir -p out/as-you && id -u > out/as-you/uid'" }
[tasks.write-as-image]
description = "Write out/as-image/ through the bind mount, without identity"
run = { container = "as-image", command = "sh -c 'mkdir -p out/as-image && id -u > out/as-image/uid'" }
[tasks.clean]
description = "Remove what the write tasks left in out/, whoever owns it"
run = { container = "as-image", command = "rm -rf out/as-you out/as-image" }
ratect run write-as-image -o quiet && ratect run write-as-you -o quiet && ls -lnd out/* out/*/*, captured on a terminal in examples/identity, on a
rootful Linux daemon:
drwxr-xr-x 1 0 0 6 Nov 8 22:35 out/as-image
-rw-r--r-- 1 0 0 2 Nov 8 22:35 out/as-image/uid
drwxr-xr-x 1 1001 1001 6 Nov 8 22:35 out/as-you
-rw-r--r-- 1 1001 1001 5 Nov 8 22:35 out/as-you/uid
alpine has no USER, so without identity its directory and file are
root’s. With identity they belong to uid 1001, the user who ran Ratect. The
same command on a desktop daemon, OrbStack on macOS, where both containers ran
as root:
drwxr-xr-x@ 3 501 20 96 Nov 8 22:35 out/as-image
-rw-r--r--@ 1 501 20 2 Nov 8 22:35 out/as-image/uid
drwxr-xr-x@ 3 501 20 96 Nov 8 22:35 out/as-you
-rw-r--r--@ 1 501 20 2 Nov 8 22:35 out/as-you/uid
Both are yours there, identity or not, since file sharing makes them so.
Removing what root left behind
A root-owned directory can’t be removed without root, even in a directory you
own: removing a directory means removing what is in it, and that takes write
access to the directory itself. The clean task does it from a container
without identity, which runs as root. rm -rf out/as-image; ratect run clean -o quiet && ls -A out, captured on a terminal in examples/identity, on a
rootful Linux daemon:
rm: cannot remove 'out/as-image/uid': Permission denied
.gitignore
out/.gitignore is the one file the project keeps there, so out itself is
yours from the moment you clone it. Without it, the first task to write there
would create out, and on a rootful Linux daemon a container without
identity would create it as root, leaving the next one with identity unable
to write inside it.
To see all of this on your own daemon:
ratect run write-as-image
ratect run write-as-you
ls -lnd out/* out/*/*
ratect run clean
The same home on every daemon
[tasks.show-home]
description = "Show the running user, its groups and its home"
run = { container = "as-you", command = """sh -c 'echo "user: $(id -un) ($(id -u)), groups: $(id -Gn)"; echo "HOME: $HOME"; echo "passwd: $(getent passwd $(id -u) | cut -d: -f6)"; ls -ld ~ ~/.ssh'""" }
ratect run show-home -o quiet, captured on a terminal in examples/identity,
on a desktop daemon:
user: root (0), groups: root bin daemon sys adm disk wheel floppy dialout tape video users
HOME: /home/me
passwd: /home/me
drwxr-xr-x 1 root root 8 Nov 8 22:35 /home/me
drwxr-xr-x 1 root root 96 Nov 8 22:31 /home/me/.ssh
and on a rootful Linux daemon:
user: runner (1001), groups: runner users
HOME: /home/me
passwd: /home/me
drwxr-xr-x 1 runner runner 8 Jan 1 1970 /home/me
drwxr-xr-x 1 runner runner 12 Nov 8 22:35 /home/me/.ssh
The running user differs, root on one and you on the other, but $HOME and that
user’s /etc/passwd entry agree on /home/me on both, so Git, which reads
$HOME, and ssh, which reads the passwd entry, both look there. On the rootful
daemon the image had no entry for uid 1001, so one was added with your username.
The read-only mount at ~/.ssh is below the home, so Docker created /home/me
before Ratect could, as root. Where the running user isn’t root, the home is
handed over to them, which is why it is runner’s on the rootful daemon. groups
works alongside identity, adding users to whoever runs.
An image with its own user and home
Some images run as a non-root user with a home of their own. The example builds one:
# A non-root user with its own home, as many language images have.
RUN adduser -D -u 1000 app
ENV HOME=/home/app
# A fresh cache volume takes its owner and mode from the image's directory at
# the same path, here below the `app` container's `identity` home in
# ratect.toml. Writable by anyone, so whoever the container runs as can fill
# the `prepared` cache. The `unprepared` one has no directory here.
RUN mkdir -p /home/me/.cache/prepared && chmod 777 /home/me/.cache/prepared
USER app
and runs it with identity and two cache volumes below the home:
[containers.app]
build_directory = "app-image"
identity = { home = "/home/me" }
volumes = [
{ type = "cache", name = "prepared", container = "/home/me/.cache/prepared" },
{ type = "cache", name = "unprepared", container = "/home/me/.cache/unprepared" },
]
[tasks.show-app-home]
description = "Show the running user and its home in an image with its own USER and HOME"
run = { container = "app", command = """sh -c 'echo "user: $(id -un) ($(id -u))"; echo "HOME: $HOME"; echo "passwd: $(getent passwd $(id -u) | cut -d: -f6)"'""" }
ratect run show-app-home -o quiet, captured on a terminal in
examples/identity, on a desktop daemon:
user: app (1000)
HOME: /home/me
passwd: /home/me
and on a rootful Linux daemon:
user: runner (1001)
HOME: /home/me
passwd: /home/me
The image’s app user runs on one and you on the other, and identity’s home replaces the
image’s ENV HOME on both.
Cache volumes below the home
[tasks.fill-caches]
description = "Write to the two cache volumes below the home"
run = { container = "app", command = "sh -c 'set -e; touch ~/.cache/prepared/ok; echo prepared: written; touch ~/.cache/unprepared/ok; echo unprepared: written'" }
ratect run fill-caches -o quiet, captured on a terminal in
examples/identity, on a desktop daemon, where the task fails:
prepared: written
touch: /home/me/.cache/unprepared/ok: Permission denied
and on a rootful Linux daemon, where it passes:
prepared: written
unprepared: written
A fresh volume is root-owned unless the image has a directory at the same
path, whose owner and mode it then takes. On a rootful Linux daemon, Ratect
hands a root-owned cache volume to you before the container starts, so both
caches are writable there. Everywhere else, app can’t write to the
unprepared volume. The prepared one takes mode 777 from the image’s
directory, so it is writable on every daemon.
chown app in the image would fix the desktop daemon and break the rootful
one: there you run instead of app, and Ratect leaves a volume another uid owns
alone. A volume that has already been created keeps its owner, so after changing
the image, remove the cache to have it created
again.
Setting HOME yourself
A HOME in environment wins over identity’s, though the passwd entry still
says home:
[tasks.show-home-override]
description = "Show the home when HOME is set in environment"
run = { container = "as-you", environment = { HOME = "/code" }, command = """sh -c 'echo "HOME: $HOME"; echo "passwd: $(getent passwd $(id -u) | cut -d: -f6)"'""" }
ratect run show-home-override -o quiet, captured on a terminal in
examples/identity, on a desktop daemon:
HOME: /code
passwd: /home/me
So Git looks in /code and ssh in /home/me. Leave HOME out of environment
unless that split is what you want.
What identity leaves to you
- It is opt-in. A container without it on a rootful Linux daemon writes as
its image’s
USER, or root if it has none. Unless it sets a non-rootuser,ratect doctorwarns about each of its writable bind mounts, since it doesn’t pull the image to see itsUSER. homeis required, even if ownership is all you want.- An entrypoint that drops privileges, as
postgresdoes, writes as the user it switches to, whoever the container started as. - A daemon on another machine (
ssh://,tcp://) still gets the uid and gid of the user running Ratect, which needn’t be yours on that machine. Ratect creates no host directories for it, so the daemon creates a missing bind mount source as root. - Docker Desktop on Linux is a
rootful Linuxdaemon to Ratect, soidentityruns the container as you there too, although its file sharing may make what it writes yours anyway. See On a rootful Linux daemon.
Coming from Batect? identity has the same goal as run_as_current_user, and
Coming from run_as_current_user
says which daemons get which mechanism.
Where to go next
- Every rule
identityfollows, including adding service users an image lacks, is in theidentityreference. - Which daemon Ratect connects to, and how to choose another, is Connecting to Docker.
- The next page, Interactive Mode, covers when a task’s container gets a terminal.
Interactive Mode
A task whose command drops you into a shell, or otherwise needs your input,
works with nothing to configure: there is no interactive field in either
format, and the same task is interactive under both binaries. This page is
the one description of what that means — which container is eligible, what
it gets, when a real terminal is allocated, and how the container learns
what kind of terminal it has. The examples are ratect.toml; the
batect.yml spelling is the same fields with the same meaning.
[tasks.shell]
description = "Start a shell in the app's environment"
group = "Utilities"
run = { container = "dev", command = "bash" }
ratect run shell lands you in bash inside dev, with your keystrokes
reaching it and its output reaching you. That is the
full-stack example’s own shell task; each
project on Worked Examples carries one too.
Which container is eligible
Each task’s own container — the task named on the command line, and every prerequisite it runs, however deeply nested. A dependency’s or a sidecar’s container is never interactive. Prerequisites run one after another, and each task container is attached to Ratect’s stdin only while it runs. Whatever input is waiting meanwhile is forwarded to it, whether or not it reads it, so a prerequisite takes piped input ahead of the named task. If the pipe ends while it runs, the named task’s stdin is closed from the start. What you type at a terminal goes to the task container running at the time; what you type between two of them waits for the next.
What the eligible container gets
Always, independent of whether Ratect’s own stdin and stdout are terminals,
its stdin forwarded from Ratect’s own, so piped input reaches the
container — including its end: when Ratect’s own stdin closes, so does the
container’s, and a process that reads until end of input (cat, a stdio
server) exits. (The host’s TERM isn’t the eligible container’s alone:
every container gets it — see TERM propagation
below.)
Additionally, when both Ratect’s own stdin and stdout are real
terminals, a real Docker TTY: the local terminal goes into raw mode for
the session, so a full-screen program (an editor, top, a REPL with line
editing) renders as it would in a shell. The terminal is restored when the
session ends; if that fails, a warning says so and names the fix (reset or
stty sane). A raw terminal sends Ctrl+C to the
container as a keystroke, as docker run -it does, so it interrupts the
program in the container rather than the run — and a command running as the
container’s main process with no handler of its own ignores it. Piped output,
a redirected non-terminal, or a CI job gets plain stdin forwarding and
streamed output instead — stdin still reaches the container either way.
The one exception is --output all, whose
line-prefixed output can’t host an interactive session: under it no
container gets a TTY or stdin, and every container gets TERM=dumb instead,
matching Batect.
Terminal resizing
When a TTY is allocated, the container’s stays in sync with the local
terminal’s size for the whole session, not just once at the start — a local
resize is forwarded live, via a SIGWINCH handler. That tracking is
Unix-only; on other platforms the size is synced once, at the start of the
session, and not tracked further. Interactive mode itself works on every
platform.
TERM propagation
Ratect’s own TERM environment variable is copied into the environment of
every container a run creates — the invoked task’s own, each prerequisite’s,
and every dependency and sidecar — whether or not that container is
eligible, matching Batect. Under --output all every
container gets TERM=dumb instead. It isn’t gated on a real TTY actually
being allocated either, so a full-screen program inside the container knows
the terminal type even when piped output lets it detect that it isn’t
attached to a real TTY. Never applied to an image build.
Where it sits among the container’s other environment variables — what overrides it on a key collision — is Environment precedence.
Coming from Batect? One known, deliberate divergence: Batect’s real-TTY gate checks only whether its output is a real terminal; Ratect’s requires both stdin and stdout to be. It is listed, with the Unix-only resize tracking, under Differences from Batect.
Proxies
When http_proxy, https_proxy, ftp_proxy or no_proxy are set in the
environment Ratect itself runs in — in either case, so HTTP_PROXY too —
they are injected into every container’s environment and every image
build’s build arguments. A task or a build that needs to reach the network
through a proxy just works, without repeating the proxy settings in
environment or build_args by hand. There is no config field for this in
either format; it is automatic, on both binaries, and
--no-proxy-vars turns it off. This page is the one
description of what is injected, how it is adjusted for a container’s point
of view, and what it can’t fix.
Precedence
Where an injected variable sits among a container’s other environment
variables, and among a build’s build_args — what overrides it on a key
collision — is Environment
precedence.
Proxies from Docker’s config.json
An image build also gets the proxies set in the proxies section of the
Docker CLI’s config.json, as docker build and Batect builds do. It is the
same file Ratect reads registry credentials and contexts from: in the
directory --docker-config names, else DOCKER_CONFIG, else ~/.docker.
{
"proxies": {
"default": {
"httpProxy": "http://proxy.example.com:3128",
"noProxy": "internal.example.com"
}
}
}
The entry used is the one keyed by the Docker host the run connects to,
spelled as the Docker CLI spells it (unix:///var/run/docker.sock,
tcp://build-host:2376), else default. Each of its httpProxy,
httpsProxy, ftpProxy, noProxy and allProxy becomes a build argument
in both cases — HTTP_PROXY and http_proxy, and so on — but only where
the build doesn’t already have that argument, so a proxy from the
environment and a container’s own build_args both win over it. The values
are passed as written: none of the adjustments below are made to them.
This is for image builds only; a container’s environment gets nothing from
config.json. A missing config.json, or one with no proxies, adds
nothing.
no_proxy is extended
Every container sharing a task’s network — the task’s own container and each
of its dependencies — has its own name appended to no_proxy/NO_PROXY, so
traffic between them isn’t sent through the proxy. Not done for image
builds: nothing is running yet during a build, so there is nothing to
exempt.
A proxy on localhost
An http_proxy/https_proxy/ftp_proxy value that points at localhost,
127.0.0.1 or ::1 is rewritten to host.docker.internal, since
localhost from inside a container refers to the container itself, not
the machine running the proxy. A value that isn’t an http/https URL, or
doesn’t refer to the local machine, is left unchanged.
This happens on every platform, including Linux — where, unlike under Docker
Desktop, nothing supplies host.docker.internal by itself. So a run that
rewrote a URL also adds host.docker.internal:host-gateway to every
container it starts and every image it builds, using Docker’s own
--add-host mechanism, which the daemon resolves to the machine running it.
That entry is added on every platform too, not only the one that needs
it: on macOS and Windows it names the same gateway Desktop would have
answered with, so it is a new /etc/hosts line rather than a change in what
the container can reach. What gates it is the rewrite, not the platform — no
rewrite, no entry — and a container’s own
additional_hosts entry for
that name always wins over it.
A proxy bound to loopback only
Rewriting the URL can’t make an unreachable proxy reachable. A proxy bound
only to 127.0.0.1 — which is what cntlm and similar default to — still
refuses a connection from a container, so on Linux Ratect checks
/proc/net/tcp/tcp6 and warns, once per run and naming the port:
The proxy on port 3333 is listening on loopback addresses only, so containers in this run cannot reach it even though its URL now names the host. Bind the proxy to 0.0.0.0 to make it reachable — which also exposes it to anything else that can reach this machine, so do that only on a network you trust. Use
--no-proxy-varsif this run doesn’t need the proxy.
It’s a warning, not a failure: the run may never use the proxy. Note the
security cost it names — binding a proxy to 0.0.0.0 opens it to everything
that can reach the machine, so weigh that rather than applying it
reflexively. Some proxies offer the same thing as a narrower setting:
cntlm, for
instance, binds 127.0.0.1:3128 by default and listens on every interface
only under its Gateway option.
A host firewall
A host firewall can block the container’s traffic even when the proxy is bound wide enough, and that case Ratect can’t detect — so if the warning doesn’t fire and the proxy still isn’t reachable, check there next.
What to look for: the connection arrives on the bridge interface of the
user-defined network the run is using, never Docker’s default docker0
bridge, so a firewall rule written for docker0 won’t cover it. Ratect
creates a network per task, or uses the one
--use-network names — and a
run can’t fall back to the default bridge even if you point --use-network
at it, because Ratect gives every container on it a network-scoped alias and
Docker only allows those on user-defined networks (docker run refuses with
network-scoped aliases are only supported for user-defined networks).
Match the rule on that network’s subnet, which docker network inspect <network> reports under IPAM.Config. Its interface name is generally not
in that output — Docker only records one there when the network was created
with com.docker.network.bridge.name, which is how docker0 itself gets
its name — so a rule pinned to an interface is both harder to write and
easier to get wrong.
Turning it off
--no-proxy-vars disables all of the above for one run: nothing is injected
into any container or build — the proxies from Docker’s config.json
included — no_proxy is left alone, and no URL is rewritten. A container’s
own build_args are still passed. It is a ratect run option, and a
ratect-compat flag.
Coming from Batect? Three deliberate differences: a localhost proxy is rewritten on Linux too,
where Batect propagates it verbatim; a loopback-bound proxy is diagnosed
rather than left to fail; and --no-proxy-vars keeps the proxies from
Docker’s config.json out of a build, where Batect passes them whatever its
flag says. All three are listed under Differences from
Batect.
Troubleshooting
Where to look when a run fails, or hangs. Each of these has a home elsewhere in the documentation already; this page is the entry point — one line per symptom, linking where it lives — plus the one thing every diagnosis ends up needing, reading Ratect’s own logs, which is written here.
| Symptom | Where it lives |
|---|---|
| Will this run fail? Why did it? | ratect doctor (ratect only) answers both without running a task: an unreachable daemon, a configuration that doesn’t load, a build_directory or Dockerfile a build can’t use, and the warnings that bite later (a floating image tag, an absolute dockerfile, a dependency with no health check). |
| A dependency never becomes ready | How Docker reaches its verdict: docker ps and docker inspect show the health state Ratect is waiting on, and Ratect imposes no timeout of its own, so a check configured to retry forever waits forever. |
| The build failed | Image building: a failing build’s whole transcript is in the error Ratect reports, under every output style; for a live transcript, see filtering RUST_LOG below. |
| I need to see what Ratect is doing | Filtering RUST_LOG, below. |
| A container was left behind, or I want to keep one | ratect resources lists and removes what a crash, a docker kill or a failed cleanup left; --no-cleanup, --no-cleanup-after-success and --no-cleanup-after-failure keep a run’s containers on purpose, running, so you can look inside — on ratect run and ratect-compat. |
| What does this exit code mean | ratect and ratect-compat exit with the same codes: the task’s own container’s, 128 + the signal’s number for a run ended by one, 125 for a run that fails for any other reason, a usage error included (or whose cleanup fails after it passed), 1 for any other verb that fails, 2 for one invoked wrong, 101 for a crash. |
| A JVM or Node build hangs or dies silently | How do I raise Docker Desktop’s resource limits? — every container runs under Docker’s own CPU/memory ceiling, and a heavy build under a tight one looks like a hang or an OOM kill. |
| Files a task wrote are root-owned, or a later write says permission denied | File Ownership and the Home Directory: who owns what a container writes through a bind mount on each kind of daemon, what identity changes, and how to remove a root-owned directory without root. On a rootful Linux daemon, ratect doctor (ratect only) warns about each writable bind mount of a container with neither identity nor a non-root user. |
&& or $VAR in a command did nothing | Why doesn’t && or $VAR work in my command? — command is literal argv, with no shell and no expression support. |
Filtering RUST_LOG
Ratect’s own diagnostics go to stderr, filtered by the RUST_LOG
environment variable (default info) — Logging vs.
output is the split between them and
Ratect’s output proper, which RUST_LOG never filters: progress, errors,
warnings and notices are printed whatever it says. RUST_LOG=debug adds every container creation,
start and removal, each setup_commands exec’s raw output, and every image
build’s log lines, which is usually what “what is Ratect doing?” is asking
for.
RUST_LOG isn’t just an on/off level switch — tracing-subscriber’s
EnvFilter
syntax lets you scope it to specific modules (target=level directives, comma-separated).
This matters in practice once you turn on debug for anything build-related (e.g. to see
a live image build transcript): bollard (the Docker
API client Ratect is built on) also logs at debug, and a bare RUST_LOG=debug includes
all of its raw API traffic — usually far more noise than signal.
A directive with no target (e.g. RUST_LOG=debug) applies everywhere, including
dependencies like bollard. Scoping to a specific target instead — ratect_core covers
everything the ratect binary logs, and all but a few of ratect-compat’s own
lines, which log under ratect_compat (among them why a run failed) — excludes
anything not matched, including bollard,
without needing to name it:
# Only ratect_core's own logs, at debug — no bollard noise at all.
RUST_LOG=ratect_core=debug ratect run build
# Keep the normal `info` default everywhere else, but add ratect_core's debug-level
# output on top (e.g. build transcripts) — usually the more useful combination.
RUST_LOG=info,ratect_core=debug ratect run build
# Narrower still: just the Docker/build/container-runtime module, not task
# orchestration (`ratect_core::engine`) as well.
RUST_LOG=ratect_core::docker=debug ratect run build
If you do want a blanket debug sweep across everything (including bollard) but need to
silence one specific dependency, add it as its own =off directive instead:
RUST_LOG=debug,bollard=off.
The same variable and syntax apply to ratect-compat, which can also write
its logs to a file with --log-file. With
RUST_LOG unset, the file gets info,ratect_core=debug,ratect_compat=debug:
Ratect’s own debug records, so it has something to read even when stderr
was quiet and says why a run failed, but other crates only at info, so
bollard’s request bodies (below) never reach a file nobody asked to hold
them. Setting RUST_LOG replaces that default for the file as well as
stderr — RUST_LOG=debug puts bollard’s records in the file too, and
RUST_LOG=warn leaves out Ratect’s debug records, including why the run
failed.
Before pasting a debug log anywhere, remember two things it can carry.
bollard’s debug records include the body of each Docker API request and
response — a container’s create request carries its whole environment,
secrets passed through from the host included — so any directive that lets
bollard through at debug (a bare RUST_LOG=debug) logs them. And a
setup_commands exec’s output is whatever the command itself printed — so if
a setup command’s own output could include something sensitive (a failed
connection string, a verbose HTTP client dumping request headers), that ends
up in the debug log too. Treat RUST_LOG=debug (or narrower ratect_core=debug)
output with the same care you’d give the command’s own output before pasting
it into a support ticket, chat message, or CI log.
RUST_LOG=off never hides why a run failed: a fatal error bypasses the filter —
see Exit codes and error
reporting.
Coming from Batect? Ratect’s logs differ from Batect’s on purpose — where they go, --log-file
or not, and what --log-file writes — as listed under
Differences from Batect.
Frequently Asked Questions
Answers to real questions that come up using Ratect — not a restatement of the configuration reference, which already covers every field mechanically. This page is expected to grow: if something surprised you, it likely surprises the next person too — open an issue.
When should I mount a directory instead of copying files into the image?
Ratect gives you both, and they trade off differently:
- A
volumesbind mount ({ local = ".", container = "/code" }) makes your working directory show up live inside the container — every one of the worked examples does exactly this for its own source tree. Edit a file on the host, rerun the task, and the container sees the change with no rebuild. The image itself stays generic (a stock language toolchain image, not your code baked into it), so pulling it is normally fast and cached. build_directoryinstead builds aDockerfile— your code isCOPY’d in at build time, so the resulting image is fully self-contained (nothing left on the host is needed to run it) and portable (push it, run it elsewhere, get the exact same bytes). The cost is the build step itself: adocker buildon every task run unless Docker’s own layer cache absorbs it, and every source edit invalidates the layers built from it.
Rule of thumb: mount while you’re iterating locally — a task-runner project, almost
by definition, is exactly that case, which is why every project under examples/
mounts rather than builds. Reach for build_directory when the image itself is
the artifact you actually want to produce or ship (a container you’re going to
publish, or a build step whose whole point is producing that image) rather than a
disposable environment to run your code in.
How do I run something at container start regardless of the task’s command?
Use entrypoint rather than command. Docker runs
Entrypoint ++ Cmd — the entrypoint always executes first regardless of what
command (or a task’s run.command) is set to, and the classic idiom is a wrapper
script that does its setup, then hands off to whatever was actually asked for:
[containers.app]
image = "my-app"
entrypoint = "/entrypoint.sh"
#!/bin/sh
# /entrypoint.sh
set -e
# ... setup that must happen no matter which task/command runs ...
exec "$@"
The exec "$@" at the end matters: it replaces the shell process with the real
command instead of running it as a child, so the real command becomes PID 1 (or
inherits proper signal delivery under exec) rather than being one process removed
from it. This is also why entrypoint/command combine cleanly for the well-known
entrypoint = "/bin/sh -c", command = "make lint" idiom (an entrypoint tokenizes
exactly like command does — see the field reference) — Ratect passes both straight
through to Docker with neither side adding an extra shell layer of its own.
If what you actually need is signal forwarding and zombie reaping rather than a
custom setup step, see
enable_init_process instead — it runs Docker’s
own init process ahead of your command for exactly that, with nothing to write.
Why does task idempotency matter?
Because Ratect doesn’t cache “already succeeded” across invocations — there’s no
timestamp check, no “nothing changed, skipping” the way a build tool like make
gives you for free. Within one invocation, a prerequisite reached by more than one
path does run only once (see prerequisites — that’s
cycle-safe dedup, not a guarantee your script is safe to run twice), but every
separate ratect-compat/ratect invocation from the shell starts completely fresh,
with no memory of any previous run. Take the migrate/test example from Cross-task
isolation — test has migrate as a
prerequisite, and migrate runs run-migrations.sh:
Every ratect run test run executes migrate again first, from a fresh
container. If run-migrations.sh isn’t safe to run twice — it reapplies a
migration that’s already applied, or errors on a table that already exists — every
single test run breaks or corrupts state, not just the first one. The same applies
to any task with real side effects reused as a prerequisite: seeding data, writing
output files another task then reads. Design each task assuming it will run more
than once against the same environment; Ratect’s model of “always run fresh
containers” (see Cross-task isolation)
means it always will.
How do I raise Docker Desktop’s resource limits?
This isn’t a Ratect setting — every container Ratect starts still runs under whatever CPU/memory ceiling Docker itself is configured with, so a heavier build (the JVM or Node examples are the ones most likely to notice) can look like it’s hanging or gets silently OOM-killed when Docker’s own default is too tight, and it’s easy to blame the task runner instead of the actual cause.
- Docker Desktop on macOS or Windows: Settings → Resources lets you raise the
CPU/memory/swap ceiling directly. On Windows with the WSL2 backend specifically,
Docker Desktop’s own Resources page can instead defer to a
.wslconfigfile controlling the WSL2 VM’s limits — Docker Desktop’s own documentation covers which applies for your setup. - Linux with the Docker Engine directly (no Docker Desktop): there’s no VM in
the picture, so this ceiling doesn’t exist in the same way — containers share the
host’s resources directly, bounded only by whatever
docker run/daemon-level limits you’ve configured yourself.
Why doesn’t && or $VAR work in my command?
command (and entrypoint) are tokenized into literal argv — quote/backslash-aware
whitespace splitting, matching Batect’s own tokenizer exactly — with no shell
involved and no expression support. command = "echo $HOME && echo done" doesn’t
run two commands with $HOME expanded; it’s parsed as a single program named
echo given the literal argv $HOME, &&, echo, done — Docker will fail to
find an executable called $HOME. Anything relying on shell operators (&&, ||,
pipes) or runtime environment expansion needs an explicit shell wrapper:
command = "sh -c 'echo $HOME && echo done'"
This is easy to conflate with a second, entirely different $-syntax: Ratect’s own
config-time expressions ($VAR,
${VAR:-default}, <name), which do exist — but only in specific fields
(environment values, a local volume’s host path, build_directory, and a few others),
evaluated when the run reaches the task that uses them, never inside command itself. So there are
three different things that can look like “the same” $VAR: Ratect’s own
config-time expression syntax (only in the fields listed above), command’s literal
tokenizer (no substitution of any kind), and real shell expansion once you’re
actually running inside a container via sh -c (using the container’s runtime
environment, resolved by the shell, not by Ratect). Which one applies depends
entirely on which field you’re looking at.
Why isn’t my host environment variable visible inside the container?
Containers don’t inherit the host’s environment automatically — not Ratect’s own
choice, just how Docker containers work, but a common first surprise for anyone
coming from local shell scripts where every variable is already there. Any host
variable a container’s command needs has to be passed through explicitly via
environment, using Ratect’s own expression
syntax:
[containers.app]
image = "my-app"
environment = { API_KEY = "$API_KEY" }
Nothing here is a default worth changing — declaring every environment variable a container actually uses is deliberate, not boilerplate: it makes a task’s real inputs visible in the config itself instead of depending on whatever happened to be exported in whoever’s shell ran it.
What’s the difference between a dependency and a prerequisite?
They sound like synonyms but are two unrelated mechanisms:
- A dependency (a container’s own
dependencieslist) is another container, started alongside the one that needs it, kept running for the whole task, and torn down together at the end. Use it for something your task’s container talks to over the network while it runs — a database, a cache, a queue. See Dependency Readiness for how several of these combine. - A prerequisite (a task’s own
prerequisiteslist) is another task, run to completion — including its own full cleanup — strictly before the task that names it starts. Use it to sequence work:compilebeforetest, a migration before the tests that need it migrated. See Task ordering.
A dependencies container is there for the duration of the run; a
prerequisites task runs and finishes, with nothing of its own left when the
next task starts.
How It Works
This describes Ratect’s internal pipeline, for anyone extending Ratect or trying to
understand its behavior in detail. For the code itself, see AGENTS.md
for a map of the source layout.
1. CLI parsing
Each binary has its own main.rs, and both parse arguments with
clap: ratect-compat/src/main.rs for Batect’s flat flag
interface (CLI reference), and ratect/src/main.rs for the
subcommand interface (ratect CLI reference). Everything below
this step is shared — both call into ratect-core, which is where the rest of
this document lives. Parsing has to happen before config evaluation (step 2)
can run, since --config-var/--config-vars-file feed into it.
2. Config loading and evaluation (ratect-core/src/config.rs)
This is two separate steps, not one: loading checks what the file says, and evaluation reads what the machine running it supplies — see decisions/0014.
-
load_project(orload_project_native, forratect.toml) starts withConfig::load_from_file_with_git_cache(orload_from_file_native_written_for): the root file is parsed intoConfig/Container/Task/TaskRun/ConfigVariable/ServiceGroupstructs — YAML vianoyalib, TOML viatoml, one struct set for both formats — and its top-levelincludelist (if any) is resolved, with every loaded file’scontainers/tasks/config_variables, and a TOML file’sservices, merged into oneConfig(see how included files combine).Includes are walked breadth-first, so every entry in the root file is reached before any included file’s own, and each file is loaded exactly once however many entries name it. A
type: gitentry clones its repository into~/.ratect/inclfirst (ratect-core/src/git_include.rs), and everything reached through one is confined to that clone and may do only what the entry granted it — see What a bundle may do for the rules, andCONTEXT.mdfor what bundle, grant and boundary each denote.It then checks the result — references, field combinations, and the shape of every value it can judge without the machine — applies
extends(native only), and returns aLoadedProject. No expression is evaluated: a field that may hold one is judged here only when it holds a literal, so a container reading a variable this machine doesn’t have stops nothing that doesn’t use it. TheLoadedProjectkeeps what evaluation needs: the directory each container was declared in, the clone a Git-included container must keep its host paths within, and which container in anextendschain supplied each path-bearing field. Listing tasks needs nothing more. -
LoadedProject::evaluate: given the containers and tasks a caller needs, and the--config-var/--config-vars-fileoverrides it parsed:-
Evaluates expressions (
$VAR,${VAR:-default},<name,<{name}, plus the built-inbatect.project_directory) in every field that takes one:environmentvalues (container, taskrun, and taskcustomise.<container>),localvolume mount host paths (in a Batect-format file, only the object form’s),build_directory,build_args, abuild_secretsentry’spath, abuild_sshentry’spaths, and —ratect.tomlonly —imageandidentity.home. Acachemount’sname/containerare plain strings, matching Batect: nothing to evaluate (see Cache volumes). A value that can’t be evaluated is an error naming the container or task, the field and the expression. -
Host path resolution: after evaluating a host path, if the result is relative, it’s resolved to an absolute path relative to the directory of the file that declared the value — the container’s own, or for an inherited field the ancestor’s that supplied it; the root config’s directory when there’s no
includeinvolved — not the current working directory. Done in this order because an expression can itself resolve to an absolute path, which mustn’t be treated as a relative fragment.batect.project_directoryitself always resolves to the root config’s directory regardless of which file a container came from. Acachemount’s Docker volume name/host directory is resolved later instead (ratect-core/src/cache.rs, viaengine.rs’sresolve_volumes), once--cache-typeand the project’s own cache key are known — neither available at this stage.The resolved path is then checked against the container’s Git boundary, if it has one: a container that came from a Git-included file may only reach inside its own clone or your project directory, unless that include was granted
allow_host_paths. Checked twice: once lexically, with both the check and the path normalized first, sincePath::starts_withdoes not interpret..; then against the real locations, with symlinks resolved as far as the path exists, since a bundle can commit one inside its own clone. A literal path gets the same check at load.
The engine evaluates each task as it reaches it — see step 3 of the task engine below.
See the configuration reference for the full expression syntax, precedence, and error rules.
-
3. Task engine (ratect-core/src/engine.rs)
TaskEngine::run_task(name) first walks the task’s whole prerequisite order —
wildcards expanded, each task once — without running anything, so a prerequisite
naming no task, or a cycle among them, fails the run before any task starts, as in
Batect. Then it runs a recursive async function. The order of its five steps is the
part worth knowing here; for what each one does in detail, read
engine.rs’s own module comment (cargo doc --open -p ratect-core), which is
where that lives and stays current.
- Already executed? If this task has already run successfully in this invocation, return immediately. This is what makes shared prerequisites run only once.
- Cycle detection: a task already in the middle of being run — an ancestor of itself in the current call stack — errors immediately rather than recursing forever. A backstop: the walk above has already refused every cycle.
- Run prerequisites, each through the same recursive function, before the
task’s own container step. They run with
top_level: false, unlike the task actually named on the command line, and with no-- ARGS. The flag keeps--skip-prerequisitesto the named task, and leaves a prerequisite’s resources out of--no-cleanup-after-success. It plays no part in interactive eligibility: every task’s own container is eligible, however deeply nested, as in Batect — see Interactive Mode. The task is then evaluated, before any Docker work of its own: every container in its graph, itsrun.environmentand itscustomiseenvironments go throughLoadedProject::evaluate, and the rest of the task reads only those values. A container no task in the run uses is never evaluated. Its container graph is built then too, and a cycle in it fails the task before it starts — no network is created, as in Batect. A task with norunof its own stops here and succeeds — it exists purely to chain prerequisites (see config reference), matching Batect’s ownTaskRunner. - Create the task’s network, then pull or build every image and create every
container in the task’s container graph on it — the task’s own included — as
soon as each one’s image is ready, and start each dependency once every
container it depends on is ready, before the task’s own container, so it can
reach them by name. The
graph is the container’s own
dependenciesunioned with the task’s, resolved recursively, with anycustomiseoverrides applied to whichever container they target at whatever depth. Every task execution gets its own network — a task’s container is never left on Docker’s shared default bridge — and it is torn down afterwards. With--use-networkan existing network is validated and reused instead, and never removed, since Ratect didn’t create it. See the task lifecycle for the step-by-step and diagrams. - Resolve and run the image.
resolve_imageturns a container’simageorbuild_directoryinto something runnable — pulling (perimage_pull_policy) or building, or erroring if neither is set — and is used identically for the task’s own container and for dependencies. The container then runs with the task’scommand, created on the task’s network (unless its ownnetwork_modesays otherwise), its environment layered as Environment precedence states. Everything else on the container — ports, hostnames, working directory, entrypoint, capabilities, devices, and the rest — is assembled bycontainer_spec.rsfrom the config and handed todocker.rsas plain values; the config reference is the list of what those fields mean, and which accept a task-levelrunoverride.
The “run once”, “pull once” and “build once” guarantees are in-memory and scoped to
a single invocation — nothing persists between runs, so a build_directory
container is rebuilt every time. Pulls and builds are memoized as once-cells holding
their outcome rather than plain sets, so two containers resolving the same image under the same
pull policy share one in-flight operation instead of racing. Dependency readiness, by contrast, is scoped
to a single task execution and discarded when it finishes.
Concurrency follows Batect’s in outline: prerequisites run sequentially, one to
completion after another, even when independent — while one task’s startup is
concurrent. Every container’s image — each dependency’s and the task’s own —
is pulled or built at once, the moment the task’s network is ready, and each
container is created as soon as its own image is (and, under
network_mode = "container:<name>", its target has been created), so a pull, build or create
that fails ends the task as soon as it fails — not once every dependency is
ready, by which time their setup commands have run. Starting is what a
container’s own dependencies gate: independent branches of the graph start
and health-wait at the same time, and a container — already created — starts
once every container it depends on has passed its readiness gate (see decision
0019).
Cleanup is concurrent the same way, in reverse: a container is stopped once every
container depending on it has been, and every container ready to stop is stopped at
once, so independent dependencies wait out their grace periods together.
The task’s network is created before any of that
starts, where Batect creates it alongside — see Differences from
Batect. Running independent prerequisites concurrently too is
a possible Rust-specific enhancement beyond Batect — tracked as
ratect#102 — and
Dependency Readiness has the detail.
Testability
The engine talks to Docker through a ContainerRuntime trait (defined in
ratect-core/src/docker.rs) rather than depending on the concrete Docker client
directly. This is what lets the engine’s prerequisite/cycle/dedup logic be
unit-tested with a fake implementation instead of a real Docker daemon.
4. Docker integration (ratect-core/src/docker.rs)
DockerClient wraps bollard and implements
ContainerRuntime. What each method is for:
pull_imageandbuild_image: fetch or build the image a container needs, streaming the daemon’s progress to the output layer as events — what, if anything, those render as is the selected output style’s decision, notdocker.rs’s (see Logging vs. output).build_imagefirst packs the build directory into an in-memory tar, honouring.dockerignorevia thedockerignorecrate.create_container: creates a container — a dependency’s or the task’s own — ready to be started: Docker’s create, which attaches it to its network, then the user-mapping uploads. It hands the container’s id back the moment that is done (inside its error, if an upload failed after Docker’s create), and the engine registers it for cleanup there and then, so a container whose start later fails or is cut short by another dependency failing is still removed. For a container withidentity, the engine then edits the created container’s identity files, prepares its home and, on a rootful Linux daemon, takes its root-owned caches, and a failure there counts as a failed create. Its own step, separate from starting, because it waits for less: a container is created once its image and the network are ready (and anynetwork_mode = "container:<name>"target has been created), and started only once the containers it depends on are — see Dependency readiness.run_container: starts and streams the task’s own container until it exits. Three attach-and-start paths sit behind it — fully non-interactive, stdin-forwarding, and a real TTY with raw mode and live resize — chosen by whether the task is interactive-eligible and whether Ratect’s own stdin and stdout are terminals. All three attach to the container before Docker’s start and read its output from that attach, as Batect does, so nothing typed or printed early is lost and any log driver works. It does not remove the container: the engine’s cleanup stage removes everything a task created, its own container included, so--no-cleanup-*is interpreted in exactly one place.create_network/remove_network/network_exists: the per-task network, or a service instance’s (decisions/0026), plus the up-front validation that makes--use-networkfail with a clear error rather than an unrelated API failure later.start_background_container/stop_and_remove_container: the same, for a dependency, sidecar or service group’s container — started and left running alongside the task rather than waited on, so no taskcommandapplies; its output is shown only under-o all, read from an attach made before it starts.follow_container: the output of a service group’s container that anotherratect services upstarted, attached to after the fact, under-o all.wait_for_container_healthy/exec_in_container: the two steps of the dependency readiness gate. The first blocks on Docker’s own event stream, replayed from the beginning so a verdict that arrived before the stream opened still counts, and turns an unhealthy verdict into an error carrying the last health check’s exit code and output, when the container and daemon are still there to report them. The second runs onesetup_commandsentry in the running container and returns its exit code and output for the engine to judge.
Nothing here depends on config types: container_spec.rs converts config into a
plain ContainerSpec first, which is what the methods that create and start a container
take; the rest take its id and plain values.
The module’s own comment carries the gotchas — where each path calls Docker’s
start relative to attaching, why cleanup ownership is not to be split again, how
build_ssh paths are classified — and is the thing to read before changing any of
this.
Container creation/start/removal events are logged at debug level via tracing (see
below), as is each setup_commands exec’s raw output — which is why
Troubleshooting warns about pasting a debug
log anywhere.
5. Logging vs. output
Ratect keeps two channels deliberately separate — and output itself follows one rule: stdout is the result, stderr is everything said about producing it (decisions/0017).
- Output is what a user with
RUST_LOGunset would be worse off without, and doesn’t go throughtracing, apart from two terminal-resize failures that are logged instead. The result — a run’s task-container output, atasks listlisting — is stdout. Everything about the run is stderr: errors (Error:), warnings (Warning:), notices (the interrupt notice, what--no-cleanup*left in place), in every style includingquiet; and progress (“Running build…”, “Pulling alpine:3.18…”, “build finished with exit code 0 in 2.3s.”), the one class--output/-oshapes. Progress is the one place the binaries differ:ratectwrites it to stderr,ratect-compatto stdout, where Batect puts it — see Streams. Internally these lines are typed events (ratect-core/src/ui/):engine.rsanddocker.rspost task-execution milestones, and the three stderr classes, to an event sink instead of printing, and the selected output style decides what each renders as —fancy’s live per-container status block on an interactive terminal,simple’s append-only lines otherwise, no progress at all underquiet, orall’s per-container prefixed lines (the one style where even container output routes through the event sink, line-buffered, instead of streaming to stdout directly — the task container’s own lines still landing on stdout). Eachmainnames which stream its progress console is; nothing inside the loggers chooses. - Diagnostics are breadcrumbs — Docker API calls, what resolved to what,
a best-effort retry that then succeeded — via
tracing/tracing-subscriberon stderr, filtered byRUST_LOG(defaults toinfo;ratect-compat’s--log-filedefaults todebugfor Ratect’s own targets). A fatal error is never only one of these:main.rsprints it directly (Error: <message>), so it stays visible underRUST_LOG=offand-o quietalike — except for a run’s failure the run has already reported by another route (the task’s own non-zero exit, a signal or a closed stdout, or a failure to run the task once it had started or to clean up after it, which the engine reported as it happened), which gets no second line, and for a verb that printed its ownError:line for each thing it couldn’t do (ratect includes clean/refresh). A failedratect services upis a run, and reports as one.ratect-compatalso records every one atdebug, so--log-filesays why the run failed unlessRUST_LOGfilters that record out.
Colours (e.g. the exit code in the task summary line, the Error: marker) are,
by default, only emitted when the stream being written to is actually a
terminal — each stream decides for itself, tracing’s lines included — see
Colour for the controls that change that.
Filtering RUST_LOG
Scoping RUST_LOG to Ratect’s own targets (ratect_core, ratect_core::docker,
and ratect-compat’s ratect_compat) rather than every dependency’s is on
Troubleshooting, which owns it.
ratect CLI Reference
This documents the ratect binary — the forward-looking CLI, with its own
subcommand-based interface. For the compatibility binary, see the
ratect-compat CLI reference instead; the two are described
separately because they are deliberately different interfaces, not two spellings of
one (Two binaries, two formats says which to
pick). If you haven’t run a task yet, Getting Started runs a
first one end to end, and the worked examples show a real
project per language.
Configuration.
ratectreads its own native TOML configuration (ratect.tomlby default) — see decisions/0003 for why. Its full schema is theratect.tomlreference; it’s the same schema Configuration Reference documents forbatect.yml, re-spelled in TOML, withextendsin place of YAML anchors,identityin place ofrun_as_current_user, and native-only additions such asservices. Abatect.ymlis still readable by naming it with-f, so a project can migrate incrementally —ratect config converttranslates one automatically.
The native config format
The format itself — the TOML spelling of every field, extends, includes, and
the auto-loaded ratect.local.toml — is the ratect.toml
reference (the
file, local
overrides).
Commands
Grouped by purpose. Within a command, the sub-verbs follow their natural
workflow order (list before clean/refresh) rather than alphabetically.
ratect --help lists the commands in this same order — clap can’t render the
group headings there, so the order alone carries them.
Running tasks
| Command | What it does |
|---|---|
ratect run <task> [-- ARGS...] | Runs a task. Anything after -- is appended to the task command’s own arguments, or replaces the image’s default CMD when the task has no command. |
ratect tasks list | Lists the tasks this project defines. |
ratect services up <group> | Brings a service group up, or attaches to it if it already is, shows every member’s output, and takes it down once its exit condition is met — see services options. |
ratect services down <group> | Takes a service group down, whatever state its containers are in. |
ratect services list | Lists this project’s service groups that have containers or a network on the daemon, in any state. |
Managing resources
| Command | What it does |
|---|---|
ratect caches list | Lists the caches this project can see, project-scoped and shared, with the scope of each. |
ratect caches clean [NAME...] | Removes this project’s caches, or just the named ones — which may be shared. |
ratect includes list | Lists the cached Git includes shared by every project on this machine. |
ratect includes clean [--all] | Removes cached Git includes. |
ratect includes refresh | Re-clones them, picking up a ref that has moved. |
ratect resources list [--all] | Lists containers and networks left over from task runs that have ended. |
ratect resources clean [--all] | Removes them. |
Configuration & diagnostics
| Command | What it does |
|---|---|
ratect config validate | Checks the configuration loads and is problem-free, without a daemon — a CI-friendly gate. |
ratect config convert | Converts a batect.yml project (read unless -f names another file) into native .toml files, one per file. |
ratect doctor | Checks this project and this machine for problems, without running anything. |
Shell integration
| Command | What it does |
|---|---|
ratect completions <shell> | Prints a shell completion script (bash, zsh, fish, powershell, elvish) to stdout — see Shell completion. |
There is deliberately no ratect <task> shorthand. ratect-compat takes a task
name as a bare positional argument, which works only because it has no subcommands;
as ratect grows verbs, “is doctor a task or a command?” becomes a question the
interface can’t answer, so run is always explicit.
ratect run build
ratect run test -- --filter integration
ratect tasks list
ratect services up stack
ratect services list
ratect services down stack
ratect caches list
ratect caches clean gradle-cache
ratect includes list
ratect includes refresh
ratect resources list
ratect resources clean --older-than 1d
ratect config validate
ratect doctor
ratect completions zsh
Global options
These work with every command, before or after it — ratect -f custom.yml run build
and ratect run build -f custom.yml are the same invocation.
| Option | Default | Description |
|---|---|---|
-f, --config-file <PATH> | ratect.toml | The configuration file. Parsed by extension — .toml as the native format, .yml/.yaml as Batect-format YAML — so -f batect.yml keeps reading a Batect config while migrating — until it includes a .toml file, which needs a ratect_version only a ratect.toml root can declare. caches uses it only to locate the project directory — it never reads the contents. |
-o, --output <STYLE> | auto | fancy, simple, quiet or all; unset auto-selects fancy when stderr is an interactive console, simple otherwise. ratect’s own progress is on stderr in every style; stdout is the task’s own output — see Output Styles. |
--no-color | — | No color in Ratect’s own output (never affects a task’s own output), and simple becomes the auto-selected style — see Colour for how it combines with NO_COLOR/CLICOLOR_FORCE. |
Narrower options attach to the commands that actually use them, rather than being
global: a flag that’s accepted and then ignored reads as a promise. So the
config-variable options below belong to run, services up, config validate and doctor (the
commands that evaluate configuration), and the Docker connection options to run, services, caches, resources and doctor (the
ones that reach a daemon).
| Option | Applies to | Description |
|---|---|---|
--config-var <NAME=VALUE> | run, services up, config validate, doctor | Sets a config variable. Repeatable; wins over --config-vars-file and the variable’s own default. |
--config-vars-file <PATH> | run, services up, config validate, doctor | A file of config variable values (a flat NAME = VALUE map), parsed as TOML or YAML by extension. In a YAML file an unquoted number or boolean is read as written, as in ratect-compat. Defaults to an auto-discovered ratect.local.toml beside the config file, when present. |
A path given to -f or --config-vars-file has a leading ~ expanded to your home
directory, and . and .. removed before the path is used, so link/../ratect.toml
is ./ratect.toml whether or not link is a symlink. A leading .. stays. A
--config-vars-file you give must name a file: run refuses one that doesn’t before
reading the config, and config validate and doctor report it as a problem.
tasks list still accepts both, deprecated: they have no effect there, since listing
tasks evaluates no value, and passing either prints a warning saying so. They’ll be
removed in a later release.
Docker connection options
Taken by run, services, caches, resources and doctor — every command that reaches a
daemon — and never by tasks list, includes or config, which don’t. Which
daemon they reach, their DOCKER_* environment-variable defaults, and TLS with a
private certificate authority are on Connecting to
Docker, shared with ratect-compat.
| Option | Default | Description |
|---|---|---|
--docker-host <HOST> | DOCKER_HOST | Docker host to connect to — see Connecting to Docker. |
--docker-context <NAME> | DOCKER_CONTEXT, then the active context, unless a host is set | Docker CLI context to connect through — see Connecting to Docker. |
--docker-config <PATH> | DOCKER_CONFIG, then ~/.docker | Directory containing the Docker CLI’s own configuration — see Connecting to Docker. |
--docker-tls | — | Use TLS, identically to --docker-tls-verify — see Connecting to Docker. |
--docker-tls-verify | DOCKER_TLS_VERIFY | Use TLS, verifying the daemon’s certificate — see Connecting to Docker. |
--docker-cert-path <PATH> | DOCKER_CERT_PATH, then --docker-config/DOCKER_CONFIG, then ~/.docker | Directory containing any of ca.pem/cert.pem/key.pem — see Connecting to Docker. |
--docker-tls-ca-cert <PATH> | ca.pem in the certificate directory | The TLS CA certificate — see Connecting to Docker. |
--docker-tls-cert <PATH> | cert.pem in the certificate directory | The TLS client certificate — see Connecting to Docker. |
--docker-tls-key <PATH> | key.pem in the certificate directory | The TLS client key — see Connecting to Docker. |
run options
| Option | Default | Description |
|---|---|---|
--enable-buildkit | — | Force BuildKit for image builds, over the daemon’s default and DOCKER_BUILDKIT. Only run and services up build images, so only they take it. |
--use-network <NAME> | — | Reuse an existing Docker network for every task in this invocation instead of creating one per task — see ratect-compat’s description. |
--disable-ports | — | Never bind container ports on the host — see ratect-compat’s description. |
--no-proxy-vars | — | Don’t propagate proxy environment variables to image builds or containers, nor the proxies in Docker’s config.json to image builds — see Proxies. |
--skip-prerequisites | — | Run the task alone, without its prerequisites — see ratect-compat’s description. |
--override-image <CONTAINER=IMAGE> | — | Replace a container’s image. Repeatable — see ratect-compat’s description for what it replaces and when it errors, except that here an empty CONTAINER or IMAGE, or a CONTAINER given twice (the last one wins), isn’t rejected. |
--tag-image <CONTAINER=TAG> | — | Extra tag for an image a container builds. Repeatable — see ratect-compat’s description for when it errors, except that here an empty CONTAINER isn’t rejected. |
--no-cleanup, --no-cleanup-after-success, --no-cleanup-after-failure | — | Leave the task’s containers and network in place, running, after success (the task’s own container ran, whatever its exit code), after failure (something failed before it could), or both. After success that is the named task’s alone — its prerequisites are still cleaned up; after failure it is whichever task failed — see ratect-compat’s description. |
--max-parallelism <N> | unbounded | Cap concurrent image pulls/builds, container creates, dependency container starts and setup commands — see ratect-compat’s description. |
--cache-type <TYPE> | volume | volume or directory — see ratect-compat’s description and cache volumes. |
services options
services up <group> brings up the service
group’s
containers — each member, and whatever it depends on, started as a task’s
dependency is — then shows every member’s output on stderr, each line under its
container’s name as -o all shows it, until the group’s exit_condition
is met. It then takes the group down: every container stopped and removed, each
before what it depends on, then its network. It exits with the code the group’s exit_code_from selects,
and otherwise as a run does: 125 for Ratect’s own failure, 128 + the signal’s
number for a termination signal — see Exit codes. Its
output style is always all, the one that shows several containers’ output at once,
so -o with any other style is refused.
A group that is up belongs to no services up. It is the containers and network
carrying its labels, wherever they came from, so a second services up of the same
group never starts another copy. What it does depends on what it finds, the first of
these that applies deciding:
- A container only created or being removed, or a network with no container:
another
services uporservices downis bringing the group up or taking it down, so it waits, saying so once, and looks again. A group left that way — by aservices upkilled outright while bringing it up, or a take-down that couldn’t remove the network because a task was still running on it — is waited on until you end the wait and runservices down. - Its network gone, or no member up: it replaces the group, saying
Replacing service group 'stack': none of its members is up, or its network is gone., then takes it down and brings it up anew. - A member up — running, or paused or restarting: it attaches, saying
Service group 'stack' is already up; attaching to it. Ending this takes it down., and from then on shows the output of each of the group’s containers that was running as it attached, and waits for the exit condition. It starts nothing: a member that has already exited stays exited and doesn’t count towards the condition, thoughexit_code_from = { container = "<member>" }still takes the code that member left.
Two services up started at once end up the same way: one brings the group up and the
other waits for it, then attaches. Whichever ends:
- Its exit condition being met, or a termination signal, takes the group down, whoever
brought it up — Ctrl+C in an attached
services upstops a group another terminal started. Every otherservices upattached to it then sees its members stop, and ends, finishing whatever of the take-down is left. A further signal during the take-down force-removes what is left, as it does a task’s cleanup. - Killed outright (
kill -9, a terminal closed under it), aservices uptakes nothing down and can’t say so: the group stays up. The nextservices upattaches to it, saying so, andservices downends it.
The group is labelled with the directory of the configuration file up was given.
Every checkout of a project shares its project name, so services up in a second
checkout attaches to the group the first brought up, and warns that its containers’
bind mounts point into the first: Attaching to service group 'stack', which was brought up from /work/first, not /work/second: its containers' bind mounts point there.
A container already holding one of the group’s names, <project>..<group>..default..<container>, without the group’s labels stops services up with
the daemon’s error; Ratect neither attaches to it nor removes it. A container running
when services up attaches is used as it is, and a container the configuration has
gained since the group came up is not added: to apply a change to the group’s
configuration or images, take the group down first.
A task reaches a group that is up by running on its network, whose name is fixed:
ratect run <task> --use-network <project>..<group>..default runs the task’s
containers there, where each of the group’s containers answers to its name in the
configuration, and leaves the network alone afterwards.
services down <group> stops and removes the group’s containers and network, whatever
state they are in — running, stopped, or half brought up. While the configuration
declares the group, it stops them as up does, each before what it depends on and
with its own stop_signal and stop_grace_period; it needs only the project_name
the root configuration file sets, though, so it also takes down a group the
configuration no longer declares, or one whose configuration fails to load after the
root file parses, stopping its containers all at once. A group that isn’t up is no failure. services list shows each group that
has containers or a network on the daemon, whatever their state, with each container’s state and the directory it was brought up from; with
-o quiet, each group’s name alone.
resources never selects a service group’s containers or
network, whatever their state and whatever its options, and doctor doesn’t count
them as leftovers: services down is how a group ends.
| Option | Applies to | Description |
|---|---|---|
--config-var, --config-vars-file | up | As for run. |
| Docker connection options | up, down, list | See Docker connection options. |
--enable-buildkit | up | As for run. |
--cache-type <TYPE> | up | As for run: use the same type as the tasks sharing the group’s caches. |
caches options
--cache-type <volume|directory> (default volume) selects which storage to act on,
for both list and clean — a cache in one is invisible to the other, so this has to
match how the project runs its tasks. Under directory, this project’s caches are
host directories under <project>/.batect/caches/<name> and shared ones live at
~/.ratect/caches/<name>; with no home directory there are no shared ones. A
.batect/caches or .batect that is a symbolic link
is followed, as in Batect, so caches clean removes the cache directories wherever
it points — see Cache volumes.
caches never reads the configuration file. A cache belongs to the project
directory, so both commands work on a project whose configuration is broken or
missing entirely — which is exactly when clearing a cache tends to be what’s needed.
caches list prints each cache under the name a volumes entry gives it, not the
Docker volume it’s stored in; that name is what caches clean takes back. Under
-o quiet it’s one name per line and nothing else, for scripting — and it prints
this project’s caches only, unless --scope shared asks otherwise. What it
emits is exactly what a caches clean carrying the same flags would act on, so
the output can be piped straight back. Naming a cache that doesn’t
exist warns on stderr rather than passing silently, since the likeliest cause is
a typo. Under --cache-type directory, caches clean also warns when the project
has no .batect/caches directory, and names each entry there that it skips
because it is a symbolic link, which is never followed. caches clean reports
each cache as it is removed, so a removal that fails, which stops the clean,
leaves everything removed before it already reported above the error.
--scope <project|shared> restricts both commands to one kind of cache. A
shared cache is one every project on
the machine can use, so the listing keeps them apart — a shared cache is
not this project’s, and most of the ones shown will belong to other
projects. ratect caches list, captured on a terminal in examples/full-stack
after a run, while
ratect/tests/fixtures/shared-cache.toml’s
warm-cache task had created its shared cache:
Caches for this project:
- full-stack-npm-cache
Shared caches on this machine:
- shared-tools
Removing a shared cache always takes --scope shared — whether it is named
or not, and whether or not this project has a cache of the same name. A shared
cache holds storage every other project on the machine is using, so it is never
reached by an unqualified clean. ratect caches clean shared-tools, in the
same state:
Error: 'shared-tools' is a shared cache, used by every project on this machine. Re-run with '--scope shared' to remove it.
caches clean with no names therefore sweeps this project’s caches only.
Both scopes are read from storage, not from the configuration — a project cache
is found by its batect-cache-<key>- prefix, a shared one by
ratect-shared-cache-. That is what keeps these commands working on a project
whose configuration is broken. With --scope shared, they never read or create
the project’s key file, .batect/caches/key, since only a project cache is
named after it.
includes options
The Git include cache under ~/.ratect/incl — where a type: git
include is cloned and kept. With
no home directory there is no cache, and these find nothing.
ratect includes list, captured after
the one checked-in project with a Git include
had been loaded once into an otherwise empty cache:
1 cached Git include(s), 261.3 KiB on disk:
https://github.com/batect/hello-world-bundle.git at 0.12.0
261.3 KiB, last used 0 seconds ago
Unlike caches and resources, this cache is
global — one directory shared by every project on this machine, keyed by
(repo, ref). So there’s no project scoping, and clean reaches other projects’
includes as well as your own. That matters less than it sounds: everything here is
re-cloneable, so the worst case is a fetch.
A command that loads the project and has to clone an include for it prints
Cloning <repo> <ref>... on stderr first, and a blank line once the clone has
succeeded, in every style but quiet; includes refresh prints neither.
| Command | Description |
|---|---|
includes clean | Removes includes nothing has used for 30 days — the same threshold the automatic sweep applies, done on demand. |
includes clean --older-than <AGE> | A different threshold (30m, 2h, 7d). |
includes clean --all | Everything, regardless of age. |
includes refresh | Discards every cached clone and fetches it again. |
Every form of clean also removes the temporary directories left by clones that were
interrupted, once unchanged for 30 days: a more recent one may be a clone still in
progress. It removes what an interrupted clean, refresh or ratect-compat sweep
left at once: each moves a clone aside before deleting it, so one cut short never leaves
part of a clone for a later command to use. The next command that needs the include, or
includes refresh, clones it again; until then includes list may still show it, at 0
bytes.
clean and refresh carry on past an include they can’t remove, or clone again, and
then print an Error: on stderr for each, naming it and why, in every style, and
exit 1. A refresh whose clone fails leaves that include removed: the next command
that needs it clones it again.
clean names each leftover it removes by its path, after the includes, and counts the
leftovers on the total line only when it removed some. One it can’t remove is an
Error: and exit 1, as an include it can’t remove is. Here
ratect includes clean --all, run with HOME pointed at a scratch directory holding
three leftovers and no includes, one of them made unremovable by a read-only
subdirectory, removes two and prints an error for the third:
Removed /tmp/ratect-home/.ratect/incl/ec3564423a4b2c600611e288ce72ff419cc95541211b9381ce8b741e9aaad18b.tmp-736f329f71b94dbbb8b10d25461379b0, left by an interrupted clone.
Removed /tmp/ratect-home/.ratect/incl/ec3564423a4b2c600611e288ce72ff419cc95541211b9381ce8b741e9aaad18b.del-bbb06d33962b4e77a2971e0d462b9a1c, left by an interrupted removal.
Removed 0 cached Git include(s) and 2 leftover(s) of interrupted clones and removals.
Error: Could not clean /tmp/ratect-home/.ratect/incl/ec3564423a4b2c600611e288ce72ff419cc95541211b9381ce8b741e9aaad18b.tmp-fda60e700d77468b937c8fd7de2bc4cf, left by an interrupted clone: Permission denied (os error 13)
Under -o quiet only the error is printed. refresh leaves leftovers to clean.
Removing part of what an interrupted clone left counts as changing it, so once the cause
of an error like this is fixed, clean leaves the rest for another 30 days.
refresh is how you pick up a moved ref. A (repo, ref) pair is cloned once and
then never re-fetched, so if ref is a branch — or a tag someone re-pushed — your
project keeps using whatever it pointed at the first time, indefinitely. The automatic
sweep doesn’t help, because it removes entries that go unused, and an include you’re
actively using never becomes stale. Pinning ref to something immutable remains the
better answer; refresh is for when it isn’t.
Under -o quiet, list prints repo<TAB>ref<TAB>key per line and nothing else, where
key is the entry’s directory under ~/.ratect/incl. In every style, credentials in a
repo URL are shown as ***, as everywhere Ratect names one — and so is anything else
between its :// and last @, so https://host/a@b shows as https://***@b. Two entries
can then look alike only if their remotes differ in nothing but what was hidden, so in
the other styles an entry with part of its repo hidden is also named by the first 12
characters of its key: https://***@host/repo.git at v1 (key 45de9a2d81c0).
resources options
Containers and networks outlive a run when something goes wrong — a crash, a
kill -9, a --no-cleanup run, or a cleanup that failed. resources finds
them by the labels Ratect stamps on everything it creates, so they’re identifiable
however long ago they were made. ratect resources list, captured in
examples/full-stack after ratect run journey-test --no-cleanup-after-success:
6 left over from 1 previous run:
journey-test (7 seconds ago, run 11ac2452-81ed-412f-9dd5-3115c03563a9):
- container db (running)
- container cache (running)
- container app (running)
- container journey-test (exited)
- container ratect-health-check-app (exited)
- network ratect-full-stack-network-u4f9aa
Remove them with: ratect resources clean
Grouped by run, because that’s the unit a leftover belongs to: a run that was killed
outright, or crashed, leaves a network and every container it started, and they only
make sense together. (Ctrl+C, SIGTERM and SIGHUP aren’t those cases any more — each
cleans up after itself. SIGKILL can’t be trapped by anything, so it still is; see
Differences from Batect.)
A container is named as your configuration names it, not by the
<project>-<container>-<suffix> name it has in Docker — or, for the companion an
external_health_check runs, by
the ratect-health-check-<container> name Ratect gives it.
| Option | Applies to | Description |
|---|---|---|
--all | list, clean | Task runs Ratect can’t tell have ended, as well as those it can. Never a task run still going. |
--all-projects | list, clean | Every Ratect project’s leftovers, not just this one’s — never anything Ratect didn’t create. Also the way to use resources from outside a project directory, since the project scope is read from the configuration. |
--older-than <AGE> | list, clean | Only task runs older than AGE — 90s, 30m, 2h, 7d. A task run’s age is its oldest container’s or network’s. |
resources list is clean’s dry run. Both take the same options and select
identically, so whatever list shows you is exactly what clean with those same
options will remove — there’s no separate --dry-run because there’s nothing for it
to do differently.
A task run still going is never selected. A task run carries the same labels
whether it is going or left over, so each one holds a lock for as long as its process
drives it, cleanup included — both binaries take it — and resources reads it. The
kernel frees a lock when its process ends, however it ends, kill -9 included. Each
task run is one of three things:
| A task run is | When | Selected |
|---|---|---|
| ended | its lock is free, and was written on this machine since it last booted | by default |
| still going | its lock is held | never |
| unknown | Ratect can’t tell: there is no lock, it was written before a reboot or by another kernel (Ratect in a container sharing your home), or the lock can’t be read, as on some network filesystems | with --all |
A task run’s containers and network are selected or left out together, and one
selected by --all is listed as one Ratect can't tell it has ended. A task run is
unknown in particular when it was left by a Ratect too old to take the lock, so a
leftover from before an upgrade needs --all.
So does every leftover once the machine has rebooted, though it has certainly ended.
--older-than is the guard for those: resources clean --all --older-than 1d. On
any platform but Linux and macOS, Windows included, every task run is unknown.
When the selection leaves task runs out for their state, both commands say so on
stderr — Left out 2 task runs still going, and 1 task run Ratect can't tell has ended (pass --all to include it). A task run too young for --older-than isn’t
counted there. Containers and networks carrying Ratect’s project label but no task
run’s are neither selected nor counted, and nor is a service instance’s container
whose image or configured labels gave it a task run’s label.
--all here composes with --older-than, where includes clean’
--all conflicts with it: that one means every cached include, whatever its age,
while this one means every state a leftover can be in short of still going. Neither
is --all-projects, which widens the scope to every project, not the states.
Each lock is a file, ~/.ratect/runs/<run>.lock, named for the task run’s id. A task
run that cleaned up fully deletes its own, and clean deletes an ended task run’s once
it has removed everything of it. Nothing else does: one kept by a task run that, cut short, stopped waiting for
the daemon to answer a create (it may have made something), one left by a task run whose
leftovers went another way (docker rm, or ratect-compat alone), or from before a
reboot, stays, a few dozen bytes each. Delete them by hand only when nothing is running
and nothing is left over, on this daemon or any other the home directory is used with:
deleting a leftover’s file makes it unknown.
Under -o quiet, list prints resource ids one per line and nothing else, ready to
pipe into docker rm. Removal takes containers before networks, since a network
still holding an endpoint can’t be removed; a resource that fails to remove doesn’t
stop the rest, but clean then exits 1 with one Error: naming each refusal.
resources reads one thing from the configuration — the root file’s
project_name, to scope itself to this project — and nothing else in it, so neither
the ratect_version
check nor a value this machine can’t evaluate gets in the way. What to remove comes
from the labels alone.
Nothing without Ratect’s own labels is ever listed or removed, --all-projects
included: containers started by other tools, and Docker’s built-in bridge/host/
none networks, are invisible to both commands.
What this doesn’t cover: cache volumes/directories are caches’
territory, not resources’ — they’re a deliberate cache, not a leftover. Likewise the
Git include cache under ~/.ratect/incl is includes’ own
command. Built images are tagged <project>-<container> and reused/overwritten on
every run rather than tracked as a resource — also a deliberate cache. Tmpfs mounts
and exec instances die with their container, so there’s nothing left to find.
config
ratect config validate is doctor’s configuration half on its own — it loads the
config, evaluates every container and task against this machine, and runs the same
config-only checks (values this machine can’t evaluate, a
build_directory/Dockerfile a build can’t use, an absolute dockerfile,
floating image tags, dependencies with no
health_check, an entry given more than once in one dependencies or
prerequisites list, a mount above an identity home), exiting non-zero on a problem. It never touches Docker, so it’s the
gate to run in CI when all you want to know is “is the config valid?”, without a
daemon. It takes the same --config-var/--config-vars-file options as run, and
reads ratect.local.toml the same way, since evaluating the config can need them.
A config that doesn’t load stops at its first error.
ratect config convert migrates a Batect-format batect.yml project to the native
format. It reads batect.yml unless -f names another file: -f’s usual
ratect.toml default is the file it writes, not the one it reads.
ratect config convert # writes ratect.toml beside it, and a .toml beside each include
ratect config convert --stdout # prints instead, to review or pipe
It’s one-directional (ratect-compat stays YAML; the reverse would be lossy) and
converts each file the project owns beside itself: the root becomes ratect.toml,
and every local included file, at any depth, becomes a .toml with the same name in
its own directory (more/c.yml → more/c.toml ), with each include entry rewritten to
point at the converted file. Nothing is re-based — every value is copied exactly as
written — so a relative path in more/c.toml resolves against more/, exactly as it
did in more/c.yml (see Where relative paths resolve).
A Git include stays a Git include, its repo, ref, path and allow_host_paths
carried across: nothing from a bundle is copied out, and no file in one is converted.
A root batect.yml with no project_name converts to a ratect.toml naming the
project as ratect-compat does — after the root file’s directory — since ratect.toml
requires one.
Nothing is written if any converted file already exists — the error lists them all;
pass --force to overwrite them, or --stdout to print instead. With more than one
file, --stdout prints each document in order, the root first, each under a
# === … === banner naming its file (more/c.toml ).
The conversion preserves each file’s configuration, not formatting: YAML
anchors/aliases/merge keys are expanded inline and comments are dropped — so each
output carries a header and is a starting point to review, not a blind drop-in.
Before anything is written, every conversion is checked to round-trip losslessly back
to the same configuration, so each file encodes the configuration you started with —
and every way ratect runs that configuration differently is listed, as below.
A task’s own container has no readiness gate, so its health check — from
health_check or from its image’s own HEALTHCHECK — isn’t waited on, and its
setup_commands don’t run (see Dependency
Readiness). An image’s HEALTHCHECK
can’t be seen without the image, so check those yourself. An enabled
run_as_current_user becomes identity, which doesn’t replace the image’s identity
files, and applies --user and changes a cache volume’s owner only on a rootful Linux
daemon, and a disabled one is dropped
(what changes). Its
home_directory is used as written in a batect.yml but
evaluated as identity.home in
a ratect.toml, so one containing a $ or < expression changes value, and one holding
a .. is refused until that is changed. Likewise, a string-form
volumes entry’s host path is used as written in a batect.yml but evaluated in a
ratect.toml. A \ in either stays a backslash (foo\bar becomes
foo\\bar), since a batect.yml never reads one as an escape, so a $ or <
after one is still converted as an expression, and listed. One that would then
be no valid expression — img$, a $ with no name after it — can’t have meant
one, so convert escapes it
whole (img\$) and it keeps its value, unlisted. An image is always
escaped whole: a batect.yml refuses an expression there, so nothing in one
was meant as one. Two more concern a Git include. A pathless entry whose bundle also offers
a ratect-bundle.toml would have ratect load that file instead of the
batect-bundle.yml the batect.yml loaded, so convert sets its path to
batect-bundle.yml and says so; remove path to switch to the native file. And a
bundle declaring Git includes of its own is refused by ratect unless
allow_nested_git_includes is set on that entry (see Nested Git
includes) — a grant convert never writes for you.
config convert lists each place in the converted project where one of these
applies — per converted file, its include entries’ items first, then its
containers’ in order of container name — after converting, and again in that
file’s own header, so the list travels with the file. ratect -f batect.yml config convert --stdout, captured in
ratect/tests/fixtures/convert
— a project with something to check:
# Generated by `ratect config convert` from batect.yml.
# Review before use: comments were not carried over.
#
# Check before use:
# Task 'test' runs container 'app' as its own, so under ratect the container's 'setup_commands' don't run — a task's own container has no readiness gate (see https://github.com/or1can/ratect/blob/main/docs/dependency-readiness.md#the-tasks-own-container).
# Container 'app' has a volume host path '$HOME/.cache', which batect.yml uses as written but ratect evaluates as an expression — check what it resolves to under ratect.
ratect_version = "0.13.0"
project_name = "convert-fixture"
[containers.app]
image = "alpine:3.18.2"
[[containers.app.setup_commands]]
command = "./warm-cache.sh"
[[containers.app.volumes]]
container = "/cache"
local = "$HOME/.cache"
[tasks.test]
description = "Runs the tests"
[tasks.test.run]
command = "./run-tests.sh"
container = "app"
Check before using ratect.toml:
warning Task 'test' runs container 'app' as its own, so under ratect the container's 'setup_commands' don't run — a task's own container has no readiness gate (see https://github.com/or1can/ratect/blob/main/docs/dependency-readiness.md#the-tasks-own-container).
warning Container 'app' has a volume host path '$HOME/.cache', which batect.yml uses as written but ratect evaluates as an expression — check what it resolves to under ratect.
With --stdout, the documents are all that reaches stdout; each heading and its list
after it are on stderr. Without it, they follow the success message on stdout,
naming the file written. With nothing to check, neither the list nor the header
block appears. Either way the conversion succeeds and exits 0, and the list prints
whatever RUST_LOG is set to, under -o quiet too.
The result declares the converting binary’s own version as its
ratect_version. It writes
each volumes, ports and devices entry as an object, the only form the native
schema admits, whichever form batect.yml used.
doctor
Answers “why did that fail?”, or “will it?”, without running a task.
ratect doctor, captured in
ratect/tests/fixtures/doctor
— a project written to trip each warning and a problem — after
ratect run build --no-cleanup-after-success there:
Checking ratect.toml...
ok Docker daemon reachable (29.8.2)
ok Docker daemon class: desktop
warning 'batect' is a Batect wrapper script and still runs Batect, not Ratect — delete it and run ratect (or ratect-compat) from your PATH
ok ratect.toml loads (6 container(s), 2 task(s))
warning Container 'deploy': cannot evaluate 'environment.TOKEN' ('$DEPLOY_TOKEN'): Host environment variable 'DEPLOY_TOKEN' is not set, and no default was given (e.g. '${DEPLOY_TOKEN:-default}') — a run that reaches it fails on this machine
warning container 'database' uses a floating image tag — pin it, or the same configuration will run a different image later
warning dependency 'cache' has no health_check — unless its image defines one, it counts as ready the moment it starts
warning container 'app' gives 'cache' more than once in its 'dependencies' — it starts only once
problem container 'app': build_directory '/private/tmp/ratect/ratect/tests/fixtures/doctor/missing-dir' doesn't exist
warning container 'scratch' has identity.home '/work/me' under the writable bind mount at '/work' — a home that doesn't exist yet is created on the host, in that directory
warning 1 task run(s) left over from previous runs — see `ratect resources list`
11 check(s): 1 problem(s), 7 warning(s).
Error: 1 problem(s) found.
The Docker daemon class line says which kind of daemon this connection reached:
rootless or userns-remap when the daemon reports it, desktop when Ratect runs
on macOS or Windows and reaches it over a local socket, and rootful Linux
otherwise. A daemon reached over the network is classified by what it reports, so
it is never desktop. Docker Desktop on Linux is rootful Linux, deliberately:
only vendor-specific signals tell it from a native daemon
(why), and
identity treats it as one.
If the daemon answers but its class can’t be read, that is a warning.
The class also decides two warnings a run gives too, about containers in the
project, whichever task reaches them, leaving out a base with no image or build_directory, which
nothing can run:
identityon a userns-remap daemon. Every container user maps to a subordinate host uid, root included, so the container has only other users’ access to a bind mount the host user owns, and what it does write has a subordinate owner. That ownership has to be arranged on the host. Its home is still guaranteed.- A non-root
useron a rootless or userns-remap daemon. The container has only other users’ access to a bind mount the host user owns, so it usually can’t write there or read anything private. Auserof0orrootisn’t reported.
Neither stops a run, and a run reaching such a container warns about it too. doctor
can’t report the third thing a run warns about, an identity container whose image
runs it as a non-root user on either daemon: the image’s user isn’t in the
configuration, the image may not be local, and doctor doesn’t pull it. config validate reports none of these, since it doesn’t connect to a daemon.
On a rootful Linux daemon, doctor also warns about each writable bind mount of a
container that writes there as root, whose files may end up root-owned on the host,
and suggests identity, or
run_as_current_user for a container in a .yml file, which can’t set identity. That
is a container with no identity, no enabled run_as_current_user, and either no
user or a user of 0 or root. With no user it assumes root, since it doesn’t
pull the image to find out. It fires on Docker Desktop on Linux too, where the files
are in fact the host user’s, because that file sharing is what the class can’t see.
identity is still sound there. A mounted socket or single file isn’t reported, since
a write can’t change its owner, except from a daemon reached over the network, whose
paths aren’t on this machine to look at. It says nothing when you are root, since root-owned files are then yours. A run
doesn’t warn about this, and neither does config validate.
Over a local socket to a rootful Linux daemon, doctor also reads who owns each
writable bind mount’s host path, for a container that runs as you: one with identity,
or an enabled run_as_current_user. If another uid owns it, it warns that a write
there may be refused, as it can be for a directory an earlier run left
root-owned. “May”, since group or other permissions can still allow it, and on Docker
Desktop on Linux a bind mount looks like the container user’s own, so the write may
well succeed. A missing path isn’t reported, since a run tries to create it as you, and nor is
one whose owner can’t be read, or anything when you are root. A daemon reached over the network isn’t checked, because its mounts are on its
own filesystem, and neither is any other class, where the container doesn’t run as
your uid. It’s a warning, and config validate doesn’t report it.
A problem will fail a run — an unreachable daemon, a configuration that doesn’t
load, a build_directory or Dockerfile a build can’t use. A warning works but is
likely to bite: a floating image tag (latest, or no tag at all) means the same
configuration runs a different image next week, an absolute dockerfile only works
where the project is checked out at that path, and a dependency with no health_check counts as
ready the moment it starts unless its image defines one, which is where “connection
refused” on the first run comes from.
So is each value this machine can’t evaluate — an unset $VAR, a <var with no
value — naming its container or task, its field and the expression, as deploy’s
$DEPLOY_TOKEN above. Every one is reported, not only the first. It’s a warning
rather than a problem because a variable only CI sets is expected to be missing on
a laptop, and it fails only a run that reaches it:
ratect run build there never evaluates deploy. The same goes for a value that
evaluates but can’t be used — an expression-valued
identity.home that isn’t an absolute path, or a
Git-included container’s host path that evaluates to somewhere outside its
boundary. A container with such a value is left out of the checks that read its
values, so its image tag and build_directory aren’t judged until it evaluates.
When everything evaluates, doctor says so on its own ok line.
A dependencies or prerequisites list that gives the same entry twice is a warning,
as app’s cache above. Batect refuses such a file; Ratect loads it and starts
or runs the entry once, so the repeat is reported rather than refused. Entries are
compared as written: a wildcard prerequisite given twice is a repeat, but a wildcard
beside a task it matches is not.
A mount above a container’s
identity home
is reported for what it does to that home, which is created through the mount before
the container starts. The deepest mount strictly above the home decides, with a bind
mount or cache going over a tmpfs at the same path, and a mount at the home itself
supplies it, so that gets no finding whatever is above it:
| Deepest mount above the home | Finding |
|---|---|
tmpfs | Problem: the run fails, whether or not the home already exists |
Read-only bind mount or cache | Warning: the run fails unless the home already exists there |
| Writable bind mount | Warning: a missing home is created on the host, in that directory |
Writable cache | None |
A tmpfs higher up changes nothing, since a deeper mount goes on top of it when the
container starts. A cache under --cache-type=directory, a host directory, is judged
as a volume, since neither doctor nor config validate takes that flag. Only the
configuration’s mounts are read, so a VOLUME the image declares between a tmpfs and
the home gets the tmpfs’s problem, though the home is created in that volume and the
run works.
If you’re migrating from Batect, doctor also flags a leftover batect/batect.cmd
wrapper script. Those aren’t harmless: ./batect still downloads and runs the
unmaintained JVM binary, so you can think you’ve switched to Ratect while ./batect
quietly runs the old tool.
Delete the wrapper and run ratect (or ratect-compat, for strict Batect
compatibility) from your PATH. Batect’s committed wrapper was its installer — it
fetched the right JVM version on demand — whereas Ratect is an ordinary binary you
install once, so there’s nothing for a committed wrapper to do. (Don’t repoint the
wrapper at Ratect by symlinking it: a committed symlink is machine-specific and doesn’t
work for batect.cmd on Windows, and it still needs the binary on the PATH anyway.)
The one exception is a codebase with ./batect hardcoded across CI jobs, Makefiles and
docs that you can’t change all at once: there, replacing the wrapper with a one-line
transitional shim — exec ratect-compat "$@" — keeps those call sites working while you
migrate them (it still needs ratect-compat on the PATH). A wrapper that no longer
runs Batect isn’t flagged.
doctor exits non-zero if it found any problem, and zero for warnings alone, so
it works as a CI step. Under -o quiet it prints only warnings and problems.
The environment checks run even when the configuration itself won’t load —
“your config is broken and your daemon isn’t running” is more useful than fixing
one to discover the other. It also reports leftovers unprompted, since the whole
reason resources exists is that nobody thinks to look: a
warning counting the leftover task runs that have ended, which is what a bare resources clean removes, and another counting those Ratect can’t tell have ended, pointing at
resources list --all. A task run still going isn’t reported.
Shell completion
ratect completions <shell> prints a completion registration script to stdout
for bash, zsh, fish, powershell or elvish. Source it from your shell’s
startup file:
# bash — in ~/.bashrc
source <(ratect completions bash)
# zsh — in ~/.zshrc, *after* compinit has run (see the note below)
source <(ratect completions zsh)
# fish — in ~/.config/fish/config.fish
ratect completions fish | source
zsh needs its completion system initialized first. The zsh script ends with a
compdefcall, andcompdefonly exists oncecompinithas run — so thesourceline must come afterautoload -U compinit && compinitin your~/.zshrc(frameworks like oh-my-zsh already runcompinitfor you; just keep thesourceline after they load). Sourcing it in a bare shell that hasn’t runcompinitfails withcommand not found: compdef; runautoload -U compinit && compinitfirst to try it interactively. bash and fish need no such initialization.
It completes command and flag names, their fixed values (-o fancy|simple|…,
--cache-type volume|directory), file-path arguments, and — the part that earns
its keep on a task runner — task names: ratect run <TAB> lists the tasks
your config defines. That last one is dynamic: the installed script re-invokes
ratect at completion time to read the config, always without cloning, pulling,
or touching Docker, so a <TAB> is instant and safe.
Task completion honours an explicit -f, and follows the config’s includes —
local files, and Git includes that are already cached. It never clones or
pulls, so tasks from a Git include that hasn’t been fetched yet won’t appear
until the first real run caches it.
Built on an unstable API. Task-name completion uses clap’s
unstable-dynamicengine, so it may occasionally need a fix as that API settles. The static parts (commands, flags, values, paths) don’t depend on it.
Exit codes and diagnostics
Identical to ratect-compat’s: both binaries share one mapping, whose design is
decisions/0016. An invocation is on one of two paths,
and its exit code depends on which. ratect run is a run, even when its arguments
don’t parse, and so is ratect services up; every other verb isn’t. For a line that doesn’t parse, the subcommand
counts where it would be read as one — not after --, and not as another option’s
value — so ratect --bogus run test is a run. --help and --version exit 0 on
either path, once the arguments reach them.
ratect services up is a run too, whose exit code is the one its group’s exit_code_from
selects in place of the task’s own (see services
options); the rules below hold for it with that change.
A run exits with one of three things, answering one question: did the task’s own container run to an exit code of its own?
- It did: that exit code,
0included. A task’s own125,126or127passes through the same way, and a prerequisite that fails this way stops the chain. One exception: if every container exited0but Ratect then fails to clean up — a removal the daemon refused, or a cleanup stopped with Ctrl+C with something still to remove — the run exits125instead, and a prerequisite whose cleanup fails stops the chain there. A task’s own non-zero code is never overridden. A container or network that something else already removed, such as a dependencydocker rm -f’d mid-run, isn’t a cleanup failure, since nothing is left behind. - A termination signal ended it: 128 + that signal’s own number —
130for Ctrl+C (SIGINT),143forSIGTERM,129forSIGHUP. Any of the three abandons the run and then cleans up after it; a second one during that cleanup force-removes whatever is left, a Ctrl+C after that stops the cleanup, andratect resources listfinds whatever that leaves (forservices up,ratect services down <group>removes it instead). A signal that arrives only during the cleanup of a run that had already finished doesn’t change its exit code; one during a prerequisite’s cleanup ends the run before the next task starts; one while the run is still connecting to Docker ends it at once, with nothing yet to clean up. A run whose stdout reader goes away —ratect run test | head -n 1, onceheadhas its line — ends the same way, as thoughSIGPIPEhad ended it:141, after the same cleanup. A closed stderr never ends a run. - It never ran, or never finished, for any other reason:
125— an unknown or misused flag (ratect run --bogus,ratect -o bogus run test), a config file that isn’t there, a config that doesn’t load, an unknown task, an unreachable daemon, a failed pull or build, a dependency that never became ready. An unknown task’s error ends with how to list the tasks:(Run 'ratect tasks list' for a list of all tasks in this project, or 'ratect run --help' for help.).
Every other verb runs nothing, so it exits 0 when it succeeds; 1 when it fails
(config validate on a file that doesn’t parse, caches list with the daemon down,
doctor finding a problem); and 2 when it was invoked wrong — a flag that’s rejected
(ratect --bogus, ratect tasks list --bogus, a missing subcommand), or an option value
that fails its own check, such as a -f naming no file (ratect tasks list where there
is no ratect.toml) or a --docker-config naming no directory. doctor and config validate report a -f naming no file as a problem they found instead, and exit 1, as
doctor does a Docker directory that isn’t one; a flag rejected in their own arguments is still
2.
Every failure of Ratect’s own reaches stderr as Error: <message>, in every output style
including quiet, whatever RUST_LOG says. Two kinds of failed run print no Error:
line, because something else already reported them: a task’s own non-zero exit (rule 1 —
the code itself and, outside quiet, the finished with exit code N summary line), and
a run ended by a signal or a closed stdout (rule 2 — the notice saying so). A failure to
run a task that has started is reported when it happens, before cleanup; one before any
task starts, as ratect exits.
ratect-compat’s
section has each rule in full.
RUST_LOGcontrols Ratect’s own internal logging (defaultinfo, on stderr — see FilteringRUST_LOG). Unlikeratect-compatthere’s no--log-file; redirect stderr if you want one.- A crash (a genuine bug) exits
101and prints where to report it,ratect’s version and platform, and a reminder to re-run withRUST_BACKTRACE=1if it isn’t already set — seeratect-compat’s own note on this, which applies identically here.
Differences from ratect-compat
ratect-compat | ratect | |
|---|---|---|
| Run a task | ratect-compat <task> | ratect run <task> |
| List tasks | ratect-compat --list-tasks | ratect tasks list |
| Cache cleanup | --clean/--clean-cache | ratect caches clean [NAME...] |
| Listing caches | not available | ratect caches list |
| Finding leftovers from a previous run | not available | ratect resources list/clean |
| Bringing a group of containers up together | not available | ratect services up/down/list |
| Checking a project without running it | not available | ratect doctor |
| Managing the Git include cache | not available (only the automatic sweep) | ratect includes list/clean/refresh |
Batect-inert flags (--upgrade, --no-update-notification, --no-wrapper-cache-cleanup) | accepted, no effect | not offered |
--log-file | supported | not offered |
| Configuration | batect.yml | native ratect.toml (with extends); batect.yml still readable via -f |
ratect.toml Configuration Reference
This documents ratect.toml, the native configuration format the
ratect binary reads by default. It is the same
schema the Configuration Reference documents — the same
containers, tasks, and fields, with the same meanings — re-spelled in TOML, with
native additions (extends, ratect_version, and the other fields marked
(native only) under Field reference), its auto-discovered local
overrides file named ratect.local.toml rather than batect.local.yml, a few
YAML-isms removed (anchors, the compact string shorthands), and
identity in place of run_as_current_user.
Because the field semantics are identical across both formats, this reference
does not repeat them: for what a given field actually does, follow the links into
ratect-compat-config-reference.md. What’s covered here is the parts
that are genuinely different — the TOML spelling, and the native-only rules.
The native format is
ratect’s alone —ratect-compatreadsbatect.ymlonly (see Two binaries, two formats). To migrate an existingbatect.yml, runratect config convert.
The file
A ratect.toml describes a project’s containers and tasks. Named containers
and tasks map onto TOML tables, so a container build-env is [containers.build-env]
and a task build is [tasks.build]:
project_name = "my-app"
[containers.build-env]
image = "rust:1.90"
working_directory = "/code"
volumes = [{ local = ".", container = "/code" }]
environment = { CARGO_TERM_COLOR = "always" }
[tasks.build]
description = "Compile the project"
group = "Development"
run = { container = "build-env", command = "cargo build" }
project_name is the only top-level key the format requires, though a project
must also set ratect_version
or ratect refuses it. Unlike in a batect.yml loaded by ratect-compat,
project_name is never inferred from the directory name. It’s
taken from the root file only, and names the images the project builds and its
eu.orican.ratect.project label — see
Top level. ratect defaults -f to
ratect.toml; point it at a differently-named file, or a batect.yml, with
-f.
project_name, a container’s name, a task’s and a config variable’s follow the
same rules as in a batect.yml — see Project and container
names, Task
names and Config variable
names — and the error
for one that breaks them gives the line and column of the name itself in a
.toml file (of its value, for project_name), and of the entry’s value in an
included .yml one.
This closely mirrors examples/rust/ratect.toml’s
own real build-env container and build task — same image, same command, same
task description/group — with an environment entry added here purely to
show the syntax; the real file doesn’t set one.
ratect_version: the version a project was written for
A top-level ratect_version records the Ratect version the project was
written for:
ratect_version = "0.13.0"
project_name = "my-app"
ratect checks it before reading anything else in the file, and refuses to
run the project in two cases:
- The project is newer than the binary. A project written for 0.13 most likely uses something 0.11 doesn’t know, so 0.11 says it needs 0.13 or later rather than failing on whichever field it meets first.
- A later release changed what a configuration means. Ratect keeps a list
of every change to what a
ratect.tomlmeans or accepts — theCHANGELOG.mdentries marked ratect.toml: under Breaking. If any came after the project’sratect_version,ratectlists them and stops; once you’ve reviewed them, setratect_versionto the version you’re running. An upgrade that crosses none of them is silent.
A refusal of the second kind also says, for each change, whether it touches
the project, to help with the review — it never replaces it, and the project
is refused either way. ratect run hello, captured in
ratect/tests/fixtures/written-for
— a project written for 0.11.0, run by 0.13.0:
Error: Refusing to load ratect.toml: This project was written for ratect 0.11.0, and ratect has changed what a configuration means since:
- ratect 0.12.0: a '\' in an expression escapes the character after it and is dropped, and a trailing '\' fails the load — none found
- ratect 0.12.0: every '$' or '<' in an expression starts a reference, so a malformed one ('$$', 'a < b', '${X:default}') fails the load, and an unbraced name ends at '.' or '-' (write '<{batect.project_directory}') — none found
- ratect 0.12.0: a task or config variable name Batect refuses fails the load: a task name is letters, digits, ':', '-', '.' and '_', starting and ending with a letter or digit; a config variable name is letters, digits, '-', '.' and '_', starting with a letter and not with 'batect' — doesn't apply: it loads under these rules
- ratect 0.12.0: 'project_name' and every container name must be a Docker image-name component, or the load fails: lowercase letters and digits, joined by a single '.', one or two '_', or any number of '-' — doesn't apply: it loads under these rules
- ratect 0.12.0: an included file that sets 'forbid_telemetry' to true fails the load; only the root file may — doesn't apply: it loads under these rules
- ratect 0.12.0: a string 'volumes' or 'devices' entry with an empty options segment ('a:b:') fails the load — doesn't apply: it loads under these rules
- ratect 0.12.0: a local include's 'path' whose first component is '~' is looked for in the home directory, not in a '~' directory beside the file declaring it — none found
- ratect 0.12.0: a 'command', 'entrypoint', 'run.command', 'run.entrypoint' or setup command that can't be split into arguments (an unbalanced quote, a trailing '\') fails the load, even where no task runs it — doesn't apply: it loads under these rules
- ratect 0.12.0: a Git bundle is refused until the 'ratect_version' of the file its include names, or the include's 'reviewed_ratect_version', covers every change since; the root's 'ratect_version' doesn't cover a bundle — none found
- ratect 0.13.0: 'run_as_current_user' in a TOML file, or inherited through 'extends' from a YAML file and enabled, fails the load; use 'identity' instead — doesn't apply: it loads under these rules
- ratect 0.13.0: a home directory ('~' first in a local include's 'path' or a host path) is 'HOME' when it is set and absolute, and only otherwise the passwd entry's — none found
With this check set aside, the project loads under ratect 0.13.0's rules.
Review them (see CHANGELOG.md), then set 'ratect_version' to 0.13.0 to run it with this version.
Each change’s outcome depends on how it can be checked:
- A change that only makes something fail to load is checked by loading the project once more under the running version’s rules, with this check set aside. That load runs nothing, but fetches what a normal load does, Git bundles included. The refusal says once whether the project loads. If it does, each such change doesn’t apply; if it doesn’t, the refusal shows the error, and each such change may apply, since the error doesn’t say which one caused it.
- A change with a detector — one Ratect can recognise by looking, such
as the one refusing a Git bundle, or one to what an expression means — is
looked for in each of the project’s
.tomlfiles, read as plain TOML: none found, or found with the field and file it was found in. Its.ymlfiles aren’t looked in, so a project with one reads not known rather than none found. Nor is it none found when the project doesn’t load: which files there are isn’t known then, so only the root file is looked in, and a use there is still found. - A change nothing checks would say not checked. Every change so far has a check.
So for the project above, every change is ruled out: it loads, and declares
no Git include, no local include starting with ~, no host path starting with
~, a reference or an escape, and no expression a change reads differently. Once you’ve read the changes and agree, set
ratect_version to 0.13.0 and it loads.
ratect doctor and ratect config validate report a refusal the same way:
the refusal is a problem, each change a finding of its own — ok once it’s
ruled out, warning otherwise — and whether the project loads is ok, or a
problem naming the error.
Only the major and minor numbers are compared, and only the root file may set
it — an included file, or any YAML file, that does is rejected, except the
file a Git include names, which declares a bundle’s own. The root’s version
never covers a bundle: each is checked against its own, or against its include
entry’s reviewed_ratect_version — see The version a bundle was written
for. A project
without one counts as written for 0.3.0, the first release with ratect.toml,
so since 0.12.0 changed what a configuration means it’s refused until it sets
one; ratect config convert writes it for you.
A project whose root file is a batect.yml can’t set it at all — it keeps
Batect’s own shape. Its YAML files mean what they mean to Batect, which
nothing on the list changes, so it loads whatever the list says. A .toml file it includes
doesn’t, so a project that includes one counts as written for 0.3.0 too, and
is refused naming that file — once it has loaded, so a .toml include that
doesn’t load gets its own error first. Making the root a ratect.toml is the way to
declare a version for it: ratect config convert
converts its YAML files, but reads every file as YAML, so a local .toml
include has to be carried over by hand. ratect-compat rejects the field too, saying
that only a native ratect.toml can declare it.
extends: inheritance instead of YAML anchors
batect.yml factors out a shared base container with YAML anchors/aliases/merge
keys (&base/*base/<<:). Those are YAML syntax and don’t exist in TOML, so
ratect.toml replaces them with an explicit extends field:
[containers.base]
image = "rust:1.90"
environment = { CARGO_TERM_COLOR = "always" }
[containers.build-env]
extends = "base"
working_directory = "/code" # added
environment = { RUSTFLAGS = "-D warnings" } # replaces base's entirely
The rules:
- Single parent.
extendsnames exactly one container. - Shallow, per field. A field the child sets replaces the inherited one
outright — there is no deep-merging into nested maps. Above,
build-env’senvironmentis{ RUSTFLAGS }only;base’sCARGO_TERM_COLORis not merged in. This matches how<<:already behaves, and Cargo’s profileinherits. To keep an inherited map and add to it, restate the whole map. - Chains.
amay extendbwhich extendsc; each level fills what the one below left unset. A cycle (including a container extending itself) is an error. - Base-only containers need no
image. Only a container a task actually runs is required to have animageorbuild_directory, so abasethat exists purely to be extended can omit both. - Resolved after paths. Inheritance happens after relative paths are made
absolute, so an inherited
build_directoryor volume host path stays anchored to the file that declared it, not the child’s location — this matters when the parent came from an included file. - Clearing an inherited list. An empty list is a value like any other, so
setup_commands = []on a child clears the parent’s. That is how to reuse a container as a dependency without its setup steps. - Overriding a build with an image. Because inheritance is per-field with no
way to unset one, setting
imageon a child is how you override a parent’sbuild_directory:imagewins, and the inheritedbuild_directoryis simply unused.ratect-compatrejects a container with both fields (Batect does, and has noextendsthat would need the override) — this is a deliberate difference, not an oversight. A container used only as anextendsbase likewise needs neither field; the requirement is enforced when a task actually runs a container, so noabstractmarker is needed. - Containers only. Tasks do not
extends(compose task behaviour withprerequisites/dependenciesinstead).
One shape per list entry
volumes, ports, and devices take one object shape per entry — not the
compact "local:container" strings batect.yml also accepts. Use inline tables
for the terse cases and [[...]] array-of-tables blocks for longer ones; they’re
equivalent:
[containers.app]
image = "postgres:16"
# Inline tables — compact.
volumes = [
{ local = ".", container = "/code" },
{ local = "./secrets", container = "/run/secrets", options = "ro" },
]
ports = [{ local = 5432, container = 5432 }]
# Or the block form — readable when there are many fields.
[[containers.app.devices]]
local = "/dev/kvm"
container = "/dev/kvm"
- A
volumesentry is a host bind (local+container[+options]), a named cache volume ({ type = "cache", name = "...", container = "..." }), or a tmpfs mount ({ type = "tmpfs", container = "...", options = "..." }). - A
portsentry is{ local, container }[+protocol], with port ranges written as"6000-6010"— see Port mappings. - A
devicesentry is{ local, container }[+options].
The parser itself still accepts the string forms (which is what lets a
.yml include keep using them), and so does
config validate, without a warning; the native schema
and the docs treat the object form as canonical.
Config variables and expressions
Config variables are declared under [config_variables] and referenced with the
same <name / <{name} expression syntax as batect.yml — the syntax is
values inside strings, so it carries across verbatim. Which fields resolve
one is not identical: this format also resolves them in image, which a
batect.yml refuses — see Expressions in image, and
note that the image line in the example below is exactly that case. Otherwise
see ConfigVariable and
Expressions.
[config_variables.tag]
default = "latest"
description = "The image tag to run."
[containers.app]
image = "myapp:<{tag}" # a config variable
environment = { HOME = "${HOME}" } # a host environment variable
Local overrides
A ratect.local.toml beside the config file is loaded automatically when
present (no flag), supplying config-variable values for the current
developer/machine — the native default for --config-vars-file:
# ratect.local.toml — gitignore this.
tag = "dev"
It holds values only, not configuration: a flat name = "value" map, nothing
else. Anything you want to vary locally should be a config variable the tracked
config interpolates, keeping what varies declared and visible rather than hidden
in an untracked file. Precedence, lowest to highest: a variable’s default, then
the config-vars file (ratect.local.toml, or whatever --config-vars-file
names), then --config-var on the command line.
Includes
include is an array of entries, each a local file or a Git bundle. Formats may
mix: each included file is parsed by its extension — .toml as native,
.yml/.yaml as Batect-format YAML — so a native project can still pull in an
existing batect.yml fragment or bundle unchanged.
include = [
{ path = "ci/tasks.toml" }, # local, native
{ path = "shared/legacy.yml" }, # local, still YAML
{ type = "git", repo = "https://example.com/bundle.git", ref = "v2" },
]
A type = "git" entry with no path discovers its bundle file by looking for
ratect-bundle.toml first, then batect-bundle.yml — so an unmigrated Batect
bundle keeps working, and a bundle author can ship both files to support ratect
and Batect at once. How included files combine, where their paths resolve
and what a bundle may do are on Includes; the shared
~/.ratect/incl cache is in the batect.yml
reference
(ratect includes manages it); why you’d
share a bundle across projects at all is Reusable Pipeline Building
Blocks.
An extends in a native file may inherit from a container defined in any
included file, including a YAML bundle — the container namespace is flat once
includes are merged.
Some top-level keys are root-only. An included file, in either format, fails
the load naming that file if it declares project_name or
ratect_version —
except a bundle’s entry file, which may declare its own — or
sets forbid_telemetry to true — a key with no effect, accepted so a file
written for Batect still loads, as in a batect.yml.
Setting forbid_telemetry to false in an included file is allowed.
Shared caches
A cache mount is private to the project by default: the storage carries the
project’s own key, so two projects declaring cargo-registry get two
different caches. scope = "shared" drops that key, so every project on the
machine naming it gets the same storage.
[[containers.build-env.volumes]]
type = "cache"
name = "cargo-registry"
container = "/usr/local/cargo/registry"
scope = "shared" # or "project", the default
[[containers.build-env.volumes]]
type = "cache"
name = "build-output"
container = "/build" # no scope: private to this project
This exists because the alternative is worse. A bundle that wants one Cargo
registry or npm cache across projects would otherwise have to spell it as a
host path (local = "~/.cache/cargo"), which means granting the bundle access
to your home directory — the thing
allow_host_paths exists to permit and
decisions/0004
would rather solve properly. A shared cache says the same thing directly,
grants no host filesystem access at all, and keeps the location under Ratect’s
control.
Where it is stored. A shared cache is the Docker volume
ratect-shared-cache-<name>, or the directory ~/.ratect/caches/<name> under
--cache-type=directory — beside ~/.ratect/incl, where Git includes are
cloned, because both belong to the machine rather than to any one project. With
no home directory the directory form is refused, naming the cache. A project
cache remains batect-cache-<project key>-<name>.
A name has one scope per project. Declaring cargo-registry as project
in one container and shared in another is rejected when the file loads: one
name would mean two different pieces of storage. Two containers naming the
same cache is the ordinary way to share it between them, and is unaffected.
Removing one takes naming it. ratect caches clean with no arguments
sweeps this project’s caches and never a shared one — discarding storage other
projects are still using should not be a side effect. See
the caches options.
Expressions in image
A container’s image takes expressions, so a
pipeline can choose its image per run without a flag:
[config_variables.tag]
default = "latest"
[containers.app]
image = "my-repo/my-image:<{tag}"
[containers.tools]
image = "my-repo/tools:${IMAGE_TAG:-latest}"
Both forms work: <{tag} reads a config_variables entry
(settable with --config-var tag=1.2.3), and ${IMAGE_TAG:-latest} reads the
host environment with a fallback. The same rules apply as everywhere else — an
unset host variable with no :-default is a hard error naming it, rather than a
silent empty string that would produce a puzzling image reference.
A container inheriting an image through extends gets the expression its
parent wrote, evaluated the same way, so it resolves to the same value.
Nothing is evaluated when the file loads, so ratect tasks list works
whatever this machine supplies. Running a task evaluates only the containers
that task uses, when the run reaches it — again like every other
expression-bearing field. So an unset variable with no :-default fails only
the tasks whose containers read it. The error names the container, the field
and the expression, so you are not left hunting for which one. A
malformed one, such as
img:${, is the exception: it is a mistake in the file, so the file fails to
load, located by its line and column.
Rejected in a batect.yml, rather than resolved or ignored. Batect has no
expression support in image, so a file using one would load here and fail
under batect itself — and unlike an exotic capability, a parameterised image
tag is something a pipeline would use on every run, so the lock-in would be
routine rather than incidental. ratect-compat users have --override-image,
which covers most of the same ground; what it can’t express is an in-config
default, which is what this adds.
The rejection is on what you wrote, not on what it would resolve to, and it
knows the difference between an expression and a literal $: alpine:3.18 and
repo/img:1.2.3 load exactly as before. An escaped
\$ is a literal $ here, as in any expression. A batect.yml’s image is no
expression at all, so a \ in it is kept as written; the rejection reads an
escape as the expression syntax does, so repo/\$x loads and repo/\\$x doesn’t.
Names follow the expression syntax
too, so repo/img:$5 is rejected, while repo/img$, a $ with no name after
it, is no expression and is used as written.
Nested Git includes
A Git include fetches configuration from a
repository and merges it into yours. That bundle can declare include entries
of its own — and in a batect.yml those may be further type: git entries,
naming any remote, with the same trust your own includes get. In ratect.toml
that is refused by default: you chose the bundle; you did not choose
whatever it decides to pull in next. Opt in per bundle by setting
allow_nested_git_includes on that bundle’s include entry:
[[include]]
type = "git"
repo = "https://github.com/my-org/infra-bundle.git"
ref = "1.2.3"
allow_nested_git_includes = true
The grant is one level deep, counts only in configuration you control, and
has to sit on the entry that reaches the bundle’s file first — the same rules
as allow_host_paths, stated once on Includes
along with the refusal you see without the grant.
A nested include’s clone failure is reported without git’s own message.
Whether a remote is unreachable, refusing connections, missing, or demanding
credentials is a readout on a network — and for a nested include the remote
was named by the bundle, not by you, so the answer is of more use to whoever
wrote it than to you. In CI, where the log is often visible to anyone who can
propose a change to that bundle, repeated attempts map an internal network one
include at a time. The failure is still reported and still names both
repositories; only the transport detail moves behind RUST_LOG=debug. An
include you declared keeps git’s message in full — it describes a remote
you wrote down, and hiding it would only make your own typo harder to find.
The field is rejected in any .yml rather than ignored, value and all, under
either binary: it is native-only, and a native-only field follows the file it
is written in (see Which fields a file may
use). Setting it to false in a
batect.yml would claim a restriction that format never applies.
reviewed_ratect_version is refused in a .yml the same way.
run_in: setup commands in another container
A setup_commands entry normally runs inside the container that declares it.
Sometimes the tooling isn’t there: seeding a database means running a client,
and a postgres:16 image is not where your migration tool lives. run_in
names another container to run the command in, while leaving when it runs
alone — it is still part of the declaring container’s readiness gate, so
nothing that depends on that container starts until the command has succeeded.
On a task’s own container, which has no readiness gate, it doesn’t run at all
(see Dependency Readiness).
[containers.db-seed-client]
image = "my-org/db-tools:latest"
# Stays alive, so there is a live process for the command to run alongside.
command = "sleep infinity"
[containers.db]
image = "postgres:16"
dependencies = ["db-seed-client"]
health_check = { command = "pg_isready -U postgres" }
setup_commands = [
{ command = "psql -h db -U postgres -f /seed/schema.sql", run_in = "db-seed-client" },
]
[containers.app]
image = "my-org/app:latest"
dependencies = ["db"]
app starts once db is healthy and the seeding command has exited 0 —
exactly as it would if that command ran inside db itself.
- The target must be one of the declaring container’s own
dependencies(or the declaring container itself, which is what leavingrun_inout means). Anything else is rejected when the file loads, naming the container you asked for. This is the rule that makes the ordering safe rather than merely likely: a dependency has already been through its own full readiness gate before the container declaring it even starts, so it is running when the command arrives. A sibling has no ordering edge to this container at all, and a container that depends on this one structurally cannot have started yet — either would be a race with no fix, so neither is offered. Adependenciesentry inherited viaextendscounts, since the check runs after inheritance resolves. A task’s owndependenciesdoes not, even for that task’s main container: it orders the target ahead of this container for one task only, and the same container used by another task would silently lose that ordering — so the dependency has to be declared on the container, where it holds everywhere. - The command runs with the target container’s environment, user and
working directory, not the declaring container’s — it is running over
there, so those are the ones that apply. That includes the fallback a
setup command with no
working_directoryof its own gets: the target’sworking_directory, not the declaring container’s. The entry’s ownworking_directorystill overrides. In the example above, that is why the command reaches the database over the network (-h db) rather than through a local socket. - The target must stay running. It is
docker exec, so there has to be a live container to exec into — hencesleep infinityabove. Arun_to_completiondependency has already exited by the time it counts as ready, so naming one is rejected when the file loads rather than failing mid-run.
run_to_completion: init containers
A dependency normally starts detached, waits for a health check (immediate if
none is configured), then runs its setup_commands — see Dependency
Readiness. run_to_completion replaces that whole
gate with a simpler one: the dependency runs, and is ready once it exits with
status 0 — a non-zero exit fails the task run the same way an unhealthy
dependency or a failing setup command does. Kubernetes-style
init-container behavior, expressed as a plain node in the existing dependency
graph rather than a separate concept:
[containers.migrate]
image = "my-repo/migrate:latest"
run_to_completion = true
[containers.app]
image = "my-repo/app:latest"
dependencies = ["migrate"]
- No health check, no
setup_commands. Neither concept applies once a dependency runs to completion — setting either alongsiderun_to_completionis rejected when the file loads. - Ordinary graph participation. A
run_to_completiondependency can depend on other dependencies (of either kind), other dependencies can depend on it, and it can be declared directly under a task’s owndependenciesor nested under another dependency’s — no special-casing either way. - Concurrent when independent. Two
run_to_completiondependencies for one container that don’t depend on each other run at the same time, gated purely by the graph, not a separate strictly-sequential list. - Inert on a task’s own container, exactly as
health_checkandsetup_commandsare. A task’s own container already always runs to completion by definition — that’s what running a task’s command means — so a container a task names viarun.containerruns as an ordinary task container whether or not it sets the flag. The same container still runs to completion as a gate when another task uses it as a dependency. (A task’s ownrunblock has no field to set it on at all.)
Not a substitute for prerequisites. A prerequisites entry runs
as a fully separate task execution — own network, own containers, own
cleanup — strictly sequential relative to whatever named it, whether or not it
ran concurrently with anything else. That isolation is the point when the two
runs genuinely shouldn’t share anything. run_to_completion solves a
different problem: staying inside one task’s own dependency graph, sharing
its network with siblings (a cache, a long-running app) that must keep
running while it finishes.
external_health_check: checking a container from outside it
A health_check runs inside the
container it checks, so it needs a shell and a tool (curl, wget,
pg_isready) to be present in that image. A distroless or scratch image has
neither, and the usual workaround is to add tooling that exists for no reason
but to be health-checked with. external_health_check checks such a container
from outside instead.
It is a separate field because it is a separate concept, not a second
spelling of health_check. health_check is Docker’s own HEALTHCHECK —
the daemon owns its schedule, its starting/healthy/unhealthy state and
its re-running for the container’s whole lifetime. This is closer to a
Kubernetes readiness check: an external observer asking “can this be used
yet?”, once, with no opinion about the container’s health afterwards. (Ratect
has no equivalent of a liveness check in either form.) So the external check
alone decides when the container is ready: if its image declares a
HEALTHCHECK of its own, Docker still runs it, but Ratect doesn’t wait on it.
[containers.api]
image = "my-repo/api:1.0.0" # scratch-based: no shell, no curl
[containers.api.external_health_check]
type = "http"
port = 8080
path = "/healthz"
[containers.app]
image = "my-repo/app:1.0.0"
dependencies = ["api"]
app now starts only once GET http://api:8080/healthz answers 200, with
nothing at all having run inside api.
Two kinds of check are supported:
type | Checks | Fields |
|---|---|---|
http | The response status of a request to path on port | port (required), path (defaults to /), expected_status (defaults to 200) |
tcp | That a connection to port is accepted | port (required) |
Both also take interval, retries and timeout, meaning exactly what they
mean on a health_check —
how long to wait between attempts, how many attempts to make before failing
the task, and how long one attempt may take. The difference is what an omitted
one does: a health_check inherits the image’s own value, and there is no
image to inherit from here, so Ratect’s own defaults apply (interval = "1s",
retries = 30, timeout = "5s"). The first attempt is made immediately
rather than after interval has elapsed. A port, timeout or retries of
zero is rejected when the file loads rather than taken literally — nothing
listens on port 0, zero attempts would never check at all, and the tools the
check is made with read a zero timeout as no timeout. So is an
expected_status that isn’t three digits, which no HTTP response can carry.
- Over the project’s own network, never a published port. The check
reaches the container by its container-config name — the same network alias
its siblings use — so
portis the port the container listens on, and nothing has to appear inports. Two isolated instances of one project (concurrent CI jobs on a single host) therefore never contend over a host port to check each other. - Reported as the container becoming healthy. The output says
api has become healthy.when the check passes — the same line ahealth_checkproduces, at the same point in the run, since both mean the container is ready to use; the check itself is still a readiness check, not Docker’s health check. A check that never passes fails it the same way too, naming the container you wrote:Container 'api' did not become healthy: last status 000 from http://api:8080/healthz after 30 attempt(s), wanted 200. The external check ran in container 'ratect-health-check-api' — --no-cleanup-after-failure keeps it for inspection. - Ratect runs the check from a companion container, which you don’t see.
Declaring one generates a container named
ratect-health-check-<container>runningcurlimages/curl(pinned by digest, not by tag — you did not write that reference, so it must not resolve to something different later), which loops the check and exits 0 or non-zero — an ordinaryrun_to_completiondependency, so the waiting happens in the dependency graph rather than anywhere new. It narrates nothing of its own in any output style: it is how the check runs, not something you declared. It always logs withjson-file, whatever the daemon’s default log driver, since a failure’s diagnosis is read back from its output. It is still a real container, soratect resourcesanddocker pssee it, and a failure names it so--no-cleanup-after-failureleaves you something to inspect. - The generated name is reserved. While
apihas an external check, anything in the project that declares or refers to a container calledratect-health-check-api— another container’sdependencies, a task’srun.containerordependencies— is rejected when the file loads, naming what referred to it. Nothing is silently replaced or quietly repurposed. - No
health_check, norun_to_completion, nosetup_commands. All three are rejected alongside it when the file loads. The first would be two answers to one question; the second has already exited by the time anything could connect to it; and the third has no ordering available to it — the companion is a sibling of the checked container rather than a gate on it, so a setup command would run against exactly the service the check is waiting for. Put such a step in a container of its own that depends on the checked one, where it waits for the check like anything else. - Inert on a task’s own container, exactly as
health_checkandsetup_commandsare — nothing waits on a task’s own container becoming ready, because running it is the task (see Dependency Readiness), so the same container can be one task’s main container and another task’s checked dependency.
Because the two are separate concepts, interval, retries and timeout do
not quite mean the same thing in both, despite the shared names — which is why
they are not one field under a type tag. Docker’s retries counts
consecutive failures before flipping to unhealthy, cushioned by a
start_period that has no meaning out here; this one counts attempts.
stop_signal/stop_grace_period: graceful shutdown
Cleanup stops every container the same way by default — Docker’s own
default signal (usually SIGTERM), then a fixed ~10-second timeout before
escalating to a forceful kill. That is fine for most containers, but not for
one where an abrupt stop can corrupt something, such as a database with data
shared between invocations. stop_signal and stop_grace_period — Docker
Compose’s own field names for the same concept — let a container opt into
different behavior:
[containers.database]
image = "postgres:16"
stop_signal = "SIGINT"
stop_grace_period = "30s"
- Purely additive. A container that sets neither field behaves exactly
as today — Docker’s own default signal and timeout, unchanged. Setting one
without the other only changes that half:
stop_signalalone still waits Docker’s own default timeout, andstop_grace_periodalone still sends Docker’s own default signal. - Only changes what a task’s own cleanup sends. The other place Ratect
stops a container —
ratect resources clean, which removes what an interrupted run left behind — finds its containers by a label scan, with no configuration to read, so it keeps Docker’s own default signal and timeout whatever a container asked for here. - Durations use Batect’s Go-style string format:
"2s","1m30s","0"— the same formathealth_check’sinterval/timeoutuse. Docker’s own stop timeout is whole seconds, so anything finer is rounded up to the next second:"500ms"waits one second, never less than asked for. - A further signal during cleanup never waits on
stop_grace_period. It only bounds the graceful stop that cleanup starts with; a second signal (Ctrl+C again, or a supervisor’s follow-upSIGTERM) force-removes whatever is left with no grace period at all, and a Ctrl+C after that abandons cleanup — see Differences from Batect.
ulimits: per-resource limits
A container can raise or lower the resource limits its processes run under —
Docker’s own --ulimit, per container:
[containers.build-env]
image = "rust:1.90"
ulimits = [
{ name = "nofile", soft = 1024, hard = 2048 },
{ name = "core", soft = 0 },
]
nameis one of the resourcesdocker run --ulimitdocuments, without itsRLIMIT_prefix:core,cpu,data,fsize,locks,memlock,msgqueue,nice,nofile,nproc,rss,rtprio,rttime,sigpending,stack. (Notas, which Docker documents as deprecated.) A name outside that list is rejected when the file loads, like an unknown capability — Docker’s API checks none of this itself, so the alternative is a container that is created happily and then fails to start, aswrong rlimit value: RLIMIT_<NAME>out of the container runtime.harddefaults tosoft. An entry that sets onlysoftsets both limits to that value, matchingdocker run --ulimit name=limit.-1means unlimited. A soft limit above the hard limit — or an unlimited soft limit under a finite hard one — is rejected when the file loads. That is the rule thedockerCLI enforces for--ulimit, though its documentation doesn’t state it; the daemon’s API doesn’t enforce it either, and a container that gets such a pair fails in the runtime witherror setting rlimit type 7: invalid argument, which names a number rather than the field you wrote.- Per container, and only that container. A dependency’s
ulimitsapply to the dependency; a task’s own container is unaffected by them, and there is no task-level or project-wide default. - Purely additive. A container that sets no
ulimitsis created exactly as before — whatever the daemon’s own defaults are.
Entries are objects, like every other native list entry — and objects only:
unlike volumes, ports and devices, this
field has no compact string form at all.
dns/dns_search/dns_options: name resolution
A container can set its own nameservers, search domains and resolv.conf
options — Docker’s own --dns, --dns-search and --dns-option, per
container:
[containers.build-env]
image = "rust:1.90"
dns = ["10.0.0.53"]
dns_search = ["corp.example.com"]
dns_options = ["ndots:2"]
- Each is a list of strings, and each is independent. Set any one, two or all three; one left unset keeps whatever the daemon would otherwise have chosen.
dnsentries are IP addresses (IPv4 or IPv6), checked when the file loads. Docker’s API rejects anything else too, but only once the container is being created, asinvalid JSON: ParseAddr(...), which names no field.- Containers still resolve each other by name. On the task’s own
network, Docker’s embedded resolver stays each container’s nameserver and
forwards to the
dnsservers for everything else — unlike mounting your own/etc/resolv.conf, which replaces it. - Fixed on the container’s own definition. Neither a task’s
runblock nor a dependency’scustomiseoverlay accepts these fields: DNS is a property of the environment a container runs in, not of which task happens to use it. A dependency’s settings apply to the dependency alone. - Purely additive. A container that sets none of the three is created exactly as before.
network_mode: leaving the task’s network
Every container normally joins the task’s own network — or --use-network’s
— reachable by its name. A container can leave it instead, with Docker’s own
--network modes:
[containers.database]
image = "postgres:16"
[containers.metrics-agent]
image = "otel/opentelemetry-collector:0.110.0"
dependencies = ["database"]
network_mode = "container:database"
hostshares the Docker host’s network namespace;nonegives the container only a loopback interface;container:<name>shares the network namespace of another container in this config — its interfaces, its hostname, its/etc/hostsandresolv.conf, and itslocalhost. Anything else is rejected when the file loads.- A
container:<name>target must be one of the container’s owndependencies, so it is already running when this one starts — the dependency graph stays the one thing that orders startup. This container is created once the target has been created (Docker needs the target’s id for that), and started once the target is ready. It may not be arun_to_completioncontainer, which has exited by then. The target may share another container’s network in turn, but a chain of them that leads back round on itself is rejected: nothing in it has a network of its own. - It applies to that container alone. Every other container in the task
joins the task’s network exactly as before, with or without
--use-network, and health checks andsetup_commandsgate readiness the same way in every mode — neither goes over the network. - Name-based reachability is lost. A container in any of the three
modes has no name on the task’s network, so a sibling can’t reach it as
<name>. Ratect doesn’t check whether anything tries to — withhost, a sibling would have to use the host’s own address instead, and withcontainer:<name>, the target’s name reaches both containers. - Containers sharing a namespace share its ports. Two services in them
can’t listen on the same port: Docker starts both containers, and the
second service’s own attempt to listen fails with
Address in use. What happens then is up to that service — most exit, which fails the run with that container’s exit code. Ratect can’t check this when the file loads, since nothing in the config says which ports a container listens on (portsonly says which are published). - Fields that need the task’s network are refused alongside it, when
the file loads:
ports(a task’srunorcustomiseones too),additional_hostnamesandexternal_health_checkin every mode, and withcontainer:<name>alsoadditional_hosts,dns,dns_searchanddns_options, which Docker refuses there. Withhostornonethey have nothing to apply to. Withcontainer:<name>they belong on the target instead, whose settings apply to both containers:portspublished on the target forward into the namespace the two share, so they reach a port either container listens on, and the target’s names andexternal_health_checkreach both the same way. If the target shares another container’s network in turn, the error names the container at the end of that chain, whose network they all share — and if that one useshostornoneitself,ports,additional_hostnamesandexternal_health_checkcan only be removed. - Fixed on the container’s own definition, like
dns: neither a task’srunblock nor acustomiseoverlay accepts it.
user/group/groups: running as a specific user
A container can say which user and groups it runs as. These are passthroughs: Ratect hands them to the runtime verbatim and synthesizes nothing.
[containers.build-env]
image = "rust:1.90"
user = "1000"
group = "20"
groups = ["docker", 999]
The nearest real project is
ratect/tests/fixtures/user.toml.
- Each value is a name or an id, written as a string or a bare integer, so
user = 1000anduser = "1000"are the same. An empty value, one containing a:and a negative integer are rejected when the file loads. userbecomes the container’s user, andgroupits primary group. Together they are the runtime’suser:group.groupwithoutuser, onceextendshas resolved the container, is rejected when the file loads.- Each field inherits on its own. A child that overrides only
userkeeps its parent’sgroup, and can’t remove it, souser = "root"under a parent withgroup = "staff"runs asroot:staff. - A base is judged like any other container, unlike the need for an
image: a base withgroupneeds auserof its own, even if every child sets one. groupsare supplementary groups, Docker’s--group-add, and need nouser: they add to whichever user the container runs as.- The runtime resolves names against the image’s own files. Ratect doesn’t
check them, so a user or group the image lacks fails the container’s start
with the runtime’s own error. An id needs no entry in the image, though with
none
whoamifails and$HOMEis/. - Ratect doesn’t prepare mounts for this user. A fresh
cachevolume stays root-owned, so a non-rootusercan’t write to it; on rootful Linux the same goes for a missing host directory, which the daemon creates as root. Create them owned by that user yourself: a fresh volume takes its owner from an image directory at the same path. If what you want is mounts prepared for you, useidentityinstead ofuser, which on a rootful Linux daemon does both. - Setup commands run as the same user. A setup command with
run_inruns as its target’s user instead. - A non-root
useron a rootless or userns-remap daemon gets a warning, naming the container and the field, when a run reaches it. It has only other users’ access to a bind mount the host user owns, so it usually can’t write there or read anything private. The run carries on, andratect doctorreports the same. - Fixed on the container’s own definition, like
dns: neither a task’srunblock nor acustomiseoverlay accepts them.
identity: your files, and the same $HOME everywhere
This field does two jobs. What a container writes through a bind mount is yours,
rather than root’s, except on a userns-remap daemon, or a rootless one under a
non-root image USER. And $HOME is what you said it is, whatever the image or the
machine, so cache mounts and mounted ssh or Git configuration can be declared once.
How it gets you the first depends on the daemon: on a rootful Linux daemon the
container runs as you, while Docker Desktop’s file sharing and a rootless daemon’s own
mapping of root to you deliver it without that.
Batect users will know this as
run_as_current_user.
File Ownership and the Home Directory shows the outcome on
each daemon; this section is the rules behind it.
[containers.as-you]
image = "alpine:3.24"
working_directory = "/code"
identity = { home = "/home/me" }
groups = ["users"]
volumes = [
{ local = ".", container = "/code" },
{ local = "ssh", container = "/home/me/.ssh", options = "ro" },
]
That container is from
examples/identity,
which that page walks through.
Both places programs look then agree: $HOME, which Git reads, and the running
user’s /etc/passwd entry, which ssh’s ~ reads. Who the running user is depends
on the daemon, and ratect doctor says which kind you have:
- On a rootful Linux daemon, which includes Docker Desktop on Linux, it is you: the container runs as your uid and gid. See On a rootful Linux daemon.
- On a local Docker Desktop, OrbStack or similar on macOS or Windows, and on
rootless and userns-remap daemons, it is the image’s own
USER, or root if it has none. Ratect doesn’t change it.
A run warns on the remapped daemons, naming the container and identity, and carries
on:
- On a userns-remap daemon, always: every container user maps to a subordinate
host uid, root included, so the container has only other users’ access to a bind
mount the host user owns, and what it does write has a subordinate owner. That
ownership has to be arranged on the host. The home is still guaranteed.
ratect doctorreports this too. - On a rootless or userns-remap daemon, when the image’s
USERisn’t root: it meets the same mapping as a non-rootuser, with only other users’ access to such a mount.doctordoesn’t report it, since it doesn’t pull the image.
These apply on every daemon:
homeis required, and is an absolute path with a leaf name and no..,:or control characters. It can hold an expression. A literal is judged when the file loads. An expression is judged when it is evaluated, before Docker touches the container, andratect config validateandratect doctorreport a bad one as a warning.- It can’t be combined with
userorgroup, or with a relativecachedestination, onceextendshas resolved the container. These are rejected when the file loads.groupsworks with it, and adds to the running user. - Only the running user’s entry changes, beside any lines added for
additional users. Every other line of the image’s
/etc/passwdstays as it was, and the file keeps its mode and owner. A name selects the entry with that name, and a uid the first entry with that uid. Only its home field changes, added to a line too short to have one. - A user with no entry, on the daemons where the image’s
USERruns: a numericUSERgets one, named with its uid (rootfor uid 0), with the numeric group fromUSERor else 0. A named group isn’t looked up: the process runs with it, but the entry and a created home have that user’s entry’s gid, or 0. An image with no/etc/passwdat all, such asscratch, is treated as having an empty one. A namedUSERthe image lacks gets nothing, and the runtime refuses to start the container. /etc/passwdisn’t edited through anything, nor is/etc/groupwhere it is edited. A symbolic link, a mount at that path or at/etc, or a file over 1 MiB fails the run, naming the container.HOMEis set in the container’s environment, over anyENV HOMEin the image. AHOMEinenvironmentwins, though the passwd entry still sayshome.- The home is only created where nothing exists: owned by the running user,
mode
0755, with any missing parent directories owned by root. An existing directory or symbolic link, a bind mount included, keeps its owner and mode even if the running user can’t write to it. A symbolic link isn’t followed, so one that is dangling or leads to a file leaves the home unusable. A file there fails the run, naming the container, and so does atmpfsas the deepest mount above the home, unless something is mounted at the home itself. Atmpfsis empty when the container starts, so it hides a home the image ships as much as a missing one, and where Docker made the home for a mount below it, that mount leaves a root-owned mount point in the home’s place. - A mount above the home is where it gets created, since that happens before the
container starts, whatever
tmpfsis further up. Under a writable bind mount, a missing home lands on the host, in that directory. Under a read-only mount, a missing home fails the run, naming the container.ratect doctorandratect config validatereport both. - A mount below the home is the exception. With a mount at
~/.sshor~/.cargo/registry, Docker creates the home and~/.cargoas root before Ratect can look at them. So each directory from the home down to a mount goes to the running user, keeping its mode, when it is owned by root, the running user isn’t root, and it isn’t at or inside another mount. A root-owned one the image shipped is handed over the same way, though not what is in it. - Fixed on the container’s own definition, like
dns: neither a task’srunblock nor acustomiseoverlay accepts it.
What this leaves as it is:
- Files baked into the image’s old home (
/root/.npmrc, from aRUNstep) stop being found via~. They are still at their old path. - An entrypoint that drops privileges (
postgres) runs as a user other than the running user, and that user keeps its own home. - A
working_directorybelow the home that isn’t a mount. Docker creates it and any missing parents, the home included, as root. A mount at it makes the home the running user’s, as above. - A
tmpfsathomehides the directory created there, so under a non-root running user its options have to allow that user to write. - No
cachemount changes owner except on a rootful Linux daemon. A fresh named volume is root-owned, so a non-root imageUSERcan’t write to one on the other daemons, even when the home above it is theirs. Fix that in the image: a fresh volume takes its owner and mode from an image directory at the same path. One owned by the image’sUSERis still another uid’s on a rootful Linux daemon, where you run instead, so a mode that lets anyone write works on every daemon. - A cache shared between uids or groups is yours to arrange.
chmodalone isn’t enough: under1777a second user can create files in it but not change the first user’s.
Coming from run_as_current_user
run_as_current_user and identity have the same goal: files you can edit and
delete, and a home that works. They differ in how they get there. Batect’s field does
one thing everywhere, while identity does what the daemon in front of it needs, so a
converted project may stop running as --user and still get the outcome.
A .yml keeps run_as_current_user, with Batect’s behaviour, including one a native
project includes, and ratect-compat always has it. A .toml file refuses it, enabled
or not, and so does a TOML container inheriting an enabled one from a .yml through
extends, which it can neither
override nor remove. ratect config convert turns an enabled
one into identity, its home_directory becoming home, drops a disabled one, and
lists each container it converted. What changes for such a container:
--userdepends on the daemon. On a rootful Linux daemon the container still runs as your uid and gid. On a local Docker Desktop, OrbStack or similar on macOS or Windows, and on rootless and userns-remap daemons, it runs as the image’s ownUSER. Desktop file sharing hands you what it writes anyway, and so does a rootless daemon when thatUSERis root. Otherwise nothing Ratect could apply would, so a run warns.- The image’s identity files aren’t replaced.
run_as_current_userswaps/etc/passwd,/etc/shadowand/etc/groupfor generated ones, which removes the users the image shipped, such asnodeorpostgres.identitychanges only the running user’s entry, and on rootful Linux adds what is missing. cachevolumes change owner only on rootful Linux. Elsewhere a fresh volume stays root-owned, so a non-root imageUSERcan’t write to it.homeis an expression, and holds no...home_directoryis used as written in a.yml.config convertcarries a$or<across as a reference, and lists it, and also lists a.., since the converted file is refused until that is changed.
Additional users
Some tools look up a user or group by name, and fail if the image lacks it. identity
can add those on every daemon, beside the image’s own users, which are all still there:
[containers.build-env]
image = "alpine:3.18.2"
identity = { home = "/home/me", additional_users = [{ name = "svc", uid = 1500, gid = 1600 }] }
groups = ["svc"]
The nearest real project is
ratect/tests/fixtures/identity.toml,
whose additional-users container is this one.
name,uidandgidare all required. Ratect picks no ids. A name starts with a letter or_, and holds only letters, digits,_,.and-. Neither id can be 0, and no two additional users can share a name, a uid or a gid. These are rejected when the file loads./etc/passwdgets one line each:svc:*:1500:1600::/nonexistent:/bin/sh. Nothing creates that home, and/etc/shadowisn’t touched.- A name or uid already in
/etc/passwdfails the run, naming the container and the values, with neither file written. That covers the image’s users and the running user, so on a rootful Linux daemon a declaration can clash on one machine and not on another, whose host user differs. Pick ids away from the ones your users have. /etc/groupgets an entry named after the user only if both that name and the gid are free, so sharing a gid with one of the image’s groups is fine, and that group is reused untouched. It is written before the container starts, sogroupscan name it. Where the gid was taken there is no entry of that name, so the runtime refuses to start a container whosegroupsnames it. Where only the name was taken,groupsfinds the existing group, at its own gid. On a rootful Linux daemon your own group counts as taken.- Ratect starts nothing as an additional user.
usercan’t be combined withidentity, so something in the container has to switch to it, as an entrypoint dropping privileges would. On the daemons where the image’sUSERruns, a namedUSERthe image lacks gets nothing even if listed here, and the runtime refuses to start the container. On a rootful Linux daemon the host user runs instead, so that image starts.
On a rootful Linux daemon
The container runs as your uid and gid, and setup commands exec as the same. If you are root, the same steps run as root. The image’s identity files are added to, never replaced:
/etc/passwd, your uid present (nodeat 1000 is the usual one): the first such entry keeps its name and gid, and only its home changes. Sowhoamisaysnode, and the process still has your gid, not the entry’s./etc/passwd, your uid absent: an entry is appended with your username, or with your uid’s digits if the image uses that name for another uid or your uid has no name on the host, password*, your gid,home, and shell/bin/sh./etc/group: an entry named after your group is appended only if both its gid and that name are free. If the gid exists, that entry is reused untouched. If only the name is taken, nothing is added, andidprints your gid with no name. If your gid has no name on the host, nothing is added either, soidnames it only if the image has an entry for it.- Host directories a mount needs are created as you before the container is, when the daemon is local: a missing bind mount source, and a mount point nested inside another host mount.
- A
cachenamed volume withrootas its owner becomes yours, keeping its mode, unless it is read-only (options = "ro") or you are root. That is what makes a fresh volume writable. Only the volume’s top directory changes: files already in it keep their owner, so a cache filled as root needs cleaning first. A volume another uid owns is left alone, so can’t be written to by you unless its mode allows. A directory cache gets nothing, since you created it. A shared cache follows the same rule.
The home follows the rules above, so home = "/root" isn’t writable by you unless
a mount below it hands it over. With a daemon on another machine (ssh://, tcp://), your uid and
gid are still the ones of the user running Ratect. Ratect creates no host directories
for it, on either machine, so the daemon creates a missing source as root. Windows has no uid to
adopt, so a Windows client reaching such a daemon fails the run, naming the container.
Docker Desktop on Linux counts as a rootful Linux daemon, so Ratect takes these steps
there, and ratect doctor calls it rootful Linux. That is deliberate: only
vendor-specific signals tell it from a native daemon
(why, and what was probed).
On the one version probed, with default file sharing, what a container wrote to a bind
mount stayed yours whichever user it ran as, so running as you may not be what delivers
that there. The same project on Docker Desktop on a Mac runs as the image’s USER.
services: bringing containers up together
A service group is a named set of the project’s containers that
ratect services up brings up together, shows
the output of, and takes down together — a stack to work against, such as an API
and its database, rather than a task that runs to an end. It names containers
already declared under containers, and adds nothing to them. An illustrative
project — none of the worked examples declares a group:
[containers.api]
image = "my-repo/api:latest"
dependencies = ["migrate"]
ports = [{ local = 8080, container = 8080 }]
[containers.db]
image = "postgres:16"
[containers.migrate]
image = "my-repo/migrate:latest"
dependencies = ["db"]
run_to_completion = true
[services.stack]
containers = ["api", "db"]
exit_condition = "any_stopped"
exit_code_from = { container = "api" }
| Field | Default | Meaning |
|---|---|---|
containers | required | The group’s members, by container name: at least one, each named once. |
exit_condition | "all_stopped" | When services up takes the group down on its own: "any_stopped" once any member has stopped, "all_stopped" once every member has. |
exit_code_from | "first_non_zero" | Where services up takes its exit code from: "first_non_zero", the first non-zero exit code a member stopped with of its own accord, or 0; "first_to_exit", the exit code of the member that stopped first; or { container = "<member>" }, that member’s exit code whenever it stopped — even when services up stopped it, as it does the rest once "any_stopped" is met. |
- A member starts as a task’s dependency does. Its own
dependenciesstart first, and its health check,setup_commandsandrun_to_completionapply — see Dependency Readiness. Each container is started once, however many members depend on it. - Only a member counts. A container a member depends on,
migrateabove, is brought up and taken down with the group, but its exit neither meets the exit condition nor gives the exit code. Withrun_to_completion, asmigratehas, it finishes before the member that depends on it starts, and its exit0is its readiness. A dependency that keeps running and then stops is reported as one that exited unexpectedly, as in a task. - Native only. A Batect-format (YAML) file can’t declare
services, included or not, andratect-compathas noservicesverb. - Any TOML file may declare a group. Groups from every file are merged, like tasks,
and a group name defined in two files fails the load. A group’s name follows the rule
a container’s does: lowercase letters and digits, joined by a single
., one or two_, or any number of-. - What the group’s containers are called. Each is created as
<project>..<group>..default..<container>on a network named<project>..<group>..default, the same names every time: that is what makes a secondservices upattach to the group, or wait for it, rather than start another copy.
Field reference
Every container and task field from ratect-compat-config-reference.md
applies, with the same meaning except where Where the semantics
differ says otherwise. Scalars, string maps
(environment, labels, build_args, …) and scalar lists
(capabilities_to_add, additional_hostnames, …) are a direct 1:1 spelling;
the only fields whose shape differs are the object-per-entry lists above.
The container fields, by area:
| Area | Fields | Semantics |
|---|---|---|
| Image | image, image_pull_policy, build_directory, dockerfile, build_target, build_args, build_secrets, build_ssh | Image building |
| Mounts | volumes (host / cache / tmpfs) | Volumes, caches, tmpfs. A cache also takes scope (native only) — the linked section describes project-keyed storage, which scope = "shared" deliberately does not use. |
| Runtime | command, entrypoint, working_directory, environment, enable_init_process, privileged, shm_size, capabilities_to_add, capabilities_to_drop, devices, labels, log_driver, log_options | Container |
| Graceful shutdown | stop_signal, stop_grace_period | above (native only) |
| Resource limits | ulimits | above (native only) |
| Name resolution | dns, dns_search, dns_options | above (native only) |
| Networking | ports, additional_hostnames, additional_hosts, dependencies | Ports, readiness |
| Network mode | network_mode | above (native only) |
| Readiness | health_check, setup_commands | Dependency Readiness. Both are inert on a task’s own container — see Where the semantics differ. A setup command also takes run_in (native only) |
| Init containers | run_to_completion | above (native only) |
| External checks | external_health_check | above (native only) |
| User | identity, user, group, groups | identity and user/group/groups (native only) |
| Inheritance | extends | above (native only) |
Where the semantics differ
Almost nothing: the two formats parse into the same model, so a field means
what ratect-compat-config-reference.md says it means. The
exceptions fall into four groups: places where extends gives a combination
a meaning it cannot have in a batect.yml, which has no inheritance; places
where this format is deliberately stricter, having no Batect
compatibility to preserve; two places where it does more than Batect,
resolving expressions in image and a string-form volumes entry’s host path —
the first of which batect.yml has to refuse rather than quietly accept, the
second of which it uses as written, as Batect does; and one where it
deliberately does less — a task’s own container has no
readiness gate.
Every row below about a container is decided by the format of the file
that declares it, not by the project — a container written in a .yml takes
the left-hand column even inside a native project (see Which fields a file
may use). The first three rows
follow the project instead: two are about an include entry rather than a
container, and the third about how a task runs its own container. An include
entry’s native-only fields, allow_nested_git_includes among them, still
follow the file: only a .toml file can set them.
| Behaviour | batect.yml (ratect-compat) | ratect.toml (ratect) |
|---|---|---|
A Git-included bundle declaring a type: git include of its own | Always allowed, matching Batect | Refused unless the bundle’s own include entry sets allow_nested_git_includes |
| A nested Git include failing to clone | Reports git’s own error | Reports that it failed, with the transport detail behind RUST_LOG=debug — see Nested Git includes |
A task’s own container’s health_check/setup_commands | Run alongside the main command, matching Batect; a failure while the main command is still running fails the task unless the command exits 0 within the next two seconds, and cancels it if it hasn’t exited by then; once it has exited 0, a failure is forgiven — the cost and the race that leaves are in known limitations | Inert: no health wait, no setup commands, and the task’s result is the main command’s alone — see Dependency Readiness |
An expression in image | Rejected when the file loads — Batect resolves nothing there; anything else, a \ included, is used as written | Resolved like any other expression, a \ escaping the character after it — see Expressions in image |
Setting run_as_current_user on a container | Runs it as the host’s own user, replacing the image’s identity files, matching Batect; enabled defaults to false, and a $ or < in home_directory is part of the path — see User mapping | Rejected when the file loads — use identity |
An expression in a string-form volumes entry’s host path ("$HOME/.m2:/root/.m2") | Used as written, matching Batect — a $ or < is part of a relative path; the object form’s local is still resolved | Resolved in either form |
A container with both image and build_directory | Rejected when the file loads, matching Batect | Allowed — image wins, and this is the only way to override a build_directory inherited from an extends parent, since inheritance is per-field with no way to unset one |
A container with neither image nor build_directory | Rejected when the file loads | Allowed — a container used only as an extends base needs neither; the requirement is enforced when a task actually runs a container, so no abstract marker is needed |
Setting stop_signal/stop_grace_period on a container | Rejected when the file loads — Batect has no equivalent field | Overrides Docker’s own default stop signal/timeout during cleanup — see above |
Setting ulimits on a container | Rejected when the file loads — Batect has no equivalent field | Sets that container’s own resource limits — see above |
Setting dns/dns_search/dns_options on a container | Rejected when the file loads — Batect has no equivalent field | Sets that container’s own name resolution — see above |
Setting network_mode on a container | Rejected when the file loads — Batect has no equivalent field | Takes that container off the task’s network — see above |
Setting user/group/groups on a container | Rejected when the file loads — Batect has no equivalent field | Sets the user and groups that container runs as — see above |
Setting identity on a container | Rejected when the file loads — Batect has no equivalent field | Gives that container a guaranteed home — see above |
image alongside a build-only field (build_args, build_target, dockerfile, build_secrets, build_ssh) | Rejected when the file loads | Allowed and ignored, for the same inheritance reason — a child overriding a build with an image still carries the parent’s build fields |
The last row is the one to watch: setting build_secrets or build_ssh on a
container that also has an image does nothing at all, and the native format
cannot tell you so without forbidding the override above. If a build field
looks like it is being ignored, check whether the container resolves to an
image.
Task fields: run (a TaskRun table —
container, command, entrypoint, environment, ports,
working_directory), prerequisites, dependencies, description, group,
and customise (see Task). A task needs at least one
of run or prerequisites.
[tasks.integration-test]
description = "Run the integration suite"
prerequisites = ["build"]
run = { container = "test-runner", command = "pytest tests/integration" }
[tasks.integration-test.run.environment]
DATABASE_URL = "postgres://db/test"
Editor support
Ratect ships a JSON schema for the native format,
schema/ratect-config.schema.json
(most of its fields generated from the config types, the native-only ones written
alongside them, and its value patterns checked against the parser by tests). Pointing a TOML-aware
editor extension at it — taplo / “Even Better TOML”
for VS Code, or JetBrains’ TOML support — gives field-name autocompletion, hover
documentation, and a red squiggle under a misspelled or unsupported field. It’s
the native counterpart of the batect.yml
schema: the same
schema, adjusted to the native shape (object-only list entries, no
run_as_current_user) and adding the native-only fields this page documents.
The simplest way to use it is a schema directive on the first line of your config, which taplo honors:
#:schema https://raw.githubusercontent.com/or1can/ratect/main/schema/ratect-config.schema.json
project_name = "my-project"
Structural validation only catches what the schema can express. For some of the
rules it can’t (a task needing run or prerequisites, an extends cycle),
ratect config validate checks a ratect.toml without a
Docker daemon, so it also works as a CI gate. A container with neither image
nor build_directory is still only reported when a task or services up runs it.
Differences from batect.yml, at a glance
batect.yml (ratect-compat) | ratect.toml (ratect) | |
|---|---|---|
| Format | YAML | TOML |
| Default file | batect.yml | ratect.toml |
| Reuse | anchors / aliases / merge keys | extends |
| Cross-project cache | — | scope = "shared" on a cache mount |
| Init containers | — | run_to_completion on a dependency |
| Health check from outside | — | external_health_check on a container |
| Graceful shutdown | — | stop_signal/stop_grace_period on a container |
| Resource limits | — | ulimits on a container |
| Name resolution | — | dns/dns_search/dns_options on a container |
| Network mode | always the task’s network | network_mode on a container |
| Named user and groups | — | user/group/groups on a container |
| Guaranteed home | — | identity on a container |
| Setup command target | always the declaring container | run_in on a setup command |
| Task’s own container’s readiness gate | health check, then setup commands | none — see Dependency Readiness |
| List entries | string shorthand or object | object (inline table or [[...]]) |
| Local overrides | batect.local.yml | ratect.local.toml |
| Git bundle default | batect-bundle.yml | ratect-bundle.toml, then batect-bundle.yml |
| Includes | YAML | TOML or YAML, by extension |
| Written-for version | — | ratect_version |
| Bring containers up together | — | services |
Most field meanings are unchanged; the spelling and the format-level rules
above are the bulk of the difference. The exceptions are the native-only
fields, the rows above with no batect.yml entry, and the handful of
behaviours in Where the semantics differ.
ratect-compat CLI Reference
ratect-compat [OPTIONS] [TASK_NAME] [-- ADDITIONAL_ARGS...]
This reflects the flags Ratect implements (ratect-compat/src/main.rs) —
every Batect CLI flag is supported, flag-for-flag, unless listed in
differences from Batect.
This is the ratect-compat binary, whose interface deliberately matches Batect’s.
The forward-looking ratect binary has its own, subcommand-based interface — see the
ratect CLI reference, and Two binaries, two
formats for which to pick.
Where options go
Options go before the task name, as in Batect. The first argument that isn’t an
option or an option’s value is the task name, and nothing after it is read as an
option. Only -- and arguments for the task may follow the task name: anything else,
such as ratect-compat build --disable-ports or ratect-compat build extra, is
refused before anything runs, with an error naming the task name and the first extra
argument. Under --list-tasks, --clean, --clean-cache or --upgrade, which
replace the task, whatever follows the options is ignored, so ratect-compat --list-tasks a b lists the tasks.
An option’s value that starts with - has to be given after =, as in
--use-network=-x: given as the next argument, it’s refused — see differences from
Batect.
A path given to -f, --config-vars-file or --log-file is resolved as Batect resolves it: a
leading ~ is your home directory, even where the shell leaves it alone
(--config-file=~/batect.yml), and . and .. are removed before the path is used,
so link/../batect.yml is ./batect.yml whether or not link is a symlink. A leading
.. stays. Before any command runs — --clean included — an -f you give must name
a file, and so must --config-vars-file; a --log-file must name a file or nothing
yet.
Options
Grouped by purpose, matching ratect-compat --help. The grouping is
presentational only — every flag parses the same regardless of the section it’s
listed under. A value placeholder here, such as <CONTAINER=IMAGE>, describes the
shape of the value; --help prints clap’s own instead, named after the option
(--override-image <OVERRIDE_IMAGE>).
| Flag | Short | Default | Description |
|---|---|---|---|
--config-file <PATH> | -f | batect.yml | Path to the configuration file to load. |
--list-tasks | -T | — | List all tasks defined in the config file, then exit. Doesn’t run anything. |
--help | -h | — | Print help (auto-generated by clap). |
--version | -V | — | Print the Ratect version. |
Configuration variables
| Flag | Short | Default | Description |
|---|---|---|---|
--config-var <NAME=VALUE> | — | — | Sets a config variable’s value; repeatable, once per NAME — a NAME given twice is rejected while the arguments are parsed. Takes precedence over --config-vars-file and the variable’s default. |
--config-vars-file <PATH> | — | batect.local.yml if it exists | A flat YAML file of config variable name: value pairs, in the same format as batect.yml itself. Every value is a string, as in Batect: an unquoted number or boolean is read as written (3.10 is 3.10, not 3.1), and a null or empty value is refused. Lower precedence than --config-var. When not given, defaults to batect.local.yml in the current directory if that file exists (an absent default file just means no overrides from a file, not an error); one that exists but isn’t a file fails every command, as in Batect. Read only when a task runs, as in Batect: every command checks only that a named file is a file, so nothing in it, nor a --config-var naming an undeclared variable, stops --list-tasks. |
Task execution
| Flag | Short | Default | Description |
|---|---|---|---|
--use-network <NAME> | — | — | Reuses an existing Docker network for every task in this invocation instead of creating (and removing) a fresh one per task. Errors clearly if the named network doesn’t exist. See task lifecycle. |
--disable-ports | — | — | Disables publishing of any container’s ports to the host, regardless of what’s configured. |
--no-proxy-vars | — | — | Don’t propagate proxy environment variables (http_proxy, https_proxy, ftp_proxy, no_proxy) to image builds or containers, nor the proxies in Docker’s config.json to image builds — see Proxies. |
--skip-prerequisites | — | — | Don’t run the named task’s own prerequisites. Only ever affects the task actually named on the command line — if that task is itself reached as someone else’s prerequisite in a later invocation, this flag has no bearing on that. |
--override-image <CONTAINER=IMAGE> | — | — | Overrides the image used by CONTAINER; repeatable. Replaces the container’s image/build_directory and image_pull_policy entirely — the override is always pulled under the default IfNotPresent policy, regardless of what the container itself configures. An empty CONTAINER or IMAGE, a CONTAINER given twice, or one also given to --tag-image, is rejected while the arguments are parsed. A CONTAINER the config doesn’t define fails the run once it reaches its first task with a run, before anything of that task starts; a run that reaches no such task, such as --skip-prerequisites on a task with only prerequisites, doesn’t check it. |
--tag-image <CONTAINER=TAG> | — | — | Tags the image built by CONTAINER with TAG, in addition to the default <project_name>-<container_name> tag; repeatable, and CONTAINER may be given more than once to apply multiple tags. Only valid for a container that actually builds an image — errors immediately if CONTAINER is configured to use a pulled image, and errors once the whole task (and its prerequisites) finishes if CONTAINER never actually ran. An empty CONTAINER or TAG, or a TAG that docker tag would refuse, such as _nonsense or one with uppercase in its repository name, is rejected while the arguments are parsed, before anything runs, and so is a CONTAINER also given to --override-image, before the config is loaded. |
--enable-buildkit | — | — | Use BuildKit for image builds, taking precedence over the DOCKER_BUILDKIT environment variable — see config reference. No --disable-buildkit counterpart; force the classic builder via DOCKER_BUILDKIT=0 instead. |
--max-parallelism <N> | — | unbounded | From 1 to 2147483647, as in Batect. Caps how many image pulls/builds, container creates, dependency container starts, and setup-command executions run concurrently across the whole invocation — a create and a start are separate capped steps, and no slot is held while a container waits for its dependencies. Health-check waits, the task’s own container’s run, and container stop/removal are never gated — see Differences from Batect. |
--cache-type <volume|directory> | — | BATECT_CACHE_TYPE, then volume | Storage mechanism for a cache volume mount (see Cache volumes): volume resolves it to a Docker named volume, directory to a host directory under <project_directory>/.batect/caches/<name>/. Has no effect on a config with no cache mounts — but does still select which storage --clean/--clean-cache act on. A BATECT_CACHE_TYPE that is neither volume nor directory, exactly, fails every command unless this flag is given. |
Cleanup after a run
| Flag | Short | Default | Description |
|---|---|---|---|
--no-cleanup | — | — | Equivalent to providing both --no-cleanup-after-failure and --no-cleanup-after-success. |
--no-cleanup-after-failure | — | — | If an infrastructure error occurs (a build/pull/health-check/setup-command failure, or anything else before the task’s own container gets to run — or the task container’s own health check or setup commands failing while its main command is still running, which cancels it), leave every container and network created for the task that failed in place instead of removing them, so the issue can be investigated — a prerequisite’s failure included. A task’s own container exiting non-zero is not “failure” for this purpose — see --no-cleanup-after-success. One divergence from Batect: containers are left genuinely running, not just present-but-stopped — see Differences from Batect. |
--no-cleanup-after-success | — | — | If the named task’s own container runs to completion — regardless of its exit code — leave every container and network created for that task in place instead of removing them. Prerequisites are still cleaned up after success, so only the named task’s resources are kept. Same divergence as --no-cleanup-after-failure: left genuinely running, not stopped-but-present. The exit code is still the task container’s own, where Batect’s is always 255 here — see Differences from Batect. |
Docker connection
Which daemon these reach, their DOCKER_* environment-variable defaults, and
TLS with a private certificate authority are on Connecting to
Docker, shared with ratect. Every invocation
accepts them; they’re used only when it actually connects. --docker-context
beside --docker-host or a TLS option is refused whether or not the invocation
connects, as in Batect.
| Flag | Short | Default | Description |
|---|---|---|---|
--docker-host <HOST> | — | DOCKER_HOST | Docker host to connect to — see Connecting to Docker. |
--docker-context <NAME> | — | DOCKER_CONTEXT, then the active context, unless a host is set | Docker CLI context to connect through — see Connecting to Docker. |
--docker-config <PATH> | — | DOCKER_CONFIG, then ~/.docker | Directory containing the Docker CLI’s own configuration — see Connecting to Docker. |
--docker-tls | — | — | Use TLS, identically to --docker-tls-verify — see Connecting to Docker. |
--docker-tls-verify | — | DOCKER_TLS_VERIFY | Use TLS, verifying the daemon’s certificate — see Connecting to Docker. |
--docker-cert-path <PATH> | — | DOCKER_CERT_PATH, then --docker-config/DOCKER_CONFIG, then ~/.docker | Directory containing any of ca.pem/cert.pem/key.pem — see Connecting to Docker. |
--docker-tls-ca-cert <PATH> | — | ca.pem in the certificate directory | The TLS CA certificate — see Connecting to Docker. |
--docker-tls-cert <PATH> | — | cert.pem in the certificate directory | The TLS client certificate — see Connecting to Docker. |
--docker-tls-key <PATH> | — | key.pem in the certificate directory | The TLS client key — see Connecting to Docker. |
Cache management
| Flag | Short | Default | Description |
|---|---|---|---|
--clean | — | — | Removes every one of this project’s own cache volumes/directories (per --cache-type or BATECT_CACHE_TYPE) and exits — doesn’t run anything, and never reads the config file, though a --config-file you give must name one. See Cache volumes. |
--clean-cache <NAME> | — | — | Removes just the named caches and exits, instead of every one of them. Takes a comma-separated list of names, each trimmed of surrounding whitespace, and is repeatable. Given together with --clean, the explicit name(s) win — --clean’s own “everything” behavior only applies when --clean-cache is never given at all. |
Output
| Flag | Short | Default | Description |
|---|---|---|---|
--output <STYLE> | -o | auto | fancy, simple, quiet or all; unset auto-selects fancy on an interactive console, simple otherwise — see Output Styles. |
--no-color | — | — | No color in Ratect’s own output (a task’s own output is never affected), and simple becomes the auto-selected style — see Colour for how it combines with NO_COLOR/CLICOLOR_FORCE. |
--log-file <PATH> | — | — | Writes Ratect’s own internal logs to this file, in addition to stderr: Ratect’s own at debug and other crates’ at info, ending with why the run failed when it did — unless RUST_LOG is set, in which case it governs the file too (see Environment variables). Bollard’s debug records, which carry each Docker request’s body, a container’s environment included, reach the file only when RUST_LOG asks for them. Plain text, one record per line, no ANSI color codes; stderr’s own output, colour included, is the same with or without it. |
Recognized, no effect
--upgrade, --no-update-notification, and --no-wrapper-cache-cleanup are accepted
but change nothing Ratect does — hidden from --help, since they’re not real Ratect features, just
recognized so an existing Batect invocation carrying one doesn’t hard-fail outright
(an unrecognized flag is a clap parse error that kills the entire invocation before
anything runs at all, including --list-tasks — unless it comes after --version or
--help, which act as soon as they’re reached). All three
only make sense for Batect’s own self-updating wrapper script, which Ratect — a single
native binary — doesn’t have and isn’t planning to grow. --upgrade specifically
prints a one-line notice to stderr and exits 0 rather than running silently, since a
user invoking it is likely expecting some visible response; reinstall or rebuild
Ratect to get a newer version instead. As in Batect, it’s still a command of its own:
it replaces a task name and --clean/--clean-cache, which then don’t run, while
--list-tasks replaces it, which then lists the tasks and prints no notice. The other two have no wrapper-cache/update
notification to disable in the first place, so they’re silently accepted with no
message at all.
Output styles
The four styles (fancy, simple, quiet, all), their captures and the
auto-selection rule are on Output Styles, shared with
ratect — the rendering is the same code in both binaries.
TLS with a private certificate authority
Why Ratect never skips certificate verification, and the worked example of
running your own CA instead, are on Connecting to
Docker,
shared with ratect.
Positional arguments
| Argument | Description |
|---|---|
TASK_NAME | The name of the task to run, as defined under tasks: in the config file. Required unless --list-tasks, --clean, --clean-cache or --upgrade is given — see Exit codes and error reporting. |
-- ADDITIONAL_ARGS... | Anything after a literal -- is appended as literal argv entries after the task’s own tokenized command — see below. Only applies to the task named on the command line, never to its prerequisites. |
Examples
# List tasks defined in ./batect.yml
ratect-compat --list-tasks
# Run a task from ./batect.yml
ratect-compat test
# Use a config file in a different location
ratect-compat -f ./ci/batect.yml build
# Pass extra arguments through to the task's command
ratect-compat test -- --verbose some/specific/file.rs
# Set a config variable referenced via `<name`/`<{name}` in `environment`
ratect-compat --config-var environment_name=staging test
# Load config variable values from a file instead
ratect-compat --config-vars-file ./ci/config-vars.yml test
Using ADDITIONAL_ARGS in a task command
run.command is tokenized into literal argv (quote/backslash-aware whitespace
splitting, no shell involved — matching Batect’s own tokenizer exactly), and anything
after -- is appended as further literal argv entries — no special syntax needed in
command itself to receive them:
tasks:
test:
run:
container: build-env
command: cargo test
Running ratect-compat test -- --nocapture here runs cargo test --nocapture inside the
container. Args are appended as literal argv entries (never concatenated into the
command string and re-parsed), so they’re safe even if they contain characters that
would be shell metacharacters elsewhere, like ;, &&, or backticks — Ratect never
passes command/ADDITIONAL_ARGS through a shell at all.
If neither the task’s run nor its container has a command, ADDITIONAL_ARGS
(when given) replace the image’s default CMD, as plain docker run <image> <args> does; the image’s ENTRYPOINT is kept. So for an image built with
ENTRYPOINT ["server"] and CMD ["--port", "80"], ratect-compat <task> -- --debug runs server --debug, not server --port 80 --debug. With
RUST_LOG=debug, the run logs the CMD the arguments replaced.
Exit codes and error reporting
An invocation is on one of two paths, and its exit code depends on which. A line is a
run unless it has one of the flags that replace a task: --list-tasks/-T,
--clean, --clean-cache or --upgrade. That holds whether or not a task is named and
whether or not the arguments parse; a flag counts only where it would be read as one, not
after -- or as another option’s value. --help and --version exit 0 on either path,
once the arguments reach them. The design is
decisions/0016.
A run — ratect-compat <task> — exits with one of three things, answering one question:
did the task’s own container run to an exit code of its own?
- It did: that exit code,
0included. Ratect waits for the container to exit and inspects its status — a task whose command isexit 42makesratect-compatitself exit42, matchingdocker run’s convention rather than collapsing every failure to one code. A task’s own125,126or127passes through the same way. A task that runs as a prerequisite and fails this way stops the rest of the chain immediately — no other prerequisites, and not the task that depended on it, will run — matching Batect’s documented behavior. One exception: if every container exited0but Ratect then fails to clean up — the daemon refuses to remove a container or the task network, or a Ctrl+C stops the cleanup with something still to remove — the run exits125instead, and a prerequisite that fails this way stops the chain there. A task’s own non-zero code is never overridden, and what--no-cleanup,--no-cleanup-after-successor--no-cleanup-after-failureleaves in place on purpose isn’t a cleanup failure — nor is a container or network that something else already removed, such as a dependencydocker rm -f’d mid-run, since nothing is left behind. - A termination signal ended it: 128 + that signal’s own number —
130for Ctrl+C (SIGINT),143forSIGTERM,129forSIGHUP— the shell’s own convention, so a script or CI job can tell a cancelled run apart from a failed one and tell what cancelled it, whatever cleanup does afterwards. All three abandon the run and then clean it up — see Differences from Batect for the full behavior, including what--no-cleanup-after-failuredoes to it and what a second signal does. A signal that arrives only during the cleanup of a run that had already finished ended nothing, so rule 1 applies: a passing run whose cleanup then completes still exits0. One that arrives during a prerequisite’s cleanup ends the run before the next task starts, and exits 128 + its number. One that arrives while the run is still connecting to Docker ends it at once, with nothing yet to clean up, however long the connection would have taken. A run whose stdout reader goes away —ratect-compat test | head -n 1, onceheadhas its line — ends the same way, as thoughSIGPIPEhad ended it: it exits141, after the same cleanup, with a notice on stderr saying the stdout closed. A closed stderr never ends a run. - It never ran, or never finished, for any other reason:
125—docker run’s own code for “thedockercommand itself failed”. An unknown or misused flag (ratect-compat --bogus build, or a bareratect-compat --bogus), no task name, a missing or malformed config file, a--config-vars-filethat isn’t a file, a task or container referenced by name that doesn’t exist, a dependency cycle, an unreachable daemon, an image pull or build that fails, a dependency that exits or never becomes ready, a setup command that fails, a--log-filethat can’t be opened: all125, one code, with the reason on stderr.
Everything other than a run — --list-tasks, --clean, --clean-cache, --upgrade —
runs nothing, so it exits 0 when it succeeds, 1 when it fails (a config that doesn’t
parse under --list-tasks, a --log-file that exists but can’t be opened), and 2 when
it was invoked wrong: a flag that’s rejected (ratect-compat --bogus --clean), or an
option value that fails its own check — a -f or --config-vars-file naming something
that doesn’t exist or isn’t a file, a batect.local.yml that isn’t a file, a BATECT_CACHE_TYPE that is no cache type, a --docker-config, --docker-cert-path,
DOCKER_CONFIG or DOCKER_CERT_PATH naming something that doesn’t exist or isn’t a
directory, --docker-context beside --docker-host or a TLS option, or a --log-file
in a directory that doesn’t exist, or that exists but isn’t a file.
Every failure of Ratect’s own is printed to stderr as Error: <message> (the marker in
bold red when stderr is a terminal) — deliberately not through
tracing::error!/RUST_LOG (which Ratect’s internal diagnostics go through — see
how it works): a fatal error is the reason the
process is about to exit non-zero, not an optional diagnostic, so it stays visible even
under RUST_LOG=off or a filter that excludes Ratect’s own target — including under
-o quiet. Two kinds of failed run print no Error: line,
because something else already reported them: a task’s own non-zero exit (rule 1 — the
exit code, and outside quiet the finished with exit code N summary line, say it,
and the container’s own output says why), and a run ended by a signal or a closed
stdout (rule 2 — the notice said so when it happened). A cleanup failure is reported once, as it
happens, by a line naming what was left behind and the docker command that removes
it. A failure to run a task that has started (an image that won’t pull or build, a
container that can’t be created or started, a dependency that never becomes ready) is
reported once too, when it happens — before the cleanup that follows it, as under
Batect; any failure before a task starts is printed as the process exits.
- Running with no task name, and none of
--list-tasks,--clean,--clean-cacheor--upgrade, is a command-line error, found before the config-variables file or the config is read — so a missing or broken-fstill reports the missing task name. It exits125, like any other usage error on a run, and the error, which points at--list-tasksand--help, is always on stderr, whateverRUST_LOGor-osays. So is-- ADDITIONAL_ARGSwith no task name before it. - A misspelled task name (whether given directly on the command line, or as a
prerequisitesentry) gets aDid you mean 'x'?suggestion appended to the error, for every existing task name within a Levenshtein edit distance of 3 — ported from Batect’s ownTaskSuggester/EditDistanceCalculator(confirmed by reading Batect’s source). Multiple equally-close matches are all suggested, e.g.Did you mean 'build' or 'bulid'?— Batect’s own implementation can silently drop one of two equally-close suggestions (its sorting comparator doubles as its de-duplication key), which Ratect’s deliberately doesn’t replicate. - A task named on the command line that doesn’t exist ends its error with how to list
the tasks, after any suggestion:
Task 'tst' not found. Did you mean 'test'? (Run 'ratect-compat --list-tasks' for a list of all tasks in this project, or 'ratect-compat --help' for help.), in every output style. A missingprerequisitesentry gets no such hint, as in Batect. - A crash (a genuine bug, not one of the above) exits
101, Rust’s own default for an unhandled panic.ratect-compatprints where to report it (https://github.com/or1can/ratect/issues/new), the binary’s version and platform, and — ifRUST_BACKTRACEisn’t already set — a reminder to re-run with it set, since a backtrace makes a much more useful report.
Environment variables
| Variable | Effect |
|---|---|
RUST_LOG | Controls log verbosity on stderr (error, warn, info [default], debug, trace) — and, if --log-file is given, in the file too, which logs Ratect’s own records at debug when it’s unset. See Filtering RUST_LOG for scoping it to Ratect’s own targets. Unlike Batect, Ratect always logs to stderr regardless of --log-file; Batect’s own default with no --log-file is silent. See Differences from Batect. |
BATECT_CACHE_TYPE | The default for --cache-type: volume or directory, exactly. Any other value, empty included, fails every command but --help and --version, unless --cache-type is given. |
DOCKER_HOST | The default for --docker-host — see Connecting to Docker. |
DOCKER_CONTEXT | The default for --docker-context — see Connecting to Docker. |
DOCKER_CONFIG | The default for --docker-config — see Connecting to Docker. |
DOCKER_CERT_PATH | The default for --docker-cert-path — see Connecting to Docker. |
DOCKER_TLS_VERIFY | The default for --docker-tls-verify — see Connecting to Docker. |
DOCKER_BUILDKIT | Forces the image builder on (1, yes or true) or off (0, no or false), in any case; empty counts as unset, and any other value fails the first build — see --enable-buildkit and config reference. |
NO_COLOR | If set, exactly the same effect as --no-color — see Colour. |
CLICOLOR_FORCE | Forces colored output even when the stream isn’t a terminal, unless --no-color/NO_COLOR is set — see Colour. |
Ratect supports interpolating host environment variables and config variables into
environment values, volume host paths, build_directory, build_args,
build_secrets’ path, and a build_ssh entry’s paths in batect.yml ($VAR,
${VAR:-default}, <name — see
config reference) — see
differences from Batect.
batect.yml Configuration Reference
Ratect reads a YAML file (batect.yml by default) describing containers and tasks.
This documents the schema Ratect parses (ratect-core/src/config.rs) —
every Batect configuration field is supported, field-for-field, unless listed in
differences from Batect.
A field documented as a string also takes an unquoted number or boolean, read
as the text written: description: 12.6000 is 12.6000, and PYTHON_VERSION: 3.10 in build_args is 3.10, not 3.1. An empty value, ~ or null is
not read as text: as a map value such as a build_args entry, or as a list
entry, it is refused.
Standard YAML features — anchors (&name), aliases (*name), and merge keys
(<<:) — work throughout the file, not just in specific fields: they’re core
YAML syntax handled by the parser itself (noyalib) before any of the schema
below ever sees the document, not something Ratect implements or could disable.
Useful for factoring out a shared base container definition, for example:
containers:
base: &base
image: alpine:3.18
environment:
COMMON_VAR: shared-value
worker:
<<: *base
working_directory: /worker
Extensions
An anchor has to live on something, and sometimes the value you want to share
isn’t a container or task at all — a block of environment variables, say. For
that, a top-level key whose name starts with . is an extension: Ratect
ignores it entirely, so it can hold an anchor for the rest of the file to alias
(matching Batect, which sets kaml’s extensionDefinitionPrefix to .).
.common-environment: &common-environment
TZ: UTC
CI: "true"
containers:
build-env:
image: alpine:3.18
environment:
<<: *common-environment
EXTRA_VAR: extra-value
Only top-level keys are extensions. A .-prefixed key anywhere else is an
ordinary field name, and rejected if it isn’t a real one — so a typo nested
inside a container still gets caught.
Top level
project_name: my-project
containers:
<name>: <Container>
tasks:
<name>: <Task>
config_variables:
<name>: <ConfigVariable>
| Field | Type | Required | Description |
|---|---|---|---|
project_name | string | no | Names the images the project builds (<project_name>-<container name>) and its eu.orican.ratect.project ownership label. Defaults to the lowercased name of the directory holding the root file. Root file only. See Project and container names for what it may contain. |
containers | map of name → Container | no | Container definitions, keyed by name. Referenced from tasks via run.container. See Project and container names for what a name may contain. |
tasks | map of name → Task | no | Task definitions, keyed by name. Run by name via ratect-compat <task-name>. See Task names for what a name may contain. |
config_variables | map of name → ConfigVariable | no | Declares the config variables usable via <name/<{name} expressions. A name must be declared here before it can be referenced — see Expressions — and follows Config variable names. |
include | list of string or Include | no | Splits configuration across multiple files — see Includes below. |
forbid_telemetry | boolean | no | Recognized but inert — Ratect collects no telemetry, so there’s nothing to forbid. |
Project and container names
A built image is tagged <project_name>-<container name>, so project_name and
every container’s name — a pull-only container’s too — must be a Docker
image-name component: lowercase letters and digits, joined by a single period,
one or two underscores, or any number of dashes. my-app, api.v2 and
build_env are names; My-App, -api, a..b, a:b and org/app are not.
A name that breaks the rule is refused, never changed to fit it. The rule is
Batect’s, and so are the messages such a name fails the load with, for every
command, --list-tasks included:
Invalid project name 'My-App'. The project name must be a valid Docker reference: it must contain only lowercase letters, digits, dashes (-), single consecutive periods (.) or one or two consecutive underscores (_), and must not start or end with dashes, periods or underscores.
Invalid container name '-api'. Container names must be valid Docker references: they must contain only lowercase letters, digits, dashes (-), single consecutive periods (.) or one or two consecutive underscores (_), and must not start or end with dashes, periods or underscores.
Like any error raised while the file is parsed, each gives a line, column and path — for a container name, the entry’s value’s, as for a task name.
A root file with no project_name is named after the directory holding it,
lowercased as Batect lowercases it: a batect.yml in My-App/
names the project my-app. A directory whose lowercased name still breaks the
rule (-app/) fails the load, naming the inferred name and the
file and saying to set project_name, as does a root file directly in the
filesystem root, whose directory has no name.
Includes
include:
- some-include.yml
- path: some-other-include.yml
type: file
- type: git
repo: https://github.com/my-org/my-batect-bundle.git
ref: v1.2.3
path: bundle.yml
Each entry is either a bare string path (a local file include), or an object form —
{path, type: file} for another local file, or {type: git, repo, ref, path} for a
Git include (a “bundle”: shared tasks/containers imported from a separate Git
repository). Any other type is rejected with a clear error.
An included file uses the same schema as the root file, with three differences:
- It must not declare
project_name— that’s root-only. - It must not set
forbid_telemetrytotrue— only the root file can forbid telemetry. Setting it tofalseis allowed. containers,tasks, andconfig_variablesmay each be omitted entirely (they default to empty) — a file that exists only toincludefurther files, or only to add one task, doesn’t need to restate the others.
Every file, root or included, must hold some configuration: one that is empty,
or holds only whitespace, comments or a null document (---, ~), fails to
load, naming the file. A file holding just {} loads.
How every loaded file’s containers, tasks, and config_variables merge into
one set, and where an included file’s relative paths resolve, are on
Includes — one page for both formats, from the plain file
include through what a Git-included bundle may do and why. Why you’d share
a bundle across projects at all is Reusable Pipeline Building
Blocks.
Local file includes
A local include’s path is resolved relative to the directory of the file that
declares the include — not the root project directory — so an included file
further down a subdirectory can itself include more files using paths relative to
its own location. A leading ~ is expanded to the host user’s home directory, by
the same rule as a volume’s host path; a Git include’s
path is never expanded.
Git includes
| Field | Type | Required | Description |
|---|---|---|---|
repo | string | yes | A Git remote — anything git clone itself accepts (an HTTPS/SSH URL, a local path, or a remote helper’s <helper>::<address>). |
ref | string | yes | The tag, branch, or commit to check out. Must be a value that never changes (in practice, an immutable tag or a pinned commit SHA, not a branch) — see below. |
path | string | no, default batect-bundle.yml | The path, within the repository, of the file to include — resolved relative to the repository’s own root, not the file that declared the include. |
allow_host_paths | boolean | no, default false | Vouches for this bundle: lets a container it defines use a host path outside both the clone and your project directory. Honoured only on an entry in your own configuration — see Vouching for a bundle. |
A (repo, ref) pair is cloned once and cached forever at
~/.ratect/incl/<hash>, keyed by a hash of the pair — it is never re-fetched, even if
the remote’s ref later moves (e.g. a branch, or a tag someone re-pushed). This is why
ref must be pinned to something immutable: ratect-compat has no update/refresh
mechanism of its own, matching Batect, whose own cache clones only when the working
copy is missing too — the ratect binary can force a re-clone via ratect includes refresh (see the ratect CLI reference), which also
refreshes entries a prior ratect-compat run cached, since both binaries share
~/.ratect/incl. Note
that the 30-day eviction sweep doesn’t help here — it removes entries that go unused,
and an include you’re actively using never becomes stale, so it stays frozen at whatever
its ref pointed to when first cloned. If you need to pick up a change made to a
bundle, choose a new ref (e.g. bump the tag) or delete the corresponding directory
under ~/.ratect/incl by hand.
The same sweep removes a temporary directory a clone left in ~/.ratect/incl when it
was interrupted, once that directory has been unchanged for 30 days, and whatever an
interrupted removal left, at once. A removal moves a clone aside before deleting it, so
one cut short never leaves part of a clone for a later run to use; the next run that
needs the include clones it again.
The sweep runs in the background and nothing waits for it, so there is no command to
report to: an entry or leftover it can’t remove is logged as a warning through
RUST_LOG, if the sweep gets that far before the run exits, and never changes the exit
code. The ratect binary’s
includes clean reports each one.
Everything reached through a Git include is treated as untrusted input: the
file it names must stay inside the clone, a container it defines may mount
only inside the clone or your project directory unless allow_host_paths
vouches for it, and a grant counts only on the entry that reaches a file
first. The rules — and the one place the two formats differ, a bundle’s own
Git includes, which batect.yml always allows — are on What a bundle may
do.
Cloning requires the system git binary to be installed and on PATH — Ratect shells
out to it (git clone --quiet --no-checkout --template= followed by
git checkout --recurse-submodules <ref>, Batect’s two commands with no template)
rather than embedding a Git library, so any Git configuration (credentials,
.gitconfig rewrites, protocol policy, etc.) that your normal git clone already
relies on works the same way for the clone, except a template (init.templateDir),
which it doesn’t use. The checkout, which
fetches nothing, uses none of your Git configuration: core.autocrlf doesn’t change its
line endings, no hook runs during it, and a file stored in Git LFS is left as its
pointer file. The repository’s own .gitattributes still applies, so a bundle that
needs particular line endings sets them there.
A load that clones prints Cloning <repo> <ref>... on stdout first, and a blank line
once the clone has succeeded, in every output style but quiet. git’s own output is
shown only if the clone fails, as part of the error; a prompt for credentials still
reaches the terminal. Wherever Ratect names a repo, credentials in its URL are shown
as *** (https://***@host/repo.git); the clone is given the URL as written. Since a
credential may contain an unencoded /, everything between :// and the URL’s last @
is hidden, even a path’s own: https://host/a@b is shown as https://***@b.
An included repository’s submodules are never checked out, here or under Batect: a
fresh clone has no active submodules for --recurse-submodules to update.
Container
containers:
build-env:
image: alpine:3.18
volumes:
- .:/code
| Field | Type | Required | Description |
|---|---|---|---|
image | string | one of image/build_directory | A Docker image reference to pull and run (e.g. alpine:3.18). Exactly one of image/build_directory is required, and giving both is an error rather than one silently winning. image also can’t be combined with any build-only field (build_args, build_target, dockerfile, build_secrets, build_ssh) — those apply only to a container built from a build_directory. All of this is ratect-compat behaviour; ratect’s native format deliberately allows these combinations because extends needs them — see where the semantics differ. No expression support: Batect resolves none here, so one is rejected when the file loads rather than resolved, which would make the file unusable under batect itself. ratect.toml does resolve them — see Expressions in image. |
image_pull_policy | IfNotPresent or Always | no | On an image container: whether to pull it fresh or only when it’s missing locally. On a build_directory container: whether to force-pull the build’s own base image (docker build --pull) before building, or leave Docker’s own local-cache-if-present behavior alone — Batect’s own second, distinct use of this same field. Defaults to IfNotPresent either way, matching Batect. No expression support. |
build_directory | string | one of image/build_directory | Builds an image from a Dockerfile in this directory (see Image building below) instead of pulling a pre-built one. Supports expressions and is resolved to an absolute path the same way a local volume’s host path is — see Volume path resolution. |
build_args | map of string → string | no | Build-time variables passed to docker build (Docker’s own --build-arg mechanism), e.g. VERSION: "1.2.3". Only meaningful alongside build_directory. Values support expressions. |
dockerfile | string | no | The Dockerfile to build, as a path relative to build_directory’s own root, or an absolute path inside build_directory. Defaults to Dockerfile at build_directory’s root. Only meaningful alongside build_directory. No expression support. Checked when the container’s image is about to be built, before Docker is asked anything: a build_directory that doesn’t exist or isn’t a directory, and a Dockerfile that doesn’t exist, isn’t a regular file, is a symbolic link or is reached through one, or isn’t inside build_directory, each fail the build naming the field. ratect doctor and ratect config validate report the same, and warn about an absolute path, which only works where the project is checked out at that path. |
build_target | string | no | The build stage to stop at (Docker’s own --target mechanism), for a multi-stage FROM ... AS <name> Dockerfile. Only meaningful alongside build_directory. No expression support. |
volumes | list of strings/objects | no | Host bind mounts (local), named cache volumes (cache), and in-memory tmpfs mounts (tmpfs) — see Volume path resolution, Cache volumes, and Tmpfs mounts below. |
dependencies | list of strings | no | Names of other containers to start (recursively, if they themselves have dependencies) before this one, reachable by name over a Docker network created for the duration of the task. Each must name a container declared under containers; one that doesn’t is rejected when the file loads, naming the container that referred to it. Each dependency must become ready — healthy, with all its setup_commands completed — before its dependents start; see Dependency Readiness for the full model, and Dependency readiness below for the two fields it rests on. |
environment | map of string → string | no | Environment variables to set in the container, e.g. FOO: bar. Values support expressions ($VAR, ${VAR:-default}, <name). An unquoted number or boolean (PORT: 8080, DEBUG: true) is accepted and passed on as written — VERSION: 3.10 is 3.10, not 3.1, and MODE: 0x10 is 0x10. An empty value, ~ or null is refused. For what overrides these, and what they override, see Environment precedence. |
run_as_current_user | object (enabled, home_directory) | no | Runs this container as the host’s own user/group instead of the image’s default (see User mapping below). |
additional_hostnames | list of strings | no | Extra network aliases this container is reachable by, beyond its own name. No expression support. |
additional_hosts | map of string → string | no | Extra /etc/hosts entries in this container, hostname: ip, Docker’s own --add-host mechanism. No expression support. |
ports | list of strings/objects | no | Publishes container ports to the host (see Port mappings below). No expression support. Suppressed entirely by --disable-ports, regardless of this field. See CLI reference. |
health_check | object | no | Overrides the health check configuration baked into the container’s image (see Dependency readiness below). No expression support. |
setup_commands | list of objects (command, working_directory) | no | Commands run inside the started container after it becomes healthy; a dependency’s must succeed before its dependents start (see Dependency readiness below). No expression support. |
working_directory | string | no | Overrides the image’s own WORKDIR. No expression support. A task’s own container’s working_directory can be further overridden by the task-level run.working_directory — see TaskRun. A setup_commands entry with no working_directory of its own falls back to the container’s effective working directory — this, or the task’s run.working_directory or customise override where one applies — then to the image’s own default. Batect’s own documentation says a task container’s setup commands ignore run.working_directory; Batect’s code applies it, and Ratect follows the code. |
command | string | no | Overrides the image’s own default CMD. Tokenized into literal argv (quote/backslash-aware whitespace splitting, no shell involved — matching Batect’s own tokenizer exactly). One that can’t be tokenized — an unbalanced quote, a trailing \ — fails the load, as in Batect, even on a container no task uses. No expression support. Applies as-is to a dependency/sidecar container; a task’s own container’s command can be further overridden by the task-level run.command — see TaskRun. |
entrypoint | string | no | Overrides the image’s own ENTRYPOINT. Tokenized into literal argv, and checked when the file loads, the same way command is. No expression support. A task’s own container’s entrypoint can be further overridden by the task-level run.entrypoint — see TaskRun. |
labels | map of string → string | no | Docker labels applied to the container. Container level only — no task-level run override. No expression support. |
capabilities_to_add | list of strings | no | Linux capabilities to add beyond Docker’s own default set (Docker’s --cap-add), e.g. NET_ADMIN. Validated at config-load time against a fixed list based on Batect’s own Capability enum plus BPF/CHECKPOINT_RESTORE/PERFMON (added to Docker after Batect’s last release) — an unknown name is rejected with a clear error. Container level only. No expression support. |
capabilities_to_drop | list of strings | no | Linux capabilities to drop from Docker’s own default set (Docker’s --cap-drop), e.g. CHOWN. Same validation/scope as capabilities_to_add. |
privileged | boolean | no | Runs the container with extended (nearly all host) privileges — Docker’s --privileged. Defaults to false. Container level only. No expression support. |
shm_size | string or integer | no | The size of /dev/shm — Docker’s --shm-size. Accepts Batect’s own size-string format ("128", "128b", "128k", "128m", "128mb", "128g" — a bare number means bytes) or a plain YAML integer (also bytes), which must not be negative. Defaults to Docker’s own default (64 MiB). Container level only. No expression support. |
devices | list of strings/objects | no | Host devices to make available inside the container — Docker’s --device (see Volume path resolution for the similar volumes string form; devices use the same local:container[:options] shape and object form, but with no path resolution — no expression support either). options (cgroup permissions, e.g. "rwm") defaults to "rwm" when omitted, matching the docker CLI’s own default. Container level only. |
enable_init_process | boolean | no | Runs Docker’s own init process as PID 1 ahead of the actual command (reaping zombie processes, forwarding signals) — Docker’s --init. Defaults to false. Container level only. No expression support. |
log_driver | string | no | Docker’s logging driver (Docker’s --log-driver), e.g. "json-file", "syslog", "none". Defaults to leaving Docker’s own daemon-configured default alone. Container level only. No expression support. |
log_options | map of string → string | no | Driver-specific options (Docker’s --log-opt, repeatable) for log_driver — meaningless without it. Container level only. No expression support. |
Note: if a container has neither
imagenorbuild_directoryset, running a task against it is an error naming the container. A dependency container without either is also an error, since it needs to actually run to serve its purpose —build_directoryworks for dependency containers too, not just a task’s own.
Every container’s Docker hostname is always set to its own container name (matching
Batect) — not just its network alias. Without this, a container is reachable by
its name on the network, but hostname/$HOSTNAME inside it would resolve to
Docker’s random short container ID instead, which is easy to be surprised by if
anything logs or checks its own hostname.
Image building
A container with build_directory set is built (not pulled) the first time it’s
needed, and reused for the rest of that ratect invocation if referenced again (as a
task’s own container, as a dependency, or by more than one task) — but never reused
across separate ratect invocations; each run builds fresh. A few things to know:
-
Builder selection: builds use the builder the Docker daemon itself advertises as its default — BuildKit on any modern daemon — exactly matching Batect. The
DOCKER_BUILDKITenvironment variable overrides this either way (1,yesortrueforces BuildKit,0,noorfalsethe classic builder, in any case; empty counts as unset; any other value is an error) — the same variable the docker CLI honors, read with Batect’s vocabulary, since the docker CLI accepts noyes/no.--enable-buildkit(see CLI reference) forces BuildKit on, taking precedence overDOCKER_BUILDKITtoo — there’s no--disable-buildkitcounterpart; force the classic builder viaDOCKER_BUILDKIT=0instead. A daemon old enough not to advertise a default builder at all falls back to the classic builder; one advertising a builder Ratect doesn’t know is an error unlessDOCKER_BUILDKITor--enable-buildkitchooses the builder. Note thatbuild_secretsandbuild_sshrequire BuildKit — combining them with a forced (or daemon-imposed) classic builder is a clear error rather than a silent build without them. -
The Dockerfile built is
dockerfile(a path relative tobuild_directory’s own root, or an absolute path inside it), defaulting toDockerfileatbuild_directory’s own root when omitted. -
build_targetstops the build at that stage, for a multi-stageFROM ... AS <name>Dockerfile — Docker’s own--targetmechanism. -
A
.dockerignorefile atbuild_directory’s root, if present, excludes matching files from the build context — see.dockerignoresemantics below for the (non-obvious) matching rules. No.dockerignoremeans the whole directory tree becomes the build context.dockerfileand.dockerignoreitself are always included in the build context regardless of exclusion patterns, matching Docker’s own special-casing. -
build_secretsexposes secrets to the build via BuildKit’s secret-mount mechanism (a Dockerfile’sRUN --mount=type=secret,id=<key>), without persisting them into the built image’s layers — keyed by theidsuch aRUNinstruction references. Each entry is either{environment: NAME}(read from thisratectprocess’s own environment at build time) or{path: ...}(read from a file on the host, resolved likebuild_directory); exactly one of the two is required. Apathmust exist and be a file, not a directory: as in Batect, one that isn’t fails the build before it begins, whether or not aRUNinstruction mounts it. Requires the BuildKit builder (see builder selection above). Usingbuild_secretsdisables the build cache for that build entirely — BuildKit deliberately excludes a secret’s value from its cache key (so it can’t leak into one), which would otherwise let an unrelated Dockerfile change reuse a cached layer built with a now-stale secret value. -
build_sshmakes SSH keys available to the build, for a Dockerfile’sRUN --mount=type=sshinstructions. Each entry is one agent, named by anidaRUNinstruction selects with--mount=type=ssh,id=<id>.idis required, and ids must be unique across the list. Writedefaultfor the agent a bareRUN --mount=type=sshuses — BuildKit’s implicit id is not applied for you, because Batect requiresidtoo and a config that omitted it would work here but not underbatect. Each entry’spathsdecides where its keys come from, following BuildKit’s own rules:build_ssh: - id: default # required; `default` is the id a bare # `RUN --mount=type=ssh` selects. No paths: # forwards the host's own running # ssh-agent, via its SSH_AUTH_SOCK - id: deploy paths: - ~/.ssh/deploy_key # one or more private key files, served with no - keys/ci_ed25519 # agent running at all - id: other paths: - /tmp/other-agent.sock # a path that *is* a Unix socket forwards # that agent instead; it must be the entry's # only pathA path listed more than once in one entry’s
pathscounts once, as in Batect, so the same socket twice is still that entry’s only path.pathsvalues support expressions and are resolved relative to the config file, the same waybuild_directoryandbuild_secrets’pathare. Key files are served by an ssh-agent Ratect runs in-process for the duration of the build: the keys themselves never leave theratectprocess — only signatures cross into the build — and the socket they’re served on lives in a directory only the current user can open. This is the form that works in CI, where a deploy key usually exists but no agent is running.Keys must not be protected by a passphrase, and must be Ed25519, RSA or ECDSA (Ratect rejects anything else up front, naming the file, rather than failing mid-build). An RSA key whose parts don’t make a valid key is rejected the same way, and so is an unusual one whose private exponent isn’t reduced below its modulus. RSA keys are signed with
rsa-sha2-256/rsa-sha2-512; the legacy SHA-1ssh-rsaalgorithm, which OpenSSH has disabled by default since 8.8, is not offered.Requires the BuildKit builder (see builder selection above). Agents are proxied over the build’s session, not mounted as sockets — so this works unchanged on macOS/Windows, where Docker Desktop’s VM boundary otherwise blocks mounting host sockets into containers (no
/run/host-services/ssh-auth.sockworkaround involved). -
The built image is tagged
<project_name>-<container_name>(matching Batect’s own default), so it’s identifiable indocker imagesrather than showing up as an opaque generated name. That tag is reused/overwritten on every run, though — it’s for identification only, not caching or correctness (Ratect always runs the image it just built, regardless of what the tag currently points to by the time the container starts). -
Built images aren’t cleaned up automatically — since the tag is reused, the image a build replaces becomes a dangling (
<none>) image rather than disappearing, and accumulates until manually pruned (docker image prune), same as repeatedly running a plaindocker build -t ... .would leave behind. Docker’s own build cache is likewise untouched by Ratect. Matches Batect exactly — itsBuildImageStepRunner/CleanupStagePlannerhave no cache-control flag or image-removal step either. -
How much of a build’s output you see depends on the output style:
-o allstreams every build log line as<container> | Image build | ...— under BuildKit, each labelled with its step’s#N, as inapp | Image build | #5 cc -o app main.c;fancyshows the latest line in the container’s status row;simpleprints onlyBuilding <container>...andBuilt <container>.;quietprints nothing. Independently of the style, each build log line is also emitted atdebuglevel (setRUST_LOG=info,ratect_core=debugfor a live transcript without unrelated dependency noise — see filteringRUST_LOG), and if the build fails, the entire transcript is included in the error Ratect reports — not just Docker’s one-line failure summary — so a failingRUNstep’s own output is always visible, under every output style, without needingRUST_LOGset.
.dockerignore semantics
Ratect’s .dockerignore handling is a from-scratch reimplementation of Docker’s own
matching rules (github.com/moby/patternmatcher, which Docker’s documentation cites as
the reference implementation), not a .gitignore-compatible matcher — the two are
not the same, and the difference is easy to get surprised by:
- A bare pattern with no wildcard only excludes at the build context root.
node_modulesexcludes a top-levelnode_modulesdirectory, but not a nested one likepackages/foo/node_modules— unlike.gitignore, where a slash-free pattern matches at any depth by default. Use**/node_modulesfor that. **matches any number of directories (including zero), usable as a prefix, suffix, or standalone segment (**/dir2/*,dir/**,**).- Later lines take precedence over earlier ones — a
!-prefixed line re-includes a path an earlier pattern excluded. - Leading and trailing slashes are no-ops (
/foo/bar,foo/bar/, andfoo/barare all equivalent) — including a trailing slash not restricting a match to directories only, unlike.gitignore. Dockerfileand.dockerignorethemselves are always included in the build context regardless of exclusion patterns, matching Docker’s own special-casing (otherwise a broad*pattern would exclude the file the build needs).
Private registry credentials
Both pulling an image and building one (a Dockerfile FROM a private base image)
resolve credentials from your Docker configuration (~/.docker/config.json by
default, or DOCKER_CONFIG, or --docker-config) — running docker login once
beforehand is enough, including a keychain-backed store (Docker Desktop/OrbStack’s
default) or a cloud registry’s credential helper (ECR/GCR). Building resolves every
registry your Docker config declares (auths and credHelpers), and every
registry its default credsStore holds, as that store’s credential helper lists
them, since Ratect doesn’t parse a Dockerfile’s FROM lines to scope this more
precisely.
A registry whose credential helper fails to resolve doesn’t block the pull or
build — a warning names the registry, so a problem with one registry’s helper
can’t stop work that never needed it, but also doesn’t stay invisible until the
day that registry actually matters. A credsStore whose helper can’t list what it
holds is a warning naming the store, and the build goes ahead with the registries
the config declares.
Volume path resolution
Each volumes entry is a local bind mount (a host path), a cache volume (see
Cache volumes below), or a tmpfs mount (see
Tmpfs mounts below) — either the compact string form or the expanded
object form:
containers:
build-env:
image: alpine:3.18
volumes:
- .:/code
- local: ./logs
container: /var/log/app
options: ro
- type: cache
name: apk-cache
container: /var/cache/apk
- type: tmpfs
container: /code/tmp
A bare string (local_path:container_path or local_path:container_path:options) is
always a local mount — there’s no compact string form for cache/tmpfs. The
expanded object form additionally accepts type: cache (with name instead of
local) or type: tmpfs (with neither local nor name); type: local, the default
when omitted, requires local and forbids name.
For a local mount, local (the host path) is resolved:
- In the object form, the path is interpolated first (see
Expressions) — so a config variable that itself resolves to an
absolute path is taken as absolute, not treated as a literal relative fragment. The
string form’s host path is used as written, as in Batect: a
$or<in$HOME/.m2:/root/.m2is just part of a relative path, so a host path that needs an expression is written as an object. (ratect.tomlinterpolates both forms.) - A leading
~is then expanded to the host user’s home directory —$HOMEwhen it is set and absolute, else the passwd entry’s, as for the Docker CLI — so~/.cache/toolmounts the real cache directory. With no home from either, the path is refused. Only a whole leading~component expands:~user/…(another user’s home) isn’t supported, and a~anywhere but the front is a literal character. Note that a bare~must be quoted (local: "~") — unquoted, YAML reads it as null. - After any interpolation, if the result is relative, it’s resolved to an absolute path
relative to the directory containing the config file (not the current working
directory). If it’s already absolute (whether literally written that way, expanded
from
~, or because that’s what an expression resolved to), it isn’t joined onto anything. Either way, its.and..components and any trailing/are then collapsed lexically, as in Batect — without following symbolic links, so/a/link/..is/awhereverlinkpoints. - This all happens when a task is run, with CLI-supplied config variable overrides
(
--config-var/--config-vars-file) applied — not when the file loads. build_directoryis resolved the same way (it has no:container_pathpart to split off, obviously, but otherwise follows identical rules).
A mount identical to an earlier one once resolved — ./a:/a and a:/a, or a
cache mount listed twice — is mounted once, as in Batect. The same paths with
different options (./a:/a and ./a:/a:ro) are two mounts, which Docker refuses
as a Duplicate mount point, as it does under Batect.
container/options are always used as literal strings — no expression support. A
cache mount’s name/container are also plain strings, matching Batect — no
expression support there either.
Cache volumes
ratect’s native format adds ascopefield here, for a cache shared across projects. Everything below describes the project-scoped kind, which is the only onebatect.ymlhas.
Which directory to point a cache at for each toolchain — Cargo, Go, npm, pip, Gradle — is in Using Ratect With Language Ecosystems.
A cache name must start with a letter or digit and contain only letters,
digits, underscores, dots and dashes — Docker’s own volume-name character set.
The name becomes a host directory under --cache-type=directory, so a name
like /etc or ../../.ssh would otherwise have an arbitrary host directory
bind-mounted into the container; Batect performs no such check, and Ratect
diverges here for the same reason it applies containment to Git
includes. Under --cache-type=volume Docker already enforces this, so nothing that
worked there is affected. Under --cache-type=directory the same rule
applies, so a name: my cache or name: node/modules fails to load. Rename
the cache — the storage is rebuilt on the next run, which is what a cache is
for.
A cache mount persists between separate ratect invocations — unlike local, its
contents aren’t tied to a specific host path in batect.yml. name identifies it,
combined with a per-project key into either a Docker named volume (the default) or a
host directory, selected by --cache-type, or else BATECT_CACHE_TYPE (see CLI reference):
containers:
build-env:
image: alpine:3.18
volumes:
- type: cache
name: apk-cache
container: /var/cache/apk
options: rw # optional
--cache-type=volume(the default): resolves to a Docker named volume,batect-cache-<project-key>-<name>— the exact naming convention Batect itself uses, deliberately, so a project already run under real Batect has its existing cache volumes recognized and reused rather than starting cold.--cache-type=directory: resolves to a host directory under<project_directory>/.batect/caches/<name>/, created if it doesn’t exist yet. Same reasoning as above — this is where an existing Batect project already keeps its own directory-type caches.<project-key>is a value unique to this project, generated once and persisted at<project_directory>/.batect/caches/key(created lazily — the first time a run resolves acachemount, or--cleanlooks for cache volumes, under--cache-type=volume, never eagerly; a--cache-type=directoryrun never reads, creates or changes it) — without it, two unrelated projects that happen to declare a same-named cache (e.g.gradle-cache) would collide on the exact same Docker volume, since Docker volumes live in one flat, global namespace, not scoped by directory. If that file already exists (e.g. from a prior real-batectrun), its existing key is read and reused as-is, never regenerated — even though Ratect’s own generated keys look different (a full UUID, rather than Batect’s own shorter id): nothing depends on matching that format, only on reusing whatever key is already on record for this project. The file must hold exactly one line that isn’t blank or a comment (#), the key; one with none or more than one, or that can’t be read, fails the run or--clean, as in Batect, and is left as it is — replacing it would orphan every cache volume named after the key it held.
The cache root, .batect/caches, belongs to the project. If it, or
.batect, is a symbolic link, Ratect follows it, as Batect does: the key file
and every --cache-type=directory cache are created wherever it points, a run
bind-mounts the cache directory there, and a directory-type --clean removes
every cache directory it finds there. A link only moves storage the project’s
own configuration could already reach, since a local mount can name any host
path, so it’s trusted as that configuration is. Link the root to storage shared
with something else, and a clean removes what it finds there. An entry under the
root that is itself a symbolic link is different: a clean skips it, with a
warning, though a run’s mount of that cache still follows it.
--clean removes every one of this project’s own cache volumes/directories (per
--cache-type or BATECT_CACHE_TYPE) and exits, without running anything; --clean-cache <NAME> (repeatable)
restricts this to the named cache(s) instead of all of them — see
CLI reference.
Tmpfs mounts
A tmpfs mount is an in-memory filesystem — its contents are lost when the container
exits. Unlike local/cache, it has no host path or name — only the expanded object
form is accepted:
containers:
build-env:
image: alpine:3.18
volumes:
- type: tmpfs
container: /code/tmp
options: size=64m # optional
options is a standard
Docker tmpfs mount options
string (e.g. size=64m, mode=1770) forwarded verbatim to Docker — Ratect does no
parsing or validation of its contents, matching Batect.
User mapping
ratect.tomldiffers here. A.tomlfile refuses this field: see Coming fromrun_as_current_user.
containers:
build-env:
image: alpine:3.18
run_as_current_user:
enabled: true
home_directory: /home/container-user
By default, a container runs as whatever user the image defaults to — often root — so
files a task writes to a bind-mounted volume come back host-root-owned. Setting
run_as_current_user.enabled: true runs the container as the host’s own user and
group instead.
enabled defaults to false, as in Batect, so run_as_current_user: {} loads and
maps no user.
Note:
enabled: trueandhome_directoryare only ever valid together — which configs this accepts and refuses matches Batect’s own behavior exactly (the error messages are Ratect’s own), not a Ratect-specific restriction. Settingenabled: truewith nohome_directoryis an error (Ratect never guesses one, since the container’s own image has no home directory prepared for an arbitrary host uid/gid). The reverse is also an error:enabled: false(or omitted) withhome_directorystill set — e.g. simply flippingenabledback tofalsewithout also deletinghome_directoryfails config loading. Removehome_directoryentirely to disable user mapping, not justenabled.
home_directory is used exactly as written, as in Batect: it isn’t an
expression, so a $ or < in it is just part of the path. Unlike
build_directory or a volume’s host path, it is not resolved against the config
file’s directory — it names a path inside the container, so a relative value
would be meaningless there and is rejected as not absolute. A : or control
character in it is also rejected: it is written into the
generated /etc/passwd entry, where either would corrupt
the line. So is / itself, or a path ending in ..: the directory is
created by name inside its parent, and neither has a name to create.
A few things happen automatically to make this actually work, not just set --user:
- Any
localmount’s host path (or acachemount’s own host directory, under--cache-type=directory) that doesn’t exist yet is created before the container is even created, as the current host user. Otherwise Docker’s daemon (running as root) would auto-create it asroot:rooton first use, defeating the point for the common “mount my code directory, get build artifacts back with sane ownership” case. Doesn’t apply to acachemount under the default--cache-type=volume— there’s no host path at all there, just a Docker volume name. - A mount point that falls inside a
localmount (or a directory-typecachemount) — anotherlocalmount, acachemount, or atmpfsmount, at any depth — is created inside that mount’s host directory the same way, with every directory above it, so the daemon doesn’t create those asroot:rootin your project either. It’s an empty file when what’s mounted there is a file or socket, and a directory otherwise (see Differences from Batect). Only the closest enclosing mount counts, and only when it mounts a directory: nothing is created for a mount point inside a Docker volume, or inside a file or socket mount. A mount point that already exists is left alone, and so is one for Docker Desktop’s own/run/host-services//run/guest-servicespaths, one past a file in the host directory, and one in a directory you can’t write to (one the daemon created as root on an earlier run, say) — those are left for the daemon to create. A symlink on the way is followed only while it leads to a directory still inside that mount’s host directory; one leading out of it, or nowhere, leaves the mount point to the daemon. - The container’s own image has no
/etc/passwd//etc/groupentry for an arbitrary host uid/gid — many programs misbehave or refuse to run at all without one (no$HOME, no username resolution). Minimal synthetic/etc/passwd,/etc/shadow, and/etc/groupentries are uploaded into the container before it starts, named after your user and group, or with the uid’s or gid’s digits where the host has no name for it, as in Batect. home_directoryitself is created inside the container (owned by the mapped uid/gid) before it starts — it’s a path inside the container’s own filesystem, not host-mounted, so it doesn’t persist across runs, matching Ratect’s existing ephemeral-container model.- Every
cachemount on the container gets the same ownership treatment, except a read-only one. A Docker volume is created root-owned, so without this the container would mount its cache and then fail on the first write — the mount having succeeded, which makes it a confusing place to find out. Applies to a cache anywhere, including one nested insidehome_directory. A cache mounted withroamong itsoptionskeeps its owner: nothing can write to it, and the read-only mount would refuse the change.
Applies per-container, independently — a task’s own container and each of its
dependencies can each set run_as_current_user on their own; it isn’t inherited or
shared task-wide.
One limitation: host-side uid/gid lookup is Unix-only, and errors clearly on other platforms rather than guessing.
Port mappings
containers:
web:
image: nginx:alpine
ports:
- "8080:80"
- "9000-9002:9100-9102/udp"
- local: 8443
container: 443
ports publishes container ports to the host — Docker’s own -p/--publish
mechanism — and takes either form Batect itself supports, freely mixed within one
list:
- A string,
"local:container[/protocol]"(protocoldefaults totcp), e.g."8080:80"or"8080:80/udp". - A port range string,
"from-to:from-to[/protocol]", e.g."9000-9002:9100-9102"— each local port maps to the corresponding container port by position (9000→9100,9001→9101,9002→9102);localandcontainermust cover the same number of ports. - The expanded object form,
{local, container, protocol}—local/containereach accept a single port or a range (8443or"8000-8002"),protocolis optional (defaults totcp).
Validated at config-load time, as volumes is: a malformed entry, a non-positive
port, or mismatched-size local/container ranges are all rejected before anything
runs. No expression support.
TaskRun.ports (see TaskRun) adds additional port mappings for a
specific task’s run — combined with the container’s own ports as a union, not an
override; there’s no concept of one replacing an entry from the other. A mapping
given more than once, on either side or both, is published once — compared port by
port, so "8080:80" alongside "8080-8081:80-81" publishes 8080 → 80 once.
One container port may be published on several host ports ("9000:80" and
"9001:80", whether both on the container or one in TaskRun.ports), and each
host port is bound.
--disable-ports suppresses publishing of every container’s ports — from both
Container.ports and any TaskRun.ports — regardless of what’s configured. See
CLI reference.
A real, simpler instance of the object form:
examples/full-stack’s
app container publishes - local: 8080 / container: 8080 — one port, no
range or protocol (that project is written in the native ratect.toml
format, where the same field means exactly the same thing — see Field
reference). The range and UDP
forms above have no real counterpart in examples/.
Dependency readiness
A dependency must be ready before anything that depends on it starts:
healthy, then every one of its setup_commands succeeded, in declared order.
What each of those two steps waits for, how Docker reaches a health verdict,
how several dependencies’ waits combine into one task’s start-up, and a real
run of all of it are on Dependency Readiness; the two
fields are below. A task’s own container runs the same gate here,
concurrently with its main command: a failure while that command is still
running fails the task unless the command exits 0 within the next two
seconds, and cancels it if it hasn’t exited by then; once it has exited 0, a
failure is forgiven — the cost and the
race that leaves are described in known
limitations. Under ratect it has none,
even for a task container declared in a YAML file — see The task’s own
container.
health_check overrides the image’s health check configuration — each field
replaces that one aspect, and any field left out inherits the image’s own value:
| Field | Type | Description |
|---|---|---|
command | string | The command to run to check the container’s health, via the container’s default shell (a Dockerfile HEALTHCHECK CMD <string>). Exit code 0 means healthy. |
interval | duration | Time between health check runs. |
retries | integer | Consecutive failures needed before the container is considered unhealthy. |
start_period | duration | Time during which failing checks don’t count against retries (a success during it still counts as healthy immediately). |
timeout | duration | Time a single check may run before it’s considered failed. |
Durations are strings in Batect’s (Go-style) format: one or more <number><unit>
components, in any order — ns, us (or µs/μs), ms, s, m, h,
numbers optionally fractional — e.g. 2s, 500ms, 1m30s, 1.5h, or a bare
0, quoted or not. Any other number needs its unit: interval: 5 is refused.
A negative duration is refused too, except a zero (-0s).
Each setup_commands entry takes:
| Field | Type | Required | Description |
|---|---|---|---|
command | string | yes | The command to run. Tokenized into literal argv, and checked when the file loads, the same way a container’s own command/entrypoint is (see Container) — no shell involved. A command relying on shell operators (&&, $VAR expansion, etc.) needs an explicit sh -c '...' wrapper — the FAQ has the worked explanation. |
working_directory | string | no | Directory to run it in. Falls back to the container’s effective working_directory when omitted — including a task’s run.working_directory or customise override — and then to the image’s own default when none is set. |
Task
tasks:
test:
run:
container: build-env
command: echo "hello"
prerequisites:
- build
| Field | Type | Required | Description |
|---|---|---|---|
run | TaskRun | no* | What to actually execute for this task. |
prerequisites | list of strings | no* | Names of other tasks to run first, in order. Each prerequisite (and its own prerequisites, transitively) runs at most once per ratect invocation, even if shared by multiple tasks. A circular dependency is detected and reported as an error. A name containing * is a wildcard, expanded against every task name at run time (see Wildcard prerequisites below) rather than looked up literally. |
dependencies | list of strings | no** | Sidecar containers scoped to this task specifically — see below. Requires run. Each must name a container declared under containers; one that doesn’t is rejected when the file loads. |
description | string | no | Shown next to the task’s name in --list-tasks output — see below. Purely informational. |
group | string | no | Groups this task under a heading in --list-tasks output, together with every other task sharing the same group — see below. An empty group is the same as none. Purely a display grouping; has no effect on execution order or prerequisites. |
customise | map of string → TaskContainerCustomisation | no | Per-task environment/ports/working_directory overrides, keyed by container name — see below. |
* At least one of run/prerequisites is required. A task with only prerequisites and no run is valid — its prerequisites still run, then Ratect stops, since there’s no container of the task’s own left to run.
** dependencies here is distinct from a container’s own dependencies field: this one is scoped to this task specifically, rather than to every task that uses the container. It’s unioned with the task’s own container’s dependencies — both start together — and can’t name run.container itself.
Task names
A task’s name contains only letters, digits, colons, dashes, periods and
underscores, and starts and ends with a letter or digit — build, lint:go and
test.unit are names, -a, a: and a* are not. The rule is Batect’s, and so
is the message a name that breaks it fails the load with, for every command,
--list-tasks included:
Invalid task name 'a*'. Task names must contain only letters, digits, colons, dashes, periods and underscores, and must start and end with a letter or digit.
Like any error raised while the file is parsed, it gives a line, column and
path — tasks.a* — which for this error are the entry’s value’s, not its key’s.
Wildcard prerequisites
A prerequisites entry containing * is expanded against every task name in the
project, rather than looked up literally:
tasks:
lint:go:
run:
container: build-env
command: golangci-lint run
lint:markdown:
run:
container: build-env
command: markdownlint .
ci:
prerequisites:
- "lint:*"
Running ratect-compat ci here runs both lint:go and lint:markdown (in alphabetical
order) before ci itself. A single * matches zero or more characters, and a
* can’t be part of a task’s name, so a wildcard never names one
task literally. A wildcard matching multiple
tasks always runs them in alphabetical order, regardless of the project’s own
tasks declaration order. A wildcard matching zero tasks is not an error — it
simply contributes nothing. If a task is named both explicitly and by a wildcard in
the same prerequisites list, it still only runs once. Quote a wildcard entry
("lint:*", not lint:*) to avoid YAML parsing * as an anchor reference.
TaskContainerCustomisation
Applies to a non-main container used somewhere in this task’s own container graph
(a task-level or container-level dependency, at any depth) — keyed by container name
under customise:
tasks:
test:
run:
container: build-env
dependencies:
- queue
customise:
queue:
environment:
MODE: test
working_directory: /custom
| Field | Type | Required | Description |
|---|---|---|---|
environment | map of string → string | no | Merged with the container’s own environment — see Environment precedence for the order. Values support the same expressions as environment does. |
ports | list of strings/objects | no | Added to the container’s own ports, not an override — see Port mappings. |
working_directory | string | no | Overrides the container’s own working_directory. No expression support. |
A customise entry can’t target run.container itself — that’s a config error;
set the equivalent property on run instead. It also can’t name a
container that isn’t actually part of this task’s own container graph (whether
because the name doesn’t exist at all, or exists but isn’t reachable from
run.container via dependencies — container-level or task-level).
List-tasks output
With no task declaring a non-empty group, --list-tasks prints a single flat, alphabetically
sorted list — each task’s name, plus its description unless that is empty or
only whitespace. Against
ratect-compat/tests/fixtures/smoke.yml,
which sets neither:
Tasks in ratect-test:
- list-volume-task
- prereq-task
- prerequisites-only-task
- shared-prereq
- test-task
Once any task in the project declares a non-empty group, every task is listed under a
heading instead — one per distinct group value (sorted alphabetically), plus a
trailing Ungrouped tasks: heading for any task that doesn’t set group, or
sets it to the empty string — Batect treats the two alike.
Against
examples/jvm/batect.yml
(every task there sets a group, so there’s no Ungrouped tasks: heading to
show):
Tasks in example-jvm:
Checks:
- lint: Run Checkstyle
Development:
- build: Compile and assemble
- run: Run the application
- test: Run the test suite
Utilities:
- shell: Start a shell in the build environment
With --output quiet, both forms are replaced by
a machine-readable listing instead — one task per line, sorted by name, as name
alone or name<TAB>description, with no header and no grouping — the same project
again:
build Compile and assemble
lint Run Checkstyle
run Run the application
shell Start a shell in the build environment
test Run the test suite
TaskRun
For why && and $VAR don’t do what they look like they do in command, and
the three different $-syntaxes that resemble each other, see the FAQ.
| Field | Type | Required | Description |
|---|---|---|---|
container | string | yes | Name of a container defined under containers. A name that isn’t one is rejected when the file loads. |
command | string | no | Overrides the container’s own command for this task’s run specifically (see Container). Tokenized, and checked when the file loads, the same way. If neither this nor the container’s own command is set, the image’s own default CMD runs instead. Any -- ADDITIONAL_ARGS from the CLI are appended to the command as further literal argv entries — or, when there’s no command, replace the image’s default CMD — see CLI reference. |
environment | map of string → string | no | Environment variables to set for this task’s run specifically. Merged with the container’s own environment — see Environment precedence below for the order. Values support the same expressions as environment does. |
ports | list of strings/objects | no | Additional port mappings for this task’s run specifically — see Port mappings. Added to the container’s own ports, not an override — there’s no concept of one replacing an entry from the other. |
working_directory | string | no | Overrides the container’s own working_directory for this task’s run specifically (see Container), including where its setup_commands run. No expression support. |
entrypoint | string | no | Overrides the container’s own entrypoint for this task’s run specifically (see Container). Tokenized, and checked when the file loads, the same way. No expression support. |
Environment precedence
A container’s environment is assembled from up to four layers, each overriding the one before it on a key collision:
TERM— Ratect’s own, for every container; ordumb, for every container, under--output all. SeeTERMpropagation.- Proxy variables, when any are set where Ratect runs.
- The container’s own
environment. - The task’s
run.environment, for the task’s own container — or itscustomise.<container>.environment, for a dependency (see TaskContainerCustomisation).
An image build layers the same way with what applies to a build: proxy
variables, then the container’s own build_args. Last, the proxies from
Docker’s config.json fill
in any proxy argument still unset, overriding nothing — a layer
--no-proxy-vars skips.
Interactive mode
Which container is eligible, what it gets, when a real TTY is allocated, and
TERM propagation are on Interactive Mode, shared
with ratect.
Proxy environment variables
Which variables are propagated, how no_proxy is extended, localhost
rewriting and the host-gateway entry, the loopback-bound warning, and
--no-proxy-vars are on Proxies, shared with ratect.
ConfigVariable
config_variables:
environment_name:
default: dev
| Field | Type | Required | Description |
|---|---|---|---|
default | string | no | The value used when nothing else provides one — see Expressions for the full precedence order (CLI --config-var > --config-vars-file > this default). Referencing a declared variable that has no default and no override from either CLI source is an error. |
description | string | no | Recognized but inert — Batect surfaces this in its own generated docs/help output; Ratect has no such output to show one in. |
Config variable names
A config variable’s name starts with a letter, contains only letters, digits,
dashes, periods and underscores, and doesn’t start with batect, in any mix of
case — that prefix is kept for built-ins such as
batect.project_directory.
The rule is Batect’s, and so is the message a name that breaks it fails the
load with, located like a task name’s:
Invalid config variable name '1a'. Config variable names must start with a letter, contain only letters, digits, dashes, periods and underscores, and must not start with 'batect'.
Expressions
environment values (on Container, TaskRun and a task’s
customise entries), a
volume’s local host path in the object form (not the string form’s — see Volume
path resolution),
build_directory, build_args, a build_secrets entry’s path (not its
environment — that’s a literal host environment variable name, not itself
interpolated), and a build_ssh entry’s paths support two kinds of expression,
evaluated when you run a task — not when the file loads, so --list-tasks works
whatever this machine supplies, and uses no --config-var/--config-vars-file value.
Each task is evaluated when the run reaches it — after its prerequisites, before
any of its own containers is built or started — with those overrides applied, and
only the containers that task uses: a value this machine can’t supply fails only
a task that needs it. Everywhere else in the config, a
string is used exactly as written, with no substitution — expression support is
scoped to fields that can meaningfully take one; it’ll extend to more fields as they
themselves get built, not automatically.
ratect.tomldiffers here. The native format also resolves expressions inimage, so a tag can be chosen per run — see Expressions inimage. It is rejected in abatect.ymlrather than ignored, because Batect resolves nothing there and a file using one would stop working underbatectitself. In this format,--override-imageis the way to choose an image per run. It also resolves them in a string-form volume’s host path, which abatect.ymluses as written.
Literal
text around an expression is kept ("prefix-$VAR-suffix" interpolates just
$VAR), apart from escapes. Every other $ and < starts an
expression, so write a literal one as \$ or \<.
| Form | Resolves against | Example |
|---|---|---|
$NAME | ratect’s own host environment | $HOME |
${NAME} | ratect’s own host environment | ${HOME} |
${NAME:-default} | ratect’s own host environment, falling back to default if unset | ${LOG_LEVEL:-info} |
<name | A config_variables entry | <environment_name |
<{name} | A config_variables entry | <{environment_name} |
A host variable referenced without a :-default fallback, and unset when ratect
runs, is a hard error naming the container or task, the field, the expression and
the variable — there’s no silent empty-string fallback. A
config variable referenced via <name/<{name} must be declared under
config_variables; an undeclared name is a hard error, and so is a declared one with
no value from any source (see ConfigVariable’s precedence order).
Config variable values themselves come from, highest precedence first: --config-var NAME=VALUE (repeatable), --config-vars-file (a flat YAML map), then the variable’s
own default — see CLI reference.
Variable names
How far a name runs, as in Batect:
- Unbraced (
$NAME,<name): the longest run of letters, digits and_, so a leading digit or a non-ASCII letter is part of it —$5is a variable named5. Anything else ends it:<foo.txtisfoo’s value followed by.txt, and$A-BisA’s value followed by-B. A name holding a.or a-— a config variable such asmy-var, or the built-in — needs braces. - Braced
${…}: everything up to the}, or up to the:that starts a default, which must be:-.${a b}is a variable nameda b. - Braced
<{…}: everything up to the},:included, since a config variable has no default.
A malformed expression fails the file’s load, for every command, --list-tasks
included, and whether or not a task uses that container. It is malformed when:
- a
$or<has no name after it:$,$$,a < b,${},${:-x},<{}; - a
{is never closed:${,${HOME,<{name; - a
:in${…}isn’t followed by-:${LOG_LEVEL:info}; - a default ends in a
\with nothing to escape:${X:-a\.
The error gives the value’s line and column in the file and its path
(containers.app.environment.LOG_LEVEL), quotes the value, and says what is
wrong at which column of the value.
Escaping with \
In any of those fields, a \ makes the character after it literal and is itself
dropped, as in Batect: \$ and \< start no expression, and \\ is one
backslash. Inside a ${NAME:-default}’s default, \} is a } that doesn’t end
it. Quote such a value with single quotes, which keep a backslash as written — in
a double-quoted YAML string, \ is YAML’s own escape first.
environment:
PRICE: '\$100' # $100
DEFAULTED: '${UNSET:-a\}b}' # a}b, when UNSET isn't set
WINDOWS_PATH: 'C:\\Temp' # C:\Temp
(Illustrative; ratect-core/tests/twins/escapes
is a checked-in pair of files using each form.)
A \ at the very end of a value has nothing to escape, so the file fails to load
— for every command that loads it, --list-tasks included, and whether or not a
task uses that container. The error is located like a malformed expression’s.
A ratect.toml reads \ the same way; write such a value as a literal
(single-quoted) TOML string, for the same reason. A field that isn’t an
expression, such as a batect.yml’s image, keeps a backslash as written.
Built-in config variable: batect.project_directory
<{batect.project_directory} always resolves to the
absolute path of the directory containing the root configuration file, even in an
included file — Batect’s one built-in
config variable, so Ratect supports it without requiring (or allowing) it to be
declared under config_variables. Declaring a config_variables entry named
batect.project_directory fails the load, as any name starting
batect does, and supplying one via
--config-var/--config-vars-file is a hard error — it isn’t overridable.
Only the braced form reaches it, as in Batect: an unbraced
name ends at its first ., so <batect.project_directory is a
reference to a config variable named batect, followed by the literal
.project_directory.
Editor autocompletion and validation
Ratect ships a JSON schema describing what this reference documents:
schema/batect-config.schema.json. Pointing
an editor at it gives autocompletion for field names, hover documentation, and a
warning on a misspelled or unsupported field as you type — including the fields
Batect supports and Ratect doesn’t, which is the whole reason this is a schema of
Ratect’s own rather than Batect’s published one
(that one describes Batect’s full field set, so an editor using it would quietly
accept configuration Ratect then rejects at run time).
One gap: the schema lists a text field’s type as string only, so an editor may
warn about an unquoted number or boolean there (description: 12.6000,
interval: 0) that Ratect accepts as written. Quoting the value silences it.
The simplest way to use it is a comment at the top of your config file, which the YAML extension for VS Code and JetBrains IDEs both honor:
# yaml-language-server: $schema=https://raw.githubusercontent.com/or1can/ratect/main/schema/batect-config.schema.json
project_name: my-project
A local path works the same way ($schema=./schema/batect-config.schema.json), and
is worth preferring if you pin a Ratect version — the URL above tracks main, so it
describes the development version, which may accept fields your installed Ratect
doesn’t yet.
The schema describes a single file, include and all — not the merged result of
following those includes — so it applies equally to a root batect.yml and to any
file it includes. Its fields are generated from Ratect’s own configuration types, and
its patterns for durations and sizes are checked against Ratect’s parser, on Batect’s
own cases, by its tests. A shm_size with whitespace Batect refuses, such as
" 128m ", loads in Ratect but is flagged by the schema. The checks it can’t express
are the cross-field ones
(a task needing run or prerequisites, port ranges on both sides of a mapping
covering the same number of ports, customise naming a container that’s actually in
the task’s graph). Those are still reported by Ratect itself, when it loads the file —
for any command that loads it, --list-tasks included.
Not submitted to SchemaStore’s catalog
itself, so an editor only picks the schema up via the $schema line above.
Full example
This mirrors the sample config used in the test suite
(ratect-compat/tests/fixtures/smoke.yml):
project_name: ratect-test
containers:
build-env:
image: alpine:3.18.2
volumes:
- .:/code
tasks:
shared-prereq:
run:
container: build-env
command: echo "I should only run once"
prereq-task:
run:
container: build-env
command: echo "I am a prerequisite"
prerequisites:
- shared-prereq
list-volume-task:
run:
container: build-env
command: ls /code
prerequisites:
- shared-prereq
test-task:
run:
container: build-env
command: echo "Hello from ratect!"
prerequisites:
- prereq-task
- list-volume-task
Running ratect-compat test-task runs shared-prereq once (even though both prereq-task
and list-volume-task depend on it), then prereq-task and list-volume-task, then
test-task itself.