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.