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

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.