testcontainer_dockerfile

Build custom Docker images from a Dockerfile and use them as typed formulas with testcontainer.

testcontainer is a container runner: it does not build images. This package fills the gap by shelling out to docker build and wrapping the resulting image in a Formula.

Types

DockerImage

opaque </>

The typed output yielded after a successful build + container start. Carries the running Container (so callers can use container.host_port, container.host, etc.) plus the built image ID.

pub opaque type DockerImage

DockerfileConfig

opaque </>

Opaque builder for a Dockerfile build configuration. Construct via new and refine with with_* builders.

pub opaque type DockerfileConfig

Values

container

</>

pub fn container(img: DockerImage) -> container.Container

Get the running Container so you can use container.host_port, container.host, container.mapped_url, etc.

default_timeout_ms

</>

pub const default_timeout_ms: Int

Default build timeout (10 minutes). Can be overridden via with_timeout.

formula

</>

pub fn formula(
  cfg: DockerfileConfig,
) -> Result(formula.Formula(DockerImage), error.Error)

Run docker build and return a Formula that wraps the resulting image. The build happens eagerly when this function is called.

On success, the returned Formula can be passed straight to testcontainer.with_formula (see the README for an end-to-end example).

Failure modes (error.Error variants):

DockerNotFound — the docker CLI is not on PATH
DockerfileNotFound(path) — the configured Dockerfile path is empty, contains invalid characters, points to a directory, or does not exist on disk
BuildFailed(path, reason) — docker build returned non-zero or invalid build-arg keys were rejected. reason carries full stdout+stderr for diagnostics

image_id

</>

pub fn image_id(img: DockerImage) -> String

Get the Docker image ID (e.g. sha256:abcd...) of a built image.

max_timeout_ms

</>

pub const max_timeout_ms: Int

Maximum allowed build timeout (1 hour). with_timeout clamps to this.

new

</>

pub fn new(dockerfile_path: String) -> DockerfileConfig

Start a new Dockerfile build configuration.

dockerfile_path should point to a readable Dockerfile, e.g. "./Dockerfile" or "docker/api.Dockerfile". The path is trimmed before being passed to docker build -f.

with_bind_mount

</>

pub fn with_bind_mount(
  cfg: DockerfileConfig,
  host_path: String,
  container_path: String,
) -> DockerfileConfig

Bind-mount a host path read-write into the container.

with_build_arg

</>

pub fn with_build_arg(
  cfg: DockerfileConfig,
  key: String,
  value: String,
) -> DockerfileConfig

Add a --build-arg flag passed to docker build. Use for ARG directives inside the Dockerfile.

Note: build args are visible in the host’s process list (ps aux) during the build window. Do not pass real secrets via build args; use with_secret_env for runtime secrets, or Docker BuildKit secret mounts for build-time secrets.

with_command

</>

pub fn with_command(
  cfg: DockerfileConfig,
  cmd: List(String),
) -> DockerfileConfig

Override the image’s CMD when running the container.

with_context

</>

pub fn with_context(
  cfg: DockerfileConfig,
  context_path: String,
) -> DockerfileConfig

Set the build context (sent to the Docker daemon as the build root). Defaults to the current directory (.).

with_entrypoint

</>

pub fn with_entrypoint(
  cfg: DockerfileConfig,
  ep: List(String),
) -> DockerfileConfig

Override the image’s ENTRYPOINT.

with_env

</>

pub fn with_env(
  cfg: DockerfileConfig,
  key: String,
  value: String,
) -> DockerfileConfig

Add an environment variable injected at container start. Overrides any ENV baked into the image.

with_envs

</>

pub fn with_envs(
  cfg: DockerfileConfig,
  pairs: List(#(String, String)),
) -> DockerfileConfig

Add many env vars at once.

with_expose_port

</>

pub fn with_expose_port(
  cfg: DockerfileConfig,
  p: port.Port,
) -> DockerfileConfig

Map a port that should be exposed when the container runs.

with_expose_ports

</>

pub fn with_expose_ports(
  cfg: DockerfileConfig,
  ports: List(port.Port),
) -> DockerfileConfig

Map several exposed ports at once.

with_extra_wait

</>

pub fn with_extra_wait(
  cfg: DockerfileConfig,
  extra: wait.WaitStrategy,
) -> DockerfileConfig

Combine an additional wait strategy with whatever is already configured using wait.all_of. Useful to layer e.g. wait.health_check() on top of a base port wait.

with_label

</>

pub fn with_label(
  cfg: DockerfileConfig,
  key: String,
  value: String,
) -> DockerfileConfig

Add a Docker label to the running container.

with_name

</>

pub fn with_name(
  cfg: DockerfileConfig,
  name: String,
) -> DockerfileConfig

Set a fixed container name.

with_network

</>

pub fn with_network(
  cfg: DockerfileConfig,
  network: String,
) -> DockerfileConfig

Attach the container to a Docker network by name.

with_privileged

</>

pub fn with_privileged(cfg: DockerfileConfig) -> DockerfileConfig

Run the container as privileged. Use with extreme caution: a privileged container has full access to host devices and can escape most isolation. Naming alone (with_privileged) is the security signal — there is no runtime warning.

with_readonly_bind

</>

pub fn with_readonly_bind(
  cfg: DockerfileConfig,
  host_path: String,
  container_path: String,
) -> DockerfileConfig

Bind-mount a host path read-only into the container.

with_secret_env

</>

pub fn with_secret_env(
  cfg: DockerfileConfig,
  key: String,
  secret: cowl.Secret(String),
) -> DockerfileConfig

Add an env var whose value is wrapped in cowl.Secret and never appears in string.inspect output.

with_timeout

</>

pub fn with_timeout(
  cfg: DockerfileConfig,
  ms: Int,
) -> DockerfileConfig

Override the default 10-minute build timeout. Clamped to the inclusive range [1000, max_timeout_ms].

with_tmpfs

</>

pub fn with_tmpfs(
  cfg: DockerfileConfig,
  container_path: String,
) -> DockerfileConfig

Mount an in-memory tmpfs at the given container path.

with_wait

</>

pub fn with_wait(
  cfg: DockerfileConfig,
  strategy: wait.WaitStrategy,
) -> DockerfileConfig

Set the wait strategy used after the container starts. Replaces any previous wait strategy.