Docker.Supervised (docker_wrapper v0.1.2)

Copy Markdown View Source

A GenServer wrapping the full container lifecycle under OTP supervision.

This is a BEAM-native extension not present in the Rust crate. It starts a Docker container in detached mode, monitors its health, and cleans up on termination.

Examples

# Start a supervised Redis container
{:ok, pid} = Docker.Supervised.start_link(
  Docker.Commands.Run.new("redis:7")
  |> Docker.Commands.Run.name("my-redis")
  |> Docker.Commands.Run.port(6379, 6379),
  health_interval: 5_000,
  rm_on_terminate: true
)

Docker.Supervised.container_id(pid)  #=> "abc123..."
Docker.Supervised.status(pid)        #=> :running
Docker.Supervised.healthy?(pid)      #=> :healthy

# Under a supervisor
children = [
  {Docker.Supervised, {run_cmd, name: MyApp.Redis, health_interval: 3_000}}
]
Supervisor.start_link(children, strategy: :one_for_one)

Options

  • :name - GenServer registration name
  • :health_check - whether to poll container health (default: true)
  • :health_interval - milliseconds between health checks (default: 5_000)
  • :rm_on_terminate - force-remove container on GenServer terminate (default: false)
  • :config - Docker.Config to use for all commands (default: Docker.Config.new())

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a child spec for use in supervisors.

container_id(pid)

Returns the container ID.

healthy?(pid)

Returns the container health status.

start_link(run_cmd, opts \\ [])

Starts a supervised container.

status(pid)

Returns the container status.

stop_container(pid, timeout \\ 30000)

Stops the container gracefully.

Types

t()

@type t() :: %Docker.Supervised{
  config: Docker.Config.t(),
  container_id: String.t() | nil,
  health: :starting | :healthy | :unhealthy | :unknown | :not_found,
  opts: keyword(),
  run_cmd: Docker.Commands.Run.t(),
  status: :running | :stopped | :failed
}

Functions

child_spec(init_arg)

Returns a child spec for use in supervisors.

Expects {run_cmd, opts} as the argument.

container_id(pid)

@spec container_id(GenServer.server()) :: String.t() | nil

Returns the container ID.

healthy?(pid)

@spec healthy?(GenServer.server()) :: atom()

Returns the container health status.

start_link(run_cmd, opts \\ [])

@spec start_link(
  Docker.Commands.Run.t(),
  keyword()
) :: GenServer.on_start()

Starts a supervised container.

Accepts a Docker.Commands.Run struct and options. The container is automatically started in detached mode.

status(pid)

@spec status(GenServer.server()) :: :running | :stopped | :failed

Returns the container status.

stop_container(pid, timeout \\ 30000)

@spec stop_container(GenServer.server(), timeout()) :: :ok

Stops the container gracefully.