API

Basics

class docked.Image(first: Stage, *rest: Stage, syntax_channel: str = DEFAULT_CHANNEL, syntax_version: str | None = None, escape: str = '\\')

A Docker image. Consists of one or more Stages.

Parameters:

  • *stages – at least one stage. Multiple for multi-stage builds.

  • syntax_channel – the Dockerfile syntax to use. Default: docker/dockerfile.

  • syntax_version – the Dockerfile syntax version to use. If not specified explicitly, will be detected based on the features you use, sticking to the lowest minor version possible.

  • escape – the escape character to use in Dockerfile. Default: \.

as_str() → str

Generate Dockerfile.

build(args: list[str] | None = None, binary: str = 'docker', exit_on_failure: bool = True, stdout: TextIO = sys.stdout, stderr: TextIO = sys.stderr) → int

Build the image using syscalls to the Docker CLI.

Parameters:

  • args – additional CLI arguments to pass into Docker binary.

  • binary – docker binary to use. Must be either a path or in $PATH.

  • exit_on_failure – set to False to make the method return the exit code as a result instead of calling sys.exit on failure.

  • stdout – stream to pipe Docker CLI stdout into.

  • stderr – stream to pipe Docker CLI stderr into.

iter_lines() → Iterator[str]

Iterate over lines of Dockerfile.

Useful for writing a big Dockerfile in a file or a stream.

lint(disable_codes: Container[int] = (), stdout: TextIO = sys.stdout, exit_on_failure: bool = True) → int

Run linter on the image.

Parameters:

  • disable_codes – error codes to skip. Leave it empty by default, add some values into it when you face false-positives.

  • stdout – stream where to write the reported violations.

  • exit_on_failure – set to False to return exit code on failure instead of callin sys.exit.

property min_version: str

The minimal Dockerfile version required.

Determined based on the instructions and their arguments used.

save(path: Path) → None
save(path: None = None) → Path

Save Dockerfile in the given file path.

If no path provided, save into a temporary file and return the file path.

property syntax: str

Syntax of the Dockerfile to use.

If no syntax_version provided, the min_version will be used.

class docked.Stage(*, base: BaseImage | Stage, name: str = 'main', platform: str | None = None, build: list[BuildStep] | None = None, run: list[RunStep] | None = None, labels: dict[str, str] | None = None)

A single stage of the build.

Represents everything from FROM to FROM (or end of file) in Dockerfile.

Many arguments might appear as they would better fit into Image, but not really. One Image can produce multiple container images when using multi-stage builds. And depending on which Stage you target, the correspoding arguments (like labels) might be different.

Parameters:

  • base – base image to use or a previous Stage to start from.

  • name – the Stage name. Must be specified and unique for multi-stage builds.

  • platform – the platform for which to build the image.

  • build – Steps to execute when building the image.

  • run – Steps that affect how container based on the image will be ran.

  • labels – meta information associated with the resulting image. Corresponds to LABEL instruction in Dockerfile.

property all_steps: Iterator[Step]

Iterate over all steps, from both build and run.

as_str() → str

Represent the stage as valid Dockerfile syntax.

iter_lines() → Iterator[str]

Emit lines of Dockerfile one-by-one.

Useful for generating big stages without putting too much into memory.

property min_version: str

The minimal syntax version required for the Stage.

Build steps

class docked.BuildStep

Step that can be used in Stage.build.

These are steps that directly executed when building an Image.

class docked.ARG(name: str, default: str | None = None)

Define a variable that users can pass at build-time to the builder with the docker build.

The difference with ENV is that env vars set with ARG are not available in running container, only at build-time.

https://docs.docker.com/engine/reference/builder/#arg

class docked.CLONE(src: str | PosixPath | list[str | PosixPath], dst: str | PosixPath, chown: str | int | None = None, link: bool = False, keep_git_dir: bool = False)

Clone a git repository.

Currently, available only in development channel. So, you’ll need to explicitly specify the syntax to use this instruction:

image = d.Image(
    stage,
    syntax_channel='docker/dockerfile-upstream',
)

https://docs.docker.com/engine/reference/builder/#adding-a-git-repository-add-git-ref-dir

class docked.COPY(src: str | PosixPath | list[str | PosixPath], dst: str | PosixPath, chown: str | int | None = None, link: bool = False, from_stage: Stage | BaseImage | None = None)

Copies new files or directories from src and adds them to the filesystem of the image at the path dst.

https://docs.docker.com/engine/reference/builder/#copy

class docked.DOWNLOAD(src: str | PosixPath | list[str | PosixPath], dst: str | PosixPath, chown: str | int | None = None, link: bool = False, checksum: Checksum | None = None)

Download a remote file.

https://docs.docker.com/engine/reference/builder/#add

class docked.ENV(key: str, value: str)

Set an environment variable.

The environment variables set using ENV will persist when a container is run from the resulting image.

https://docs.docker.com/engine/reference/builder/#env

class docked.EXTRACT(src: str | PosixPath | list[str | PosixPath], dst: str | PosixPath, chown: str | int | None = None, link: bool = False)

Extract an archive from the host machine into the image.

Supported formats: identity, gzip, bzip2, and xz.

https://docs.docker.com/engine/reference/builder/#add

class docked.ONBUILD(trigger: BuildStep)

Add to the image a trigger instruction to be executed at a later time, when the image is used as the base for another build.

https://docs.docker.com/engine/reference/builder/#onbuild

