TestcontainerEx.Engine (testcontainer_ex v0.7.0)

Copy Markdown View Source

Detects which container engine is in use: Docker, Podman, minikube, or Apple Container.

Precedence

  1. Runtime override — set via set_engine/1 (highest priority, per-process).
  2. CONTAINER_ENGINE env var — explicit selection (docker, podman, colima, minikube, apple_container). When set, auto-detection is skipped entirely.
  3. CONTAINER_ENGINE_HOST / CONTAINER_HOST env vars — if the URL contains podman or matches minikube subnets, the engine is inferred from the URL.
  4. MINIKUBE_ACTIVE_DOCKERD / MINIKUBE_PROFILE env vars.
  5. Apple Container — only when the container binary exists, the service reports "running", and the API socket exists.
  6. Podman ping — HTTP ping to the daemon checking for a Podman header.
  7. Default — :docker.

Runtime engine selection

You can override the auto-detected engine at runtime:

TestcontainerEx.set_engine(:podman)
TestcontainerEx.container_engine() # => :podman

To reset back to auto-detection:

TestcontainerEx.clear_engine()

The override is stored per-process in the process dictionary, so it does not affect other processes and is cleaned up automatically when the calling process exits.

Summary

Functions

apple_container?()

Returns true when running with Apple Container.

clear_engine()

Clears a runtime engine override, restoring auto-detection.

detect()

Detects the container engine type.

minikube?()

Returns true when running in a minikube environment.

podman?()

Returns true when running with Podman.

runtime_override()

Returns the runtime override for the calling process, or nil if no override has been set.

set_engine(engine)

Overrides the auto-detected engine at runtime.

Functions

apple_container?()

@spec apple_container?() :: boolean()

Returns true when running with Apple Container.

clear_engine()

@spec clear_engine() :: :ok

Clears a runtime engine override, restoring auto-detection.

Also clears the :persistent_term cache so the next detect/0 call re-runs the full auto-detection sequence.

Examples

iex> TestcontainerEx.clear_engine()
:ok

detect()

@spec detect() :: :docker | :podman | :minikube | :apple_container

Detects the container engine type.

Returns one of:

  • :apple_container — Apple Container runtime
  • :podman — Podman
  • :minikube — Minikube
  • :docker — Docker (default)

Resolution order:

  1. Runtime override (set via set_engine/1) — per-process, highest priority
  2. Cached auto-detection result (stored in :persistent_term)
  3. Fresh auto-detection (cached for subsequent calls)

When CONTAINER_ENGINE env var is set to a valid engine, auto-detection is skipped entirely and that value is used directly.

minikube?()

@spec minikube?() :: boolean()

Returns true when running in a minikube environment.

podman?()

@spec podman?() :: boolean()

Returns true when running with Podman.

runtime_override()

@spec runtime_override() ::
  :docker | :podman | :colima | :minikube | :apple_container | nil

Returns the runtime override for the calling process, or nil if no override has been set.

set_engine(engine)

@spec set_engine(:docker | :podman | :colima | :minikube | :apple_container) :: :ok

Overrides the auto-detected engine at runtime.

The override is stored in the calling process's dictionary, so it:

  • Takes precedence over CONTAINER_ENGINE env var and auto-detection
  • Only affects the calling process (and its children via Process.info/1 inheritance)
  • Is cleaned up automatically when the process exits

Examples

iex> TestcontainerEx.set_engine(:podman)
:ok
iex> TestcontainerEx.container_engine()
:podman