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.
BuildSteps[I, O]	Build steps and tags, in order, as keyword arguments. Keys may repeat.
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

@let AddSpec = $
  | BaseDict $
      source: (Str | fs.Path | url.Url)
      target: (Str | fs.Path)
      ?chmod: (Int | fs.unix.Mode)
  | BaseDict[{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

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

Type	Description
: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 = BaseDict[{…}]

A mount available to every build step.

Item	Type	Description
type	:CACHE: | :BIND: | :VOLUME: | :TMPFS:	Mount type
target	Str | fs.Path	Mount path in the container
?source	Str | fs.Path	Host path or volume name. Required for :BIND:
?id	Str	Cache ID. Defaults to target
?readonly	Bool	Mount read-only. Defaults to false
?size	Int | Str	Size limit
?chown	Bool	Change the mount's owner to the container user
?selinux	:SHARED: | :PRIVATE:	Relabel for SELinux: :SHARED: or :PRIVATE:

BuildSteps[I, O]

@let BuildSteps[I, O] = $
  *tag: Str
  *run: ((<I, >O) -> nil)
  *add: AddSpec
  *patch: PatchSpec
  *commit: Str

Build steps and tags, in order, as keyword arguments. Keys may repeat.

Key	Value	Meaning
tag	Str	Apply an output image tag
run	() -> nil	Run a block 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

A run block has the strand input and output of the build's caller.

ContainerMount = BaseDict[{…}]

A mount for a container.

Item	Type	Description
type	:BIND: | :VOLUME: | :TMPFS:	Mount type
target	Str | fs.Path	Mount path in the container
?source	Str | fs.Path	Host path or volume name. Required for :BIND:
?readonly	Bool	Mount read-only. Defaults to false

ContainerStatus

@let ContainerStatus = $
  | :CREATED:
  | :RUNNING:
  | :PAUSED:
  | :RESTARTING:
  | :REMOVING:
  | :EXITED:
  | :DEAD:

The lifecycle state of a container.

Env = BaseDict[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 = (BaseDict[{source: Str | fs.Path}] | BaseDict[{content: Str | Bin}])

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

Platform = (Str | BaseDict[{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 = BaseDict[{…}]

A container port to publish on the host.

Item	Type	Description
container_port	Int | Str	Container port
?host_port	Int | Str	Host port. Assigned automatically when omitted
?host_ip	Str	Host address to bind
?protocol	PortProtocol	Protocol. Defaults to :TCP:

PullPolicy

An image pull policy.

Type	Description
:MISSING:	Pull the image only when it is not local
:ALWAYS:	Always pull the image
:NEVER:	Never pull the image

RestartSpec

@let RestartSpec = BaseDict $
  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[I, O] :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	_container.dockman.BuildSteps[I, O]	Build steps and tags, in order, as keyword arguments. Keys may repeat.
<	I
>	O

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?	BaseDict[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.
:init?	Bool	Run an init process that forwards signals and reaps child processes.
:entrypoint?	Str	Entrypoint override.
:restart?	_container.dockman.RestartSpec	Restart policy.
*args	Value	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 …

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?	BaseDict[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.
:init?	Bool	Run an init process that forwards signals and reaps child processes.
:entrypoint?	Str	Entrypoint override.
*args	Value	Arguments passed to cmd.
<	Iter[Value]
>	Sink[Str]

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 block in a temporary Docker container.

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

Parameters

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