Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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>
FieldTypeRequiredDescription
project_namestringnoNames 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.
containersmap of name → ContainernoContainer definitions, keyed by name. Referenced from tasks via run.container. See Project and container names for what a name may contain.
tasksmap of name → TasknoTask definitions, keyed by name. Run by name via ratect-compat <task-name>. See Task names for what a name may contain.
config_variablesmap of name → ConfigVariablenoDeclares 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.
includelist of string or IncludenoSplits configuration across multiple files — see Includes below.
forbid_telemetrybooleannoRecognized 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_telemetry to true — only the root file can forbid telemetry. Setting it to false is allowed.
  • containers, tasks, and config_variables may each be omitted entirely (they default to empty) — a file that exists only to include further 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

FieldTypeRequiredDescription
repostringyesA Git remote — anything git clone itself accepts (an HTTPS/SSH URL, a local path, or a remote helper’s <helper>::<address>).
refstringyesThe 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.
pathstringno, default batect-bundle.ymlThe 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_pathsbooleanno, default falseVouches 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
FieldTypeRequiredDescription
imagestringone of image/build_directoryA 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_policyIfNotPresent or AlwaysnoOn 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_directorystringone of image/build_directoryBuilds 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_argsmap of string → stringnoBuild-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.
dockerfilestringnoThe 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_targetstringnoThe 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.
volumeslist of strings/objectsnoHost bind mounts (local), named cache volumes (cache), and in-memory tmpfs mounts (tmpfs) — see Volume path resolution, Cache volumes, and Tmpfs mounts below.
dependencieslist of stringsnoNames 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.
environmentmap of string → stringnoEnvironment 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_userobject (enabled, home_directory)noRuns this container as the host’s own user/group instead of the image’s default (see User mapping below).
additional_hostnameslist of stringsnoExtra network aliases this container is reachable by, beyond its own name. No expression support.
additional_hostsmap of string → stringnoExtra /etc/hosts entries in this container, hostname: ip, Docker’s own --add-host mechanism. No expression support.
portslist of strings/objectsnoPublishes 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_checkobjectnoOverrides the health check configuration baked into the container’s image (see Dependency readiness below). No expression support.
setup_commandslist of objects (command, working_directory)noCommands 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_directorystringnoOverrides 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.
commandstringnoOverrides 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.
entrypointstringnoOverrides 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.
labelsmap of string → stringnoDocker labels applied to the container. Container level only — no task-level run override. No expression support.
capabilities_to_addlist of stringsnoLinux 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_droplist of stringsnoLinux capabilities to drop from Docker’s own default set (Docker’s --cap-drop), e.g. CHOWN. Same validation/scope as capabilities_to_add.
privilegedbooleannoRuns the container with extended (nearly all host) privileges — Docker’s --privileged. Defaults to false. Container level only. No expression support.
shm_sizestring or integernoThe 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.
deviceslist of strings/objectsnoHost 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_processbooleannoRuns 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_driverstringnoDocker’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_optionsmap of string → stringnoDriver-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 image nor build_directory set, 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_directory works 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_BUILDKIT environment variable overrides this either way (1, yes or true forces BuildKit, 0, no or false the 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 no yes/no. --enable-buildkit (see CLI reference) forces BuildKit on, taking precedence over DOCKER_BUILDKIT too — there’s no --disable-buildkit counterpart; force the classic builder via DOCKER_BUILDKIT=0 instead. 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 unless DOCKER_BUILDKIT or --enable-buildkit chooses the builder. Note that build_secrets and build_ssh require 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 to build_directory’s own root, or an absolute path inside it), defaulting to Dockerfile at build_directory’s own root when omitted.

  • build_target stops the build at that stage, for a multi-stage FROM ... AS <name> Dockerfile — Docker’s own --target mechanism.

  • A .dockerignore file at build_directory’s root, if present, excludes matching files from the build context — see .dockerignore semantics below for the (non-obvious) matching rules. No .dockerignore means the whole directory tree becomes the build context. dockerfile and .dockerignore itself are always included in the build context regardless of exclusion patterns, matching Docker’s own special-casing.

  • build_secrets exposes secrets to the build via BuildKit’s secret-mount mechanism (a Dockerfile’s RUN --mount=type=secret,id=<key>), without persisting them into the built image’s layers — keyed by the id such a RUN instruction references. Each entry is either {environment: NAME} (read from this ratect process’s own environment at build time) or {path: ...} (read from a file on the host, resolved like build_directory); exactly one of the two is required. A path must exist and be a file, not a directory: as in Batect, one that isn’t fails the build before it begins, whether or not a RUN instruction mounts it. Requires the BuildKit builder (see builder selection above). Using build_secrets disables 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_ssh makes SSH keys available to the build, for a Dockerfile’s RUN --mount=type=ssh instructions. Each entry is one agent, named by an id a RUN instruction selects with --mount=type=ssh,id=<id>. id is required, and ids must be unique across the list. Write default for the agent a bare RUN --mount=type=ssh uses — BuildKit’s implicit id is not applied for you, because Batect requires id too and a config that omitted it would work here but not under batect. Each entry’s paths decides 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 path
    

    A path listed more than once in one entry’s paths counts once, as in Batect, so the same socket twice is still that entry’s only path.

    paths values support expressions and are resolved relative to the config file, the same way build_directory and build_secrets’ path are. Key files are served by an ssh-agent Ratect runs in-process for the duration of the build: the keys themselves never leave the ratect process — 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-1 ssh-rsa algorithm, 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.sock workaround involved).

  • The built image is tagged <project_name>-<container_name> (matching Batect’s own default), so it’s identifiable in docker images rather 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 plain docker build -t ... . would leave behind. Docker’s own build cache is likewise untouched by Ratect. Matches Batect exactly — its BuildImageStepRunner/ CleanupStagePlanner have no cache-control flag or image-removal step either.

  • How much of a build’s output you see depends on the output style: -o all streams every build log line as <container> | Image build | ... — under BuildKit, each labelled with its step’s #N, as in app | Image build | #5 cc -o app main.c; fancy shows the latest line in the container’s status row; simple prints only Building <container>... and Built <container>.; quiet prints nothing. Independently of the style, each build log line is also emitted at debug level (set RUST_LOG=info,ratect_core=debug for a live transcript without unrelated dependency noise — see filtering RUST_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 failing RUN step’s own output is always visible, under every output style, without needing RUST_LOG set.

.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_modules excludes a top-level node_modules directory, but not a nested one like packages/foo/node_modules — unlike .gitignore, where a slash-free pattern matches at any depth by default. Use **/node_modules for 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/, and foo/bar are all equivalent) — including a trailing slash not restricting a match to directories only, unlike .gitignore.
  • Dockerfile and .dockerignore themselves 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/.m2 is just part of a relative path, so a host path that needs an expression is written as an object. (ratect.toml interpolates both forms.)
  • A leading ~ is then expanded to the host user’s home directory — $HOME when it is set and absolute, else the passwd entry’s, as for the Docker CLI — so ~/.cache/tool mounts 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 /a wherever link points.
  • 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_directory is resolved the same way (it has no :container_path part 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 a scope field here, for a cache shared across projects. Everything below describes the project-scoped kind, which is the only one batect.yml has.

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 a cache mount, or --clean looks for cache volumes, under --cache-type=volume, never eagerly; a --cache-type=directory run 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-batect run), 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.toml differs here. A .toml file refuses this field: see Coming from run_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: true and home_directory are 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. Setting enabled: true with no home_directory is 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) with home_directory still set — e.g. simply flipping enabled back to false without also deleting home_directory fails config loading. Remove home_directory entirely to disable user mapping, not just enabled.

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 local mount’s host path (or a cache mount’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 as root:root on first use, defeating the point for the common “mount my code directory, get build artifacts back with sane ownership” case. Doesn’t apply to a cache mount 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 local mount (or a directory-type cache mount) — another local mount, a cache mount, or a tmpfs mount, 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 as root:root in 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-services paths, 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/group entry 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/group entries 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_directory itself 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 cache mount 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 inside home_directory. A cache mounted with ro among its options keeps 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]" (protocol defaults to tcp), 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); local and container must cover the same number of ports.
  • The expanded object form, {local, container, protocol} — local/container each accept a single port or a range (8443 or "8000-8002"), protocol is optional (defaults to tcp).

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:

FieldTypeDescription
commandstringThe 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.
intervaldurationTime between health check runs.
retriesintegerConsecutive failures needed before the container is considered unhealthy.
start_perioddurationTime during which failing checks don’t count against retries (a success during it still counts as healthy immediately).
timeoutdurationTime 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:

FieldTypeRequiredDescription
commandstringyesThe 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_directorystringnoDirectory 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
FieldTypeRequiredDescription
runTaskRunno*What to actually execute for this task.
prerequisiteslist of stringsno*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.
dependencieslist of stringsno**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.
descriptionstringnoShown next to the task’s name in --list-tasks output — see below. Purely informational.
groupstringnoGroups 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.
customisemap of string → TaskContainerCustomisationnoPer-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
FieldTypeRequiredDescription
environmentmap of string → stringnoMerged with the container’s own environment — see Environment precedence for the order. Values support the same expressions as environment does.
portslist of strings/objectsnoAdded to the container’s own ports, not an override — see Port mappings.
working_directorystringnoOverrides 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.

FieldTypeRequiredDescription
containerstringyesName of a container defined under containers. A name that isn’t one is rejected when the file loads.
commandstringnoOverrides 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.
environmentmap of string → stringnoEnvironment 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.
portslist of strings/objectsnoAdditional 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_directorystringnoOverrides the container’s own working_directory for this task’s run specifically (see Container), including where its setup_commands run. No expression support.
entrypointstringnoOverrides 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:

  1. TERM — Ratect’s own, for every container; or dumb, for every container, under --output all. See TERM propagation.
  2. Proxy variables, when any are set where Ratect runs.
  3. The container’s own environment.
  4. The task’s run.environment, for the task’s own container — or its customise.<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
FieldTypeRequiredDescription
defaultstringnoThe 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.
descriptionstringnoRecognized 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.toml differs here. The native format also resolves expressions in image, so a tag can be chosen per run — see Expressions in image. It is rejected in a batect.yml rather than ignored, because Batect resolves nothing there and a file using one would stop working under batect itself. In this format, --override-image is the way to choose an image per run. It also resolves them in a string-form volume’s host path, which a batect.yml uses 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 \<.

FormResolves againstExample
$NAMEratect’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}
<nameA 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 — $5 is a variable named 5. Anything else ends it: <foo.txt is foo’s value followed by .txt, and $A-B is A’s value followed by -B. A name holding a . or a - — a config variable such as my-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 named a 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.