TestcontainerEx.Ryuk (testcontainer_ex v0.5.0)

Manages the Ryuk reaper container for automatic cleanup of test containers.

Ryuk is a sidecar container that watches for labeled containers and removes them when the test process exits. It is started during GenServer init and registered with a filter matching the current session.

Summary

Functions

privileged?(properties)

Returns whether Ryuk should run in privileged mode.

start(conn, session_id, properties, container_engine_host, docker_hostname)

Starts the Ryuk reaper and registers the session filter.

start_host_reaper(conn, session_id, properties)

Starts a host-based reaper that watches for labeled containers and removes them when the test process exits.

stop_host_reaper(session_id)

Stops the host-based reaper for a given session.

Functions

privileged?(properties)

@spec privileged?(map()) :: boolean()

Returns whether Ryuk should run in privileged mode.

Checks TESTCONTAINERS_RYUK_CONTAINER_PRIVILEGED env var first, then ryuk.container.privileged property. Values "true" and "1" are truthy. The env var takes precedence.

start(conn, session_id, properties, container_engine_host, docker_hostname)

@spec start(Req.Request.t(), String.t(), map(), String.t(), String.t()) ::
  {:ok} | {:error, term()}

Starts the Ryuk reaper and registers the session filter.

Returns {:ok} on success or {:error, reason} on failure. Ryuk failures are non-fatal — tests can still run without auto-cleanup.

start_host_reaper(conn, session_id, properties)

@spec start_host_reaper(Req.Request.t(), String.t(), map()) ::
  {:ok} | {:error, term()}

Starts a host-based reaper that watches for labeled containers and removes them when the test process exits.

On macOS with Colima/Docker Desktop, the Ryuk container can't reach the Docker daemon inside the VM. This function runs the reaper logic directly on the host process instead.

Returns {:ok} on success or {:error, reason} on failure.

stop_host_reaper(session_id)

Stops the host-based reaper for a given session.