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

Getting Started

This walks through defining and running your first task with Ratect. It assumes you’ve already installed Ratect and have Docker running.

Which binary? This page uses ratect and its ratect.toml format — the one to install if you’re new here (see Two binaries, two formats). If you already have a batect.yml, see Migrating a Batect Project to Ratect instead, since this page assumes you’re starting from nothing. Nothing below assumes a brand-new codebase either: writing a ratect.toml doesn’t touch any of your existing code, build scripts, or CI — it’s one new file describing how to run what you already have in a container, alongside whatever else the project does today.

Every file and transcript on this page comes from a real project checked into this repository, examples/getting-started — the page builds it up step by step, and a CI job runs every task in it against a real Docker daemon on every change, so what you read here is what actually runs. Clone that directory to follow along without typing anything.

1. Create a ratect.toml

ratect reads its configuration from a ratect.toml file in the current directory (or wherever you point -f/--config-file — see the CLI reference). The smallest file that runs something:

ratect_version = "0.13.0"
project_name = "getting-started"

[containers.build-env]
image = "alpine:3.24"
volumes = [{ local = ".", container = "/code" }]

[tasks.hello]
run = { container = "build-env", command = "ls /code" }

This defines one container (build-env, based on the alpine:3.24 image, with the current directory mounted at /code) and one task (hello, which runs ls /code inside that container). ratect_version records which Ratect the file was written for, so a later Ratect can tell you when one of its changes affects it — see ratect_version.

See the configuration reference for the full schema.

2. Run a task

ratect run hello

ratect run hello -o simple, captured on a terminal in examples/getting-started:

Running hello...
Pulling alpine:3.24...
Pulled alpine:3.24.
Running ls /code in build-env...
README.md    ratect.toml

Cleaning up...
hello finished with exit code 0 in 1.9s.

README.md and ratect.toml are ls /code’s actual output, streamed live as the container produces it — in columns, because the container was given a terminal, exactly as it would be in a shell. Everything else is Ratect’s own framing. A second run skips the pull, since the image is already local.

On a terminal, ratect defaults to its fancy output style, which draws the same milestones in place as they happen rather than one line at a time; the capture above asked for simple so it could be shown on a page. See Output Styles for the others.

3. Prerequisites

Tasks can depend on other tasks, which run first:

[tasks.build]
run = { container = "build-env", command = "echo building..." }

[tasks.test]
prerequisites = ["build"]
run = { container = "build-env", command = "echo testing..." }

Running ratect run test runs build to completion, then test. Within a single ratect run invocation:

  • Each task runs at most once, even if it’s a prerequisite of more than one other task.
  • Each container image is pulled at most once, even if multiple tasks use it.
  • A prerequisite cycle (e.g. a depends on b, b depends on a) is detected and reported as an error rather than hanging.

See Task ordering for the details.

4. Environment variables and expressions

A task’s run (and a container) can set environment variables, and a value can pull in a host environment variable or a declared config variable instead of being written as a literal:

[config_variables.environment_name]
default = "dev"

[tasks.greet.run]
container = "build-env"
command = "sh -c 'echo $GREETING in $ENVIRONMENT_NAME'"
environment = { GREETING = "hello-${WHO:-world}", ENVIRONMENT_NAME = "<environment_name" }

Running ratect run greet (with WHO unset in your shell) prints hello-world in dev. Override the config variable from the command line instead of relying on its default:

ratect run greet --config-var environment_name=staging

which prints hello-world in staging.

Note the sh -c: command is split into arguments with no shell involved, so $GREETING on its own would reach echo as literal text. Ratect’s own ${WHO:-world} and <environment_name expressions are a different thing — resolved by Ratect before the container starts, in environment values and a few other fields, never inside command. See the FAQ for the three $-syntaxes that look alike, the configuration reference for the full expression syntax (including batect.project_directory, always available without being declared), and the CLI reference for --config-var/--config-vars-file.

5. List available tasks

With four tasks in the file now, list them:

ratect tasks list
Tasks in getting-started:
- build
- greet
- hello
- test

A task’s optional description and group fields turn this flat list into a grouped one, with a line of help per task — see Worked Examples for what that looks like.

6. Reading the output

Ratect separates two kinds of output:

  • stdout: the actual output of your command — this is what your task produces, and what tasks list prints. Safe to pipe or redirect.
  • stderr: everything Ratect itself says — its progress (the lifecycle lines, shaped by --output), warnings and errors, and its internal diagnostics, logged via tracing. Only the diagnostics answer to the RUST_LOG environment variable, e.g.:
RUST_LOG=debug ratect run hello

debug also surfaces low-level Docker API activity (container create/start/remove), which is useful when troubleshooting — see Filtering RUST_LOG for scoping it to Ratect’s own diagnostics.

Next steps

See Worked Examples for a real build/test/run/lint/shell task set in Rust, Go, Node.js, Python, or the JVM — a faster starting point than building one up from scratch if your project is in one of those. Once you have a container running your own toolchain, Using Ratect With Language Ecosystems covers what to cache and a couple of correctness gotchas per ecosystem.