docker

Runs and manages Docker containers and images.

Types

Type	Description
`ArchiveError`	Raised when an image archive cannot be read or written.
`Container`	A running or stopped container.
`ContainerExitError`	Raised by `Container.wait` when the container exits unsuccessfully.
`ContainerState`	The live state of a container.
`Image`	A container image.
`ImageTag`	A repository and tag naming an image.
`InvalidImageReferenceError`	Raised when an image reference is malformed.
`MountInfo`	A mount of a container, as reported by `Container.state`.
`NoContainerError`	Raised when a container ID or name cannot be found.
`NoImageError`	Raised when an image reference cannot be found.
`PortBinding`	A published port of a container, as reported by `Container.state`.
`PushResult`	The result of pushing an image.
`RegistryAuthError`	Raised when a registry rejects the credentials for an image.
`AddSpec`	A file to add in a build step, from a path or URL or as direct content.
`ArchiveFormat`	An image archive format. Docker supports only `:DOCKER_ARCHIVE:`.
`BuildMount`	A mount available to every build step.
`ContainerMount`	A mount for a container.
`ContainerStatus`	The lifecycle state of a container.
`Env`	Environment variables to set. A value of `:INHERIT:` copies the variable from the calling environment; any other value is converted to a string.
`PatchSpec`	A unified patch to apply in a build step, from a file or as direct content.
`Platform`	A target platform: an `os/arch[/variant]` string, or its parts.
`PortProtocol`	A network protocol for a published port.
`PortSpec`	A container port to publish on the host.
`PullPolicy`	An image pull policy.
`RestartSpec`	A container restart policy.

`AddSpec = (Dict[{source: Str | fs.Path | url.Url, target: Str | fs.Path, ?chmod: Int | fs.unix.Mode}] | Dict[{content: Str | Bin, target: Str | fs.Path, ?chmod: Int | fs.unix.Mode}])`

A file to add in a build step, from a path or URL or as direct content.

If target is a directory, a source path or URL keeps its file name. Direct content is always written to target itself. chmod sets the destination's permissions.

`ArchiveFormat = (:DOCKER_ARCHIVE: | :OCI_ARCHIVE: | :OCI_DIR: | :DOCKER_DIR: | :DIR:)`

An image archive format. Docker supports only :DOCKER_ARCHIVE:.

Value	Meaning
`:DOCKER_ARCHIVE:`	Single-file Docker archive, the only multi-image format
`:OCI_ARCHIVE:`	Single-file OCI archive
`:OCI_DIR:`	OCI layout directory
`:DOCKER_DIR:`	Docker directory format
`:DIR:`	Plain directory of layers

`BuildMount = Dict[{type: :CACHE: | :BIND: | :VOLUME: | :TMPFS:, target: Str | fs.Path, ?source: Str | fs.Path, ?id: Str, ?readonly: Bool}]`

A mount available to every build step.

Key	Meaning
`type`	Mount type
`target`	Mount path in the container
`source`	Host path or volume name. Required for `:BIND:`
`id`	Cache ID. Defaults to `target`
`readonly`	Mount read-only. Defaults to `false`

`ContainerMount = Dict[{type: :BIND: | :VOLUME: | :TMPFS:, target: Str | fs.Path, ?source: Str | fs.Path, ?readonly: Bool}]`

A mount for a container.

Key	Meaning
`type`	Mount type
`target`	Mount path in the container
`source`	Host path or volume name. Required for `:BIND:`
`readonly`	Mount read-only. Defaults to `false`

`ContainerStatus = (:CREATED: | :RUNNING: | :PAUSED: | :RESTARTING: | :REMOVING: | :EXITED: | :DEAD:)`

The lifecycle state of a container.

`Env = Dict[Str | Sym, Value]`

Environment variables to set. A value of :INHERIT: copies the variable from the calling environment; any other value is converted to a string.

`PatchSpec = (Dict[{source: Str | fs.Path}] | Dict[{content: Str | Bin}])`

A unified patch to apply in a build step, from a file or as direct content.

`Platform = (Str | Dict[{os: Str, arch: Str, ?variant: Str}])`

A target platform: an os/arch[/variant] string, or its parts.

`PortProtocol = (:TCP: | :UDP: | :SCTP:)`

A network protocol for a published port.

`PortSpec = Dict[{container_port: Int | Str, ?host_port: Int | Str, ?host_ip: Str, ?protocol: PortProtocol}]`

A container port to publish on the host.

Key	Meaning
`container_port`	Container port
`host_port`	Host port. Assigned automatically when omitted
`host_ip`	Host address to bind
`protocol`	Protocol. Defaults to `:TCP:`

`PullPolicy = (:MISSING: | :ALWAYS: | :NEVER:)`

An image pull policy.

Value	Meaning
`:MISSING:`	Pull the image only when it is not local
`:ALWAYS:`	Always pull the image
`:NEVER:`	Never pull the image

`RestartSpec = Dict[{policy: :NO: | :ON_FAILURE: | :ALWAYS: | :UNLESS_STOPPED:, ?max_retries: Int}]`

A container restart policy.

Value	Meaning
`:NO:`	Do not restart the container
`:ON_FAILURE:`	Restart after an unsuccessful exit
`:ALWAYS:`	Always restart the container
`:UNLESS_STOPPED:`	Restart unless explicitly stopped

max_retries limits restarts, and applies only to :ON_FAILURE:.

Functions

`build :from ...steps … -> _container.dockman.Image`

Builds a Docker image.

Parameters

Name	Type	Description
`:pull?`	`_container.dockman.PullPolicy`	Image pull policy for the base image.
`:mounts?`	`Iterable[_container.dockman.BuildMount]`	Mounts available to every build step.
`:cd?`	`(Str \| fs.Path)`	Working directory for `run` steps.
`:env?`	`_container.dockman.Env`	Environment for `run` steps.
`:from`	`Str`	Base image.
`...steps`		Build steps and tags, in order, as keyword arguments. Keys may repeat.

`...steps`

Key	Value	Meaning
`tag`	`Str`	Apply an output image tag
`run`	`() -> Value`	Run a function inside the container
`add`	`AddSpec`	Add a file to the image
`patch`	`PatchSpec`	Apply a patch inside the image
`commit`	`Str`	Commit a layer with a message

Example

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

`container ref -> _container.dockman.Container`

Gets a container by ID or name.

Parameters

Name	Type	Description
`ref`	`Str`	Container ID or name.

`containers … -> Iterable[_container.dockman.Container]`

Lists containers.

Parameters

Name	Type	Description
`:all?`	`Bool`	List all containers, including stopped ones.
`:filter?`	`Str`	Filter expression, such as `"name=myapp*"`.

`create image ...args … -> _container.dockman.Container`

Creates a stopped Docker container, in the :CREATED: state.

Parameters

Name	Type	Description
`image`	`Str`	Image name or ID.
`cmd?`	`Str`	Command to run instead of the image command.
`:cd?`	`(Str \| fs.Path)`	Container working directory.
`:env?`	`_container.dockman.Env`	Container environment. `nil` values are not supported.
`:pull?`	`_container.dockman.PullPolicy`	Image pull policy.
`:name?`	`Str`	Container name.
`:mounts?`	`Iterable[_container.dockman.ContainerMount]`	Mounts.
`:labels?`	`Dict[Str \| Sym, Value]`	Container labels.
`:ports?`	`Iterable[_container.dockman.PortSpec]`	Ports to publish.
`:networks?`	`Iterable[Str]`	Networks to connect to, by name or ID.
`:user?`	`Str`	User, or `user:group`.
`:entrypoint?`	`Str`	Entrypoint override.
`:restart?`	`_container.dockman.RestartSpec`	Restart policy.
`...args`		Arguments passed to `cmd`.

`image ref -> _container.dockman.Image`

Gets an image by reference.

Parameters

Name	Type	Description
`ref`	`Str`	Image reference, such as `"myapp:latest"` or `"sha256:abc..."`.

`images … -> Iterable[_container.dockman.Image]`

Lists images, one per repository and tag.

Parameters

Name	Type	Description
`:all?`	`Bool`	List all images, including intermediate layers.
`:filter?`	`Str`	Filter expression, such as `"reference=myapp*"`.

`load source … -> Array[_container.dockman.Image]`

Loads images from an archive.

Parameters

Name	Type	Description
`source`	`(Str \| fs.Path)`	Archive to load.
`:platform?`	`_container.dockman.Platform`	Platform to load.

`pull ref … -> _container.dockman.Image`

Pulls an image from a registry.

Parameters

Name	Type	Description
`ref`	`Str`	Image reference.
`:platform?`	`_container.dockman.Platform`	Platform to pull.

`push ref … -> _container.dockman.PushResult`

Pushes an image to a registry.

Parameters

Name	Type	Description
`ref`	`Str`	Image reference.
`:platform?`	`_container.dockman.Platform`	Platform to push.

`run image cmd ...args … -> nil`

Runs a command in a temporary Docker container.

Parameters

Name	Type	Description
`image`	`Str`	Image name or ID.
`cmd`	`Str`	Command to run instead of the image command.
`:cd?`	`(Str \| fs.Path)`	Container working directory.
`:env?`	`_container.dockman.Env`	Container environment.
`:pull?`	`_container.dockman.PullPolicy`	Image pull policy.
`:name?`	`Str`	Container name.
`:mounts?`	`Iterable[_container.dockman.ContainerMount]`	Mounts.
`:labels?`	`Dict[Str \| Sym, Value]`	Container labels.
`:ports?`	`Iterable[_container.dockman.PortSpec]`	Ports to publish.
`:networks?`	`Iterable[Str]`	Networks to connect to, by name or ID.
`:user?`	`Str`	User, or `user:group`.
`:entrypoint?`	`Str`	Entrypoint override.
`...args`		Arguments passed to `cmd`.

`save target ...images … -> (Str | fs.Path)`

Saves one or more images to an archive, returning target.

Parameters

Name	Type	Description
`target`	`(Str \| fs.Path)`	Archive path to write.
`:format?`	`_container.dockman.ArchiveFormat`	Archive format.
`:platform?`	`_container.dockman.Platform`	Platform to save.
`...images`	`Str`	Image references to save. Only `:DOCKER_ARCHIVE:` holds more than one.

`with[R] image func … -> R`

Runs a function in a temporary Docker container.

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

Parameters

Name	Type	Description
`image`	`Str`	Image name or ID.
`func`	`(() -> R)`	Function to run.
`:cd?`	`(Str \| fs.Path)`	Container working directory.
`:env?`	`_container.dockman.Env`	Container environment.
`:pull?`	`_container.dockman.PullPolicy`	Image pull policy.