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

Using Ratect With Language Ecosystems

Every toolchain below assumes its own persistence: a package manager expects its downloaded dependencies to still be there next time, a compiler expects its incremental build cache to survive between invocations. Ratect’s own container model doesn’t give you that for free — every task starts a fresh container, and anything written outside a mounted volume disappears with it. Without a cache volume pointed at the right directory, a toolchain that assumes persistence just re-downloads or recompiles everything, every single run, as if it were on a brand-new machine each time.

This page has one section per ecosystem, naming exactly which directories need to be a cache volume and why, plus the couple of correctness gotchas that aren’t a caching question at all. Every config referenced here is the real, CI-proven config under examples/ — see Worked Examples for the full files.

Rust

volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "cargo-registry", container = "/usr/local/cargo/registry" },
    { type = "cache", name = "cargo-target", container = "/code/target" },
]

Two separate caches, for two separate things Cargo persists:

  • cargo-registry — the crate index and every downloaded/extracted dependency source. Without this, cargo build re-fetches your entire dependency tree from crates.io on every run.
  • cargo-target — compiled build artifacts (target/). Without this, every run is a cold, from-scratch compile — the difference between an incremental rebuild and a full one, which for a large dependency tree is minutes rather than seconds.

Go

volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "go-mod", container = "/go/pkg/mod" },
    { type = "cache", name = "go-build", container = "/root/.cache/go-build" },
]

Same split as Rust, Go’s own equivalents:

  • go-mod (GOPATH’s module cache) — downloaded module sources. Without it, go build/go test re-fetches every dependency module fresh.
  • go-build (GOCACHE) — the compiler’s own build cache (compiled packages, keyed by input hash). Without it, every build recompiles the entire dependency graph rather than reusing what hasn’t changed.

A linter with its own cache (golangci-lint’s ~/.cache/golangci-lint/, for example) would need the same treatment if a project adopts one — examples/go doesn’t, so there’s nothing to demonstrate it against here, but the pattern is identical: mount whatever directory the tool itself says it caches into.

Node.js

volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "npm-cache", container = "/root/.npm" },
]

npm-cache — npm’s own download cache, not node_modules itself. node_modules stays a plain, uncached part of the working directory (rebuilt by npm ci on each run, from what’s in the cache); what needs to persist is npm’s cache of already-downloaded package tarballs, so a repeat npm ci doesn’t re-download the same versions from the registry every time.

A long-lived Node process needs enable_init_process too — this isn’t a caching question, but Batect’s own nodejs.md covers it for the same reason it belongs here: Node doesn’t handle running as PID 1 correctly, so a container with no init process won’t forward SIGINT/Ctrl+C to it correctly. examples/node’s own run task doesn’t need this — it prints a message and exits, nothing to interrupt — but examples/full-stack’s app container is exactly the long-lived-server case, and sets enable_init_process = true for it.

Python

volumes = [
    { local = ".", container = "/code" },
    { type = "cache", name = "pip-cache", container = "/root/.cache/pip" },
]

pip-cache — pip’s own download/wheel-build cache. Without it, every pip install re-downloads and, for a package with no prebuilt wheel for the image’s platform, rebuilds it from source from scratch, every run.

JVM (Gradle)

environment:
  GRADLE_OPTS: -Dorg.gradle.daemon=false
volumes:
  - local: .
    container: /code
  - type: cache
    name: gradle-cache
    container: /root/.gradle

gradle-cache (~/.gradle) — Gradle’s dependency cache and its own build cache, in one directory. Without it, every run re-resolves and re-downloads the full dependency graph.

Disable the Gradle daemon. This one’s a correctness/performance gotcha rather than a caching question, and it points the opposite direction from everything above: Gradle’s daemon exists to stay warm across invocations, so it can skip reloading and recompiling the build script on the next run. That benefit depends on the daemon surviving between runs — which never happens in a Ratect container, disposable per task. Without -Dorg.gradle.daemon=false, every task pays the daemon’s own startup cost and then throws it away with the container, strictly worse than never starting one. examples/jvm sets this on build-env via GRADLE_OPTS.

If a Gradle build under Docker Desktop looks hung or dies without a message, the ceiling is usually Docker’s own, not Ratect’s — see the FAQ.

Not covered

Batect’s own per-ecosystem pages also cover .NET Core and Ruby — both caching-only concerns there, no correctness gotcha like Gradle’s or Node’s. Ratect has no example project for either ecosystem, so there’s nothing real to ground a section in here without inventing untested config; a real worked example for either is its own, larger undertaking than this page.

Next steps

From here, Task Lifecycle is the step-by-step account of what ratect run actually does — task ordering, per-task setup and cleanup — and Dependency Readiness is when a dependency counts as ready and how several dependencies’ waits combine; the FAQ collects the questions that come up first. When a second project wants the same containers and tasks, Includes covers pulling in a shared file or a Git bundle, and Reusable Pipeline Building Blocks why you’d want to.