Stevedore.Build (Stevedore v0.2.0)

Copy Markdown View Source

Assemble images declaratively from layers + a config — the crane-style create surface.

Stevedore builds images as data; it never runs build steps (no Dockerfile RUN). For each layer it computes both digests the spec requires and keeps them straight:

  • the diff_id — sha256 of the uncompressed tar (goes in the config's rootfs.diff_ids)
  • the descriptor digest — sha256 of the compressed bytes (goes in the manifest)

The default compression is gzip; output is OCI media types (or Docker v2s2 via format: :docker). Builds are deterministic: layer compression and tar headers carry no timestamps, so the same inputs yield the same digests.

Spec: OCI image-spec, config and layer; crane semantics.

Summary

Types

layer_input()

A layer source: an uncompressed tar binary, a list of Stevedore.Archive.entry/0, or a {path, opts} pointing at an uncompressed tar file.

Functions

append(image, layer_input, opts \\ [])

Appends a layer to an image, adding a matching history entry and recomputing the manifest.

from_dir(path, config, opts \\ [])

Builds a single-layer image from a directory tree.

image(layer_inputs, config, opts \\ [])

Builds an image from a list of layer inputs and a config.

Types

layer_input()

@type layer_input() :: binary() | [Stevedore.Archive.entry()] | {Path.t(), keyword()}

A layer source: an uncompressed tar binary, a list of Stevedore.Archive.entry/0, or a {path, opts} pointing at an uncompressed tar file.

Functions

append(image, layer_input, opts \\ [])

@spec append(Stevedore.Image.t(), layer_input(), keyword()) ::
  {:ok, Stevedore.Image.t()} | {:error, term()}

Appends a layer to an image, adding a matching history entry and recomputing the manifest.

from_dir(path, config, opts \\ [])

@spec from_dir(Path.t(), map() | Stevedore.Config.t(), keyword()) ::
  {:ok, Stevedore.Image.t()} | {:error, term()}

Builds a single-layer image from a directory tree.

The tree is tarred with deterministic ordering and zeroed timestamps, so the same tree always produces the same digest.

image(layer_inputs, config, opts \\ [])

@spec image([layer_input()], map() | Stevedore.Config.t(), keyword()) ::
  {:ok, Stevedore.Image.t()} | {:error, term()}

Builds an image from a list of layer inputs and a config.

config is the runtime config — a map of :entrypoint/:cmd/:env/:user/:working_dir/ :labels, or a Stevedore.Config.t/0. Options: :platform ("os/arch" or a keyword), :format (:oci/:docker), :compression (:gzip/:none/:zstd).

Examples

iex> tar = Stevedore.Archive.write!([%{name: "f", type: :regular, mode: 0o644, size: 2, linkname: nil, content: "hi"}])
iex> {:ok, image} = Stevedore.Build.image([tar], %{entrypoint: ["/f"]})
iex> length(image.layers)
1