Skip to main content
A stack provisions a language toolchain into an image. Authoring one means writing a small manifest plus the Dockerfile fragments that do the install. This page covers the stack directory; see Stacks for how stacks are selected and resolved, and Authoring bundles for packaging a stack for distribution.

​
Directory layout

A stack is a directory whose name is the stack’s component name:
Place that directory in a loose convention directory to use it immediately, or inside a bundle’s stacks/ directory to distribute it:

​
The manifest

stack.yaml is a thin descriptor:

​
The Dockerfile fragments

The two fragment files are the substance of a stack. They are Docker build snippets that clawker composes into the generated image at the right point:
  • Dockerfile.stack-root.tmpl renders as root, before the container user is created — use it for system-level installs.
  • Dockerfile.stack-user.tmpl renders as the container user, after the user switch — use it for per-user tooling.
Ship whichever your toolchain needs; a stack that only installs system-global tooling needs just the root fragment.

​
Self-guard your install

A stack must be safe to declare unconditionally, because the same name can be provisioned by more than one build stratum and images may already carry the runtime. Guard each fragment so it skips itself when the runtime is already present:
Declaring a build-time ARG (as above) lets consumers override it with clawker build --build-arg MYTOOL_VERSION=2.0.
Fragments are Go text templates, so a handful of build-context variables are available for interpolation. The shipped node, go, python, and rust stacks are the best working reference for the guard pattern, GPG/checksum verification, and the available template variables — copy their shape when writing your own.

​
How a stack renders

A project-declared stack (build.stacks) renders in the shared base image, before your root_run/user_run instructions, so your build steps can rely on it. A stack a harness declares as a dependency renders in that harness image. Both strata render even when they share a name — your self-guard handles any overlap. See Image Customization for the full build ordering.

​
Validating

Bundle a stack and validate it before publishing:
Validation loads each stack the same way clawker build does, so a missing fragment or malformed stack.yaml fails here instead of at build time. Validation checks the bundle envelope and component naming; the fragments prove out at clawker build time.