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.