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

Introduction

Define your development tasks — build, test, lint, a database to develop against, … — once in configuration, and run them identically on any machine that has Docker. No “works on my machine”, no per-developer setup drift, no JVM to start: Ratect is a single native binary, so it runs instantly.

If that sounds like Batect, that’s deliberate: Batect was archived in October 2023, and Ratect grew out of it — same batect.yml, running on a native binary instead of a JVM one. But it’s not just a port: Ratect already fixes real bugs Batect never got to (leaked containers and networks on anything but Ctrl+C, an eight-year-old open proxy issue) and adds tooling Batect never had — ratect doctor, ratect resources, a native ratect.toml format. See Differences from Batect for the full list, drop-in replacement included. It’s an independent project, not affiliated with or endorsed by the original Batect project.

See it in action

A real request against a real, composed stack — an app, a database, and a cache, each waiting for the last to actually be ready (not just “started”) before it starts itself — no wait-for-it.sh, no manual networking, no leftover containers once it’s done. This is the dependency graph from examples/full-stack — that project also has build/unit-test/run/lint/shell tasks, omitted here to keep this to the part that’s actually running below:

ratect_version = "0.13.0"
project_name = "ratect-full-stack"

[containers.app]
image = "node:22"
working_directory = "/code"
enable_init_process = true
ports = [{ local = 8080, container = 8080 }]
environment = { DATABASE_URL = "postgres://postgres@db:5432/postgres", REDIS_URL = "redis://cache:6379" }
volumes = [
    { local = "app", container = "/code" },
    { type = "cache", name = "full-stack-npm-cache", container = "/root/.npm" },
]
# Not just for `run` — `app` cannot even start without both (it connects to
# `cache` at module load, and `db` on its first request), so this belongs
# on the container itself rather than repeated on every task that uses it.
dependencies = ["db", "cache"]
command = "sh -c 'npm ci && npm start'"
# Checked from outside, over the project's own network, instead of by the
# `node -e` one-liner this used to be — escaping quotes inside a TOML string
# to make a single HTTP request. `node:22` is a full Debian image and could
# run that check itself; the field exists for images that can't (distroless,
# `scratch`), and is used here because the declarative form says what is
# actually meant. Nothing runs inside `app` to prove it is ready.
[containers.app.external_health_check]
type = "http"
port = 8080
path = "/healthz"
interval = "1s"
retries = 20

[containers.db]
image = "postgres:16"
environment = { POSTGRES_HOST_AUTH_METHOD = "trust" }
volumes = [{ local = "db/init", container = "/docker-entrypoint-initdb.d" }]
health_check = { command = "pg_isready -h 127.0.0.1 -U postgres", interval = "1s", retries = 90 }
# ANALYZE needs a real, committed table to work against, which is exactly
# what setup_commands is for — running once db is healthy, not baked into
# the init script that creates and seeds that table in the first place.
# Genuinely useful here, not just illustrative: a bulk INSERT this size
# leaves the query planner without fresh statistics until something
# collects them, and the journey-test/app queries below count() this table.
setup_commands = [
    { command = "psql -U postgres -c \"ANALYZE visits;\"" },
]

[containers.cache]
image = "redis:7"
health_check = { command = "redis-cli ping", interval = "1s", retries = 10 }

[containers.journey-test]
image = "node:22"
working_directory = "/code"
environment = { REDIS_URL = "redis://cache:6379" }
volumes = [
    { local = "journey-test", container = "/code" },
    { type = "cache", name = "full-stack-npm-cache", container = "/root/.npm" },
]
command = "sh -c 'npm ci && node test.js'"

[tasks.journey-test]
description = "Exercise the running app end to end, sharing `cache` with `app`"
group = "Development"
dependencies = ["app", "cache"]
run = { container = "journey-test" }

A real recording, not a mockup — fancy output shows all four containers’ status live, updating in place, each independently: db seeding a real million-row table before it’s ready (genuinely, not padded — that’s why it takes longer than app/cache), then running a real setup_commands step (ANALYZE visits, giving the query planner fresh statistics after that bulk insert) once it’s healthy but before anything depends on it, then app and journey-test both starting only once cache says it’s ready — cache itself, once, even though it’s a dependency of both. journey-test makes a real HTTP request to app (the JSON in the middle is its real response), then checks Redis directly to confirm the value app read got cached — see Dependency Readiness for the full model behind all of it. Every container is removed afterwards regardless of how the task ends.

Two binaries, two formats

Ratect ships two binaries. ratect reads its own ratect.toml format and is the one to install if you’re starting fresh — it’s the forward-looking CLI, free to add things Batect never had. ratect-compat reads a batect.yml unchanged, as a drop-in replacement for the (now unmaintained) batect binary, and stays batect.yml-only permanently — pick it if you already have a Batect project and want a maintained tool without editing any YAML. Both run the same engine and exit with the same codes, are versioned and released independently, and can be mixed: ratect -f batect.yml reads a Batect config too, a ratect.toml project can include a batect.yml fragment as-is, and ratect config convert translates a whole batect.yml when you’re ready to move.

Where to go next

Source and issue tracker: or1can/ratect.