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

Operations

rib is designed primarily for non-interactive CI/CD use while retaining the same interface locally. Production pipelines should pin the builder version, platform, base-image digest, and network settings.

Progress, stderr, and stdout

--progress accepts:

ModeBehavior
autoInteractive UI when stderr is a terminal; line output otherwise
colorForces the interactive UI
plainStable line-oriented CI messages
quietHides progress while retaining the final summary

Progress, warnings, and the summary go to stderr. When stdout is not a terminal, a successful build writes only the manifest digest, without a prefix or trailing newline:

IMAGE_DIGEST="$(rib build \
  --progress plain \
  --from scratch \
  --platform linux/amd64 \
  --copy ./server:/server,mode=0755 \
  --entrypoint /server \
  --to registry:registry.example.com/team/server:v1)"

cosign sign "registry.example.com/team/server@${IMAGE_DIGEST}"

Do not enable shell tracing around commands containing credentials, because the shell may log raw arguments before rib starts.

Concurrency

--jobs limits concurrent COPY builds, base-blob downloads, and target-blob uploads. The default is the available CPU count capped at four. Increasing it may improve network throughput while increasing CPU, disk, and registry load. Reduce it under tight ephemeral-storage or bandwidth limits.

Destinations are processed sequentially in declaration order. Layer operations within one registry destination are concurrent.

Temporary data and base-layer cache

Layer temporary files use the system temporary directory (TMPDIR on Unix). Registry and OCI outputs normally retain only compressed local layers. Docker archive output also retains uncompressed layers. The archive’s own temporary file is created beside its final path.

For large images, provision storage for compressed local layers, downloaded base layers, uncompressed Docker layers, and the temporary final archive.

Downloaded base blobs are not persistent by default. Enable caching with:

rib build ... --cache
rib build ... --cache --cache-path /cache/rib

The default path is ./.rib-cache. Cached blobs are rehashed before reuse. This cache stores downloaded base layers only; it neither stores built layers nor replaces Cargo/npm caches. Multiple rib processes may share the directory: writers use separate staging files and publish atomically after digest and size verification. Incomplete downloads never replace complete entries. Cache verification runs on the blocking pool under --jobs and observes cancellation. A direct push to the same registry usually needs no local cache because registry-side blob reuse avoids downloads.

Network transport

Defaults are a 30-second connect timeout, a 60-second read timeout, three attempts, and HTTPS with certificate verification. Configure these through --connect-timeout, --read-timeout, and --max-attempts.

Source and target insecure options are separate:

  • --from-plain-http, --from-skip-tls;
  • --to-plain-http, --to-skip-tls.

The target options affect all registry destinations in the invocation. Use them only for trusted development infrastructure.

Multiple destinations

rib build \
  --from alpine:3.22 \
  --platform linux/amd64 \
  --copy ./server:/app/server,mode=0755 \
  --entrypoint /app/server \
  --to registry:registry.example.com/team/server:v1 \
  --to oci-archive:dist/server-oci.tar@server:v1 \
  --to docker-archive:dist/server-docker.tar@server:v1

The configuration and manifest are created once, so all outputs have one manifest digest. They do not form a transaction: failure of a later output does not roll back completed registry publications or archives.

Logs and diagnostics

Enable detailed logs with:

RIB_LOG=rib=debug rib build --progress plain ...

RUST_LOG is intentionally not used because cargo rib build launches a user Rust project that may interpret it. Use plain, quiet, or auto in CI; color may emit terminal control sequences.

Termination and partially published data

Ctrl-C and, on Unix, SIGTERM cancel the top-level operation. Copy, archive, and layer-decompression writers check cancellation during writes. A cancelled archive remains temporary and is not published at its target path.

Archives become visible through an atomic rename only after a complete write and file synchronization. Registry manifests are sent after layers and the configuration. Unreferenced blobs uploaded before an error can remain until normal registry garbage collection.