Worked Examples
A real, minimal hello-world project for five common ecosystems — Rust, Go,
Node.js, Python, and the JVM — each with build, test, run, lint, and
shell
tasks using that ecosystem’s own usual tooling and base image. shell starts an
interactive shell in the build environment — no config needed beyond the task
itself, since interactive mode is
automatic. It’s the fastest way to poke around when a build environment isn’t
behaving as expected. The config below each intro is included directly from
the actual project, checked into this repository under
examples/ — what you
read here is exactly what a CI job in this repository runs against a real
Docker daemon on every change, so it can’t silently drift out of date. Clone
the whole directory to run one yourself, or copy the config and adjust the
commands to your own scripts.
Four of the five are ratect.toml; the same containers and tasks work
identically as batect.yml with ratect-compat (see Two binaries, two
formats) — the JVM example below is
batect.yml itself, for reasons its own section explains.
See the
configuration reference for what each field
does, and Getting Started if you haven’t run a task
before.
Every command below that chains two steps with && wraps them in sh -c '...'. command is tokenized into literal argv, with no shell
involved — an unwrapped && doesn’t fail
loudly, it’s just handed to the first program as a literal extra argument,
which several package managers silently ignore rather than reject. The
FAQ walks through it, including
the config-time $VAR syntax that looks the same and isn’t.
Try it
Cloning examples/rust
and running ratect tasks list there prints:
Tasks in example-rust:
Checks:
- lint: Run clippy with warnings denied
Development:
- build: Compile the project
- run: Run the application
- test: Run the test suite
Utilities:
- shell: Start a shell in the build environment
ratect run followed by any task name (build, test, run, lint, or shell)
then actually runs it — see Getting
Started for what that output looks like
against a real Docker daemon.
Rust
examples/rust.
The official rust image doesn’t ship the clippy component by default, so
lint adds it before running; the Cargo registry and the target build
output are each cached separately, so only the first run is cold.
ratect_version = "0.13.0"
project_name = "example-rust"
[containers.build-env]
image = "rust:1.90"
working_directory = "/code"
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "cargo-registry", container = "/usr/local/cargo/registry" },
{ type = "cache", name = "cargo-target", container = "/code/target" },
]
[tasks.build]
description = "Compile the project"
group = "Development"
run = { container = "build-env", command = "cargo build" }
[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "cargo test" }
[tasks.run]
description = "Run the application"
group = "Development"
run = { container = "build-env", command = "cargo run" }
[tasks.lint]
description = "Run clippy with warnings denied"
group = "Checks"
run = { container = "build-env", command = "sh -c 'rustup --quiet component add clippy && cargo clippy --all-targets -- -D warnings'" }
[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }
Go
examples/go.
lint uses go vet, part of the standard toolchain already in the build-env
image — no second tool or container needed for a minimal project like this
one.
ratect_version = "0.13.0"
project_name = "example-go"
[containers.build-env]
image = "golang:1.23"
working_directory = "/code"
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "go-mod", container = "/go/pkg/mod" },
{ type = "cache", name = "go-build", container = "/root/.cache/go-build" },
]
[tasks.build]
description = "Build the binary"
group = "Development"
run = { container = "build-env", command = "go build ./..." }
[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "go test ./..." }
[tasks.run]
description = "Run the application"
group = "Development"
run = { container = "build-env", command = "go run ." }
[tasks.lint]
description = "Run go vet"
group = "Checks"
run = { container = "build-env", command = "go vet ./..." }
[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }
Node.js
examples/node.
A TypeScript project with build/test/lint npm scripts (tsc, vitest,
eslint). Each of build, test and lint runs npm ci itself, and
run gets it through its build prerequisite, rather than relying on a
separate install step — a task’s own container is recreated from scratch every run,
so only what lands in the bind-mounted project directory or a cache mount
survives to the next one. The npm cache mount is what keeps a repeated npm ci fast.
ratect_version = "0.13.0"
project_name = "example-node"
[containers.build-env]
image = "node:22"
working_directory = "/code"
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "npm-cache", container = "/root/.npm" },
]
[tasks.build]
description = "Compile TypeScript"
group = "Development"
run = { container = "build-env", command = "sh -c 'npm ci && npm run build'" }
[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "sh -c 'npm ci && npm test'" }
[tasks.run]
description = "Run the built application"
group = "Development"
prerequisites = ["build"]
run = { container = "build-env", command = "node dist/index.js" }
[tasks.lint]
description = "Run eslint"
group = "Checks"
run = { container = "build-env", command = "sh -c 'npm ci && npm run lint'" }
[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }
Python
examples/python.
A plain script rather than a packaged library, kept deliberately simple;
build byte-compiles it as a minimal stand-in for a real build step (there
isn’t a natural one for a script with no compiled artifact). Same reasoning
as the Node example above for why test/lint each reinstall: the pip
cache mount is what makes that cheap.
ratect_version = "0.13.0"
project_name = "example-python"
[containers.build-env]
image = "python:3.12"
working_directory = "/code"
volumes = [
{ local = ".", container = "/code" },
{ type = "cache", name = "pip-cache", container = "/root/.cache/pip" },
]
[tasks.build]
description = "Byte-compile the project"
group = "Development"
run = { container = "build-env", command = "python -m compileall ." }
[tasks.test]
description = "Run the test suite"
group = "Development"
run = { container = "build-env", command = "sh -c 'pip install -r requirements-dev.txt && pytest'" }
[tasks.run]
description = "Run the application"
group = "Development"
run = { container = "build-env", command = "python hello.py" }
[tasks.lint]
description = "Run ruff"
group = "Checks"
run = { container = "build-env", command = "sh -c 'pip install -r requirements-dev.txt && ruff check .'" }
[tasks.shell]
description = "Start a shell in the build environment"
group = "Utilities"
run = { container = "build-env", command = "bash" }
JVM (Gradle)
examples/jvm.
Written as batect.yml rather than ratect.toml, deliberately: Batect
itself is a Gradle/Kotlin project, and JVM/Gradle is where its own
conventions and sample projects skew, so an existing Batect-using JVM shop
is likely migrating a batect.yml that already looks close to this one —
ratect-compat reads it unchanged. The task set relies on the project’s own
checked-in Gradle wrapper (./gradlew), so the image itself needs nothing
but a JDK; lint runs Checkstyle, the traditional
choice, via its own Gradle task rather than a separate tool.
project_name: example-jvm
containers:
build-env:
image: eclipse-temurin:25-jdk
working_directory: /code
environment:
GRADLE_OPTS: -Dorg.gradle.daemon=false
volumes:
- local: .
container: /code
- type: cache
name: gradle-cache
container: /root/.gradle
tasks:
build:
description: Compile and assemble
group: Development
run:
container: build-env
command: ./gradlew assemble
test:
description: Run the test suite
group: Development
run:
container: build-env
command: ./gradlew test
run:
description: Run the application
group: Development
run:
container: build-env
command: ./gradlew run
lint:
description: Run Checkstyle
group: Checks
run:
container: build-env
command: ./gradlew checkstyleMain checkstyleTest
shell:
description: Start a shell in the build environment
group: Utilities
run:
container: build-env
command: bash
Only batect.yml ships in examples/jvm/ — the same containers and tasks
would re-spell directly into ratect.toml with no behavior change (run
ratect config convert to generate one), see
extends/list-entry shape
for the syntax differences you’d see in the result.
Next steps
Every example above declares a cache volume or two. Using Ratect With
Language Ecosystems says which directories each
toolchain needs cached and why, plus the couple of correctness gotchas per
ecosystem that aren’t a caching question at all.