gantry build
Build an OCI image from your lockfile or Dockerfile, reuse cached layers, and optionally push it, for one platform or several.
CLI referenceUpdated 30 Sep 20264 min read
Usage
$ gantry build [service...] [flags]Description
gantry build produces an OCI image for each named service, or for every service that builds when you name none. Services with a Dockerfile are built from it; services set to build = "lockfile" get a generated recipe based on the lockfile it finds.
Images are tagged project-service:commit and stay on your machine unless you pass --push. gantry up runs the same build before starting anything.
Options
| Flag | Default | Description |
|---|---|---|
| -t, --tag <name> | <svc>:<sha> | Tag to give the image. Repeatable. |
| -f, --file <path> | Dockerfile | Build from a different Dockerfile. |
| --platform <os/arch,...> | host | One or more target platforms. Non-native platforms build under emulation. |
| --target <stage> | – | Stop at a named stage of a multi-stage Dockerfile. |
| --build-arg <KEY=value> | – | Set a build argument. Repeatable. |
| --no-cache [=layer] | – | Rebuild without the cache, or only one layer: base, deps or src. |
| --push | – | Push to the registry in gantry.toml, or the one set with --registry. |
| --output <type> | image | image, tar for a portable archive, or dir to unpack the filesystem. |
| --sbom | – | Write a software bill of materials next to the image. |
The layer cache
Every image Gantry builds is made of the same four layers, from slowest-changing at the bottom to fastest at the top. A change only rebuilds its own layer and the ones above it. Pick a change to see what it costs.
- baseCachedThe base image or system packages change.40–120 MB
- depsCachedThe lockfile changes.80–400 MB
- srcRebuiltAny file under the build context changes.1–20 MB
- configRebuiltEnvironment, command or ports change.< 1 KB
Rebuilds 2 of 4 layers, 1–20 MB. Everything below it comes from the cache.
~/.gantry/layers and are never uploaded unless you push. In CI, cache that folder between runs; on a warm cache a typical build drops from minutes to seconds.Examples
Build every service for the host platform:
$ gantry buildBuild web for two platforms and push both to the registry:
$ gantry build web --platform linux/amd64,linux/arm64 --push resolve pnpm-lock.yaml · 412 packages 0.19s layers linux/amd64 · 4 cached 0.08s layers linux/arm64 · 3 cached · 1 built 11.4s push registry.example.com/acme/web:4f2a9c1 5.7sExport the filesystem of a build stage to inspect it:
$ gantry build web --target deps --output dir=./outExit codes
| Code | Meaning |
|---|---|
| 0 | Every image built, and pushed if --push was set. |
| 1 | A build step failed. The failing step and its output are printed above. |
| 2 | gantry.toml or the Dockerfile is invalid. |
| 4 | Push was refused: not logged in, or no write access. |
| 130 | Interrupted with Ctrl C. |