class docked.RUN(first: str | list[str], *rest: str, mount: Mount | None = None, network: Literal['default', 'none', 'host'] = 'default', security: Literal['insecure', 'sandbox'] = 'sandbox', shell: bool = True)

Execute any commands in a new layer on top of the current image and commit the results.

https://docs.docker.com/engine/reference/builder/#run

class docked.SHELL(cmd: str | list[str])

Override the default shell used for the shell form of commands.

It affects shell form commands inside of RUN, CMD, and ENTRYPOINT instructions.

https://docs.docker.com/engine/reference/builder/#shell

class docked.USER(user: str | int, group: str | int | None = None)

Set the user name to use as the default user for the remainder of the stage.

https://docs.docker.com/engine/reference/builder/#user

class docked.WORKDIR(path: str | PosixPath)

Set the working directory for any RUN, CMD, ENTRYPOINT, COPY and ADD instructions that follow.

If the path doesn’t exist, it will be created.

https://docs.docker.com/engine/reference/builder/#workdir

Run steps

class docked.RunStep

Step that can be used in Stage.run.

These are steps that aren’t executed when building Image but rather affect how the container will be run.

class docked.CMD(cmd: str | list[str], shell: bool = False)

Provide defaults for an executing container.

https://docs.docker.com/engine/reference/builder/#cmd

class docked.ENTRYPOINT(cmd: str | list[str], shell: bool = False)

Configure a container that will run as an executable.

https://docs.docker.com/engine/reference/builder/#entrypoint

class docked.EXPOSE(port: int, protocol: Literal['tcp', 'udp'] = 'tcp')

Inform Docker that the container listens on the specified network ports at runtime.

The EXPOSE instruction does not actually publish the port. It functions as a type of documentation between the person who builds the image and the person who runs the container, about which ports are intended to be published.

https://docs.docker.com/engine/reference/builder/#expose

class docked.HEALTHCHECK(cmd: str | list[str] | None, *, interval: timedelta | str = '30s', timeout: timedelta | str = '30s', start_period: timedelta | str = '0s', retries: int = 3, shell: bool = False)

Check container health by running a command inside the container.

https://docs.docker.com/engine/reference/builder/#healthcheck

class docked.STOPSIGNAL(signal: str | int | Signals)

Sets the system call signal that will be sent to the container to exit.

https://docs.docker.com/engine/reference/builder/#stopsignal

class docked.VOLUME(*paths: str | PosixPath)

Create a mount point with the specified name and mark it as holding externally mounted volumes from native host or other containers.

https://docs.docker.com/engine/reference/builder/#volume

Other types

class docked.BaseImage(name: str, tag: str | None = None, digest: str | None = None)

Type representing a base image, like the ones you can find on Docker Hub.

It’s used in Stage to specify FROM, in COPY to specify --from and in some --mount types in RUN.

Parameters:

  • name – image name. For example, “python”.

  • tag – image tag. For example, “3.11-alpine”.

  • digest – the layer has of the image to use. You can find it on Docker Hub. Can’t be used together with tag, pick one.

class docked.BindMount(target: str | PosixPath, source: str | PosixPath | None = None, from_stage: Stage | BaseImage | None = None, allow_write: bool = False)

Allows binding directories (read-only) in the context or in an image.

Parameters:

  • target – Mount path.

  • source – Source path in the from_stage. Defaults to the root of the from.

  • from_stage – Stage or BaseImage for the root of the source. Defaults to the build context.

  • allow_write – Allow writes on the mount. Written data will be discarded.

https://docs.docker.com/engine/reference/builder/#run—mounttypebind

class docked.CacheMount(target: str | PosixPath, id: str | None = None, allow_write: bool = True, sharing: Literal['shared', 'private', 'locked'] = 'shared', from_stage: Stage | BaseImage | None = None, source: str | PosixPath | None = None, mode: int = 493, uid: int = 0, gid: int = 0)

Allows to cache directories for compilers and package managers.

https://docs.docker.com/engine/reference/builder/#run—mounttypecache

class docked.Checksum(hex: str, *, algorithm: Literal['sha256', 'sha384', 'sha512', 'blake3'] = 'sha256')

Hash of remote content for DOWNLOAD.

Parameters:

  • hex – base 16 representation of the hash value.

  • algorithm – the name of algorithm used to obtain the hash.

class docked.Mount

Create a mount that process running as part of the build can access.

This can be used to bind files from other part of the build without copying, accessing build secrets or ssh-agent sockets, or creating cache locations to speed up your build.

class docked.SecretMount(target: str | PosixPath | None = None, id: str | None = None, required: bool = False, mode: int = 256, uid: int = 0, gid: int = 0)

Allows to access secure files such as private keys without baking them into the image.

https://docs.docker.com/engine/reference/builder/#run—mounttypesecret

class docked.SSHMount(target: str | PosixPath | None = None, id: str = 'default', required: bool = False, mode: int = 384, uid: int = 0, gid: int = 0)

Allows to access SSH keys via SSH agents, with support for passphrases.

https://docs.docker.com/engine/reference/builder/#run—mounttypessh

Helpers

Collection of useful function that generate CLI commands for using inside of RUN.

The commands here are the ones that are the most often used in Docker images and require certain flags for producing safe and small images.

docked.cmd.apt_install(*pkgs: str) → str

Install system packages from Debian repositories.

docked.cmd.pip_install(*pkgs: str) → str

Install Python packages from pypi.org.