Skip to content

container.docker

Functions

run image cmd ...args

Run a direct command in a temporary Docker container from image.

Returns nil.

with image func

Run a function in a temporary Docker container from image.

Program execution and filesystem access will be redirected for the duration of the function.

Returns

The result of func

build :pull? :mounts? :from ...args

Build a Docker image.

Base parameters
  • from: base image
  • pull:
    • :missing: (default): only pull missing images
    • :always:: always attempt to pull images
  • tag: output image tag; may be omitted or repeated
Optional parameters
mounts: <array>

Container mounts available for the entire build process. Each element is a dict of the form:

  • type:
    • cache: Mount a persistent cache at target
    • bind: Bind mount source at target
  • target: <path | str>: target mount path
  • source: <path | str>: mount source (omit for cache mounts)
  • id (optional): identifier for cache mounts; target used if omitted
Build steps
run: func

Run func (a callable) inside the container

add: <dict>

Add a file to the image:

  • source: <path | url | str>: source path or URL
  • content: <str | bin>: content to write directly to target
  • target: <path | str>: target path; if a directory, source file name will be appended for source, but not for content
  • chmod: mode (optional): change target permissions
commit: msg

Creates a layer with the given message

Example
Returns

The final Image

import container.docker: docker
let img = docker.build
  from: ubuntu:24.04
  run: do run apt install -y curl
  tag: my-image
assert_eq $img.tags()[0].tag my-image

images :all? :filter?

List images, returning an iterator of Image objects

Parameters
  • all: list all images
  • filter: optional filter expression (e.g. "reference=myapp*")
Returns

An iterator of Image objects, one per repository:tag pair

image ref

Get a single image by reference

Parameters
  • ref: image reference (e.g. "myapp:latest", "sha256:abc...")
Returns

An Image object

containers :all? :filter?

List containers.

container ref

Get a single container by ID or name.

save target :format? :platform? ...images

Save one or more images to an archive.

format: accepts either strings such as docker_archive or symbols such as :docker_archive:.

load source :platform?

Load images from an archive.

pull ref :platform?

Pull an image from a registry.

push ref :platform?

Push an image to a registry.