Docker (docker_wrapper v0.1.2)

Copy Markdown View Source

A typed Elixir wrapper for the Docker CLI.

Provides functions for Docker operations by shelling out to the Docker binary. Each function accepts an options keyword list that can include a :config key with a Docker.Config struct to customize behavior.

All functions return {:ok, result} on success or {:error, reason} on failure. A non-zero exit code from Docker produces {:error, {stdout, exit_code}}.

Configuration

Pass a Docker.Config struct via the :config option to control the Docker binary, working directory, environment variables, and command timeout:

config = Docker.Config.new(
  binary: "/usr/local/bin/podman",
  timeout: 60_000
)

Docker.ps(config: config)

When :config is omitted, a default config is built from the environment: the binary is located via DOCKER_PATH or auto-detected on the PATH, and the timeout is 30 seconds.

Pipeline composition

Commands can be built using struct-based builders and executed via the facade functions:

import Docker.Commands.Run

"nginx:alpine"
|> new()
|> name("my-nginx")
|> port(8080, 80)
|> detach()
|> Docker.run()

Examples

Running a container

{:ok, container_id} = Docker.run(
  Docker.Commands.Run.new("nginx:alpine")
  |> Docker.Commands.Run.name("my-nginx")
  |> Docker.Commands.Run.detach()
)

Listing containers

{:ok, containers} = Docker.ps(all: true)

Stopping a container

{:ok, _} = Docker.stop("my-nginx")

Summary

Functions

build(cmd_or_context, opts \\ [])

Builds an image from a Dockerfile.

compose_build(cmd \\ %Commands.Compose.Build{}, opts \\ [])

Runs docker compose build.

compose_config(cmd \\ %Commands.Compose.Config{}, opts \\ [])

Runs docker compose config.

compose_down(cmd \\ %Commands.Compose.Down{}, opts \\ [])

Runs docker compose down.

compose_exec(cmd, opts \\ [])

Runs docker compose exec.

compose_logs(cmd, opts \\ [])

Runs docker compose logs.

compose_ps(cmd \\ %Commands.Compose.Ps{}, opts \\ [])

Runs docker compose ps.

compose_run(cmd, opts \\ [])

Runs docker compose run.

compose_up(cmd, opts \\ [])

Runs docker compose up.

container_prune(cmd_or_opts \\ [])

Removes all stopped containers.

create(cmd_or_image, opts \\ [])

Creates a container without starting it.

exec_cmd(cmd, opts \\ [])

Executes a command in a running container.

generic(cmd, opts \\ [])

Runs an arbitrary Docker command via the escape hatch.

history(cmd_or_image, opts \\ [])

Shows the history of an image.

image_prune(cmd_or_opts \\ [])

Removes unused images.

images(cmd_or_opts \\ [])

Lists images.

import_image(cmd, opts \\ [])

Imports a tarball to create a filesystem image.

info(opts \\ [])

Runs docker info.

inspect_cmd(cmd_or_target, opts \\ [])

Inspects one or more Docker objects (containers, images, networks, volumes).

kill(cmd_or_container, opts \\ [])

Kills one or more running containers.

load(cmd, opts \\ [])

Loads an image from a tar archive.

logs(cmd_or_container, opts \\ [])

Gets logs from a container.

network_connect(cmd, opts \\ [])

Connects a container to a network.

network_create(cmd_or_name, opts \\ [])

Creates a network.

network_disconnect(cmd, opts \\ [])

Disconnects a container from a network.

network_inspect(cmd_or_name, opts \\ [])

Inspects one or more networks.

network_ls(cmd_or_opts \\ [])

Lists networks.

network_prune(cmd_or_opts \\ [])

Removes all unused networks.

network_rm(cmd_or_name, opts \\ [])

Removes one or more networks.

pause(cmd_or_container, opts \\ [])

Pauses one or more containers.

ps(cmd_or_opts \\ [])

Lists containers.

pull(cmd_or_image, opts \\ [])

Pulls an image.

push(cmd_or_image, opts \\ [])

Pushes an image.

restart(cmd_or_container, opts \\ [])

Restarts one or more containers.

rm(cmd_or_container, opts \\ [])

Removes one or more containers.

rmi(cmd_or_image, opts \\ [])

Removes one or more images.

run(cmd_or_image, opts \\ [])

Runs a container from the given command struct or image name.

save(cmd, opts \\ [])

Saves one or more images to a tar archive.

search(cmd_or_term, opts \\ [])

Searches Docker Hub for images.

start(cmd_or_container, opts \\ [])

Starts one or more stopped containers.

stop(cmd_or_container, opts \\ [])

Stops one or more running containers.

system_df(cmd_or_opts \\ [])

Runs docker system df.

system_prune(cmd_or_opts \\ [])

Runs docker system prune.

tag(source, target, opts \\ [])

Tags an image.

unpause(cmd_or_container, opts \\ [])

Unpauses one or more containers.

version(opts \\ [])

Runs docker version.

volume_create(cmd_or_name \\ %Commands.Volume.Create{}, opts \\ [])

Creates a volume.

volume_inspect(cmd_or_name, opts \\ [])

Inspects one or more volumes.

volume_ls(cmd_or_opts \\ [])

Lists volumes.

volume_prune(cmd_or_opts \\ [])

Removes all unused volumes.

volume_rm(cmd_or_name, opts \\ [])

Removes one or more volumes.

Functions

build(cmd_or_context, opts \\ [])

@spec build(
  Docker.Commands.Build.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Builds an image from a Dockerfile.

compose_build(cmd \\ %Commands.Compose.Build{}, opts \\ [])

@spec compose_build(
  Docker.Commands.Compose.Build.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Runs docker compose build.

compose_config(cmd \\ %Commands.Compose.Config{}, opts \\ [])

@spec compose_config(
  Docker.Commands.Compose.Config.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Runs docker compose config.

compose_down(cmd \\ %Commands.Compose.Down{}, opts \\ [])

@spec compose_down(
  Docker.Commands.Compose.Down.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Runs docker compose down.

compose_exec(cmd, opts \\ [])

@spec compose_exec(
  Docker.Commands.Compose.Exec.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Runs docker compose exec.

compose_logs(cmd, opts \\ [])

@spec compose_logs(
  Docker.Commands.Compose.Logs.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Runs docker compose logs.

compose_ps(cmd \\ %Commands.Compose.Ps{}, opts \\ [])

@spec compose_ps(
  Docker.Commands.Compose.Ps.t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Runs docker compose ps.

compose_run(cmd, opts \\ [])

@spec compose_run(
  Docker.Commands.Compose.Run.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Runs docker compose run.

compose_up(cmd, opts \\ [])

@spec compose_up(
  Docker.Commands.Compose.Up.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Runs docker compose up.

container_prune(cmd_or_opts \\ [])

@spec container_prune(Docker.Commands.ContainerPrune.t() | keyword()) ::
  {:ok, String.t()} | {:error, term()}

Removes all stopped containers.

create(cmd_or_image, opts \\ [])

@spec create(
  Docker.Commands.Create.t() | String.t(),
  keyword()
) :: {:ok, Docker.ContainerId.t()} | {:error, term()}

Creates a container without starting it.

exec_cmd(cmd, opts \\ [])

@spec exec_cmd(
  Docker.Commands.Exec.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Executes a command in a running container.

generic(cmd, opts \\ [])

@spec generic(
  Docker.Commands.Generic.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Runs an arbitrary Docker command via the escape hatch.

Examples

Docker.generic(Docker.Commands.Generic.new(["system", "events"]))

history(cmd_or_image, opts \\ [])

@spec history(
  Docker.Commands.History.t() | String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Shows the history of an image.

image_prune(cmd_or_opts \\ [])

@spec image_prune(Docker.Commands.ImagePrune.t() | keyword()) ::
  {:ok, String.t()} | {:error, term()}

Removes unused images.

images(cmd_or_opts \\ [])

@spec images(Docker.Commands.Images.t() | keyword()) ::
  {:ok, [map()]} | {:error, term()}

Lists images.

Options

  • :all - show all images including intermediates
  • :config - a Docker.Config struct

import_image(cmd, opts \\ [])

@spec import_image(
  Docker.Commands.Import.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Imports a tarball to create a filesystem image.

info(opts \\ [])

@spec info(keyword()) :: {:ok, term()} | {:error, term()}

Runs docker info.

inspect_cmd(cmd_or_target, opts \\ [])

@spec inspect_cmd(
  Docker.Commands.Inspect.t() | String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Inspects one or more Docker objects (containers, images, networks, volumes).

Returns parsed JSON as a list of maps.

kill(cmd_or_container, opts \\ [])

@spec kill(
  Docker.Commands.Kill.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Kills one or more running containers.

load(cmd, opts \\ [])

@spec load(
  Docker.Commands.Load.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Loads an image from a tar archive.

logs(cmd_or_container, opts \\ [])

@spec logs(
  Docker.Commands.Logs.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Gets logs from a container.

network_connect(cmd, opts \\ [])

@spec network_connect(
  Docker.Commands.Network.Connect.t(),
  keyword()
) :: {:ok, :done} | {:error, term()}

Connects a container to a network.

network_create(cmd_or_name, opts \\ [])

@spec network_create(
  Docker.Commands.Network.Create.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Creates a network.

network_disconnect(cmd, opts \\ [])

@spec network_disconnect(
  Docker.Commands.Network.Disconnect.t(),
  keyword()
) :: {:ok, :done} | {:error, term()}

Disconnects a container from a network.

network_inspect(cmd_or_name, opts \\ [])

@spec network_inspect(
  Docker.Commands.Network.Inspect.t() | String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Inspects one or more networks.

network_ls(cmd_or_opts \\ [])

@spec network_ls(Docker.Commands.Network.Ls.t() | keyword()) ::
  {:ok, [map()]} | {:error, term()}

Lists networks.

network_prune(cmd_or_opts \\ [])

@spec network_prune(Docker.Commands.Network.Prune.t() | keyword()) ::
  {:ok, String.t()} | {:error, term()}

Removes all unused networks.

network_rm(cmd_or_name, opts \\ [])

@spec network_rm(
  Docker.Commands.Network.Rm.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Removes one or more networks.

pause(cmd_or_container, opts \\ [])

@spec pause(
  Docker.Commands.Pause.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Pauses one or more containers.

ps(cmd_or_opts \\ [])

@spec ps(Docker.Commands.Ps.t() | keyword()) :: {:ok, [map()]} | {:error, term()}

Lists containers.

Options

  • :all - show all containers (default: only running)
  • :config - a Docker.Config struct

pull(cmd_or_image, opts \\ [])

@spec pull(
  Docker.Commands.Pull.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Pulls an image.

push(cmd_or_image, opts \\ [])

@spec push(
  Docker.Commands.Push.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Pushes an image.

restart(cmd_or_container, opts \\ [])

@spec restart(
  Docker.Commands.Restart.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Restarts one or more containers.

rm(cmd_or_container, opts \\ [])

@spec rm(
  Docker.Commands.Rm.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Removes one or more containers.

rmi(cmd_or_image, opts \\ [])

@spec rmi(
  Docker.Commands.Rmi.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Removes one or more images.

run(cmd_or_image, opts \\ [])

@spec run(
  Docker.Commands.Run.t() | String.t(),
  keyword()
) :: {:ok, Docker.ContainerId.t()} | {:error, term()}

Runs a container from the given command struct or image name.

When passed a Docker.Commands.Run struct, executes it directly. When passed a string, creates a basic run command for that image.

save(cmd, opts \\ [])

@spec save(
  Docker.Commands.Save.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Saves one or more images to a tar archive.

search(cmd_or_term, opts \\ [])

@spec search(
  Docker.Commands.Search.t() | String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Searches Docker Hub for images.

start(cmd_or_container, opts \\ [])

@spec start(
  Docker.Commands.Start.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Starts one or more stopped containers.

stop(cmd_or_container, opts \\ [])

@spec stop(
  Docker.Commands.Stop.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Stops one or more running containers.

system_df(cmd_or_opts \\ [])

@spec system_df(Docker.Commands.System.Df.t() | keyword()) ::
  {:ok, String.t()} | {:error, term()}

Runs docker system df.

system_prune(cmd_or_opts \\ [])

@spec system_prune(Docker.Commands.System.Prune.t() | keyword()) ::
  {:ok, String.t()} | {:error, term()}

Runs docker system prune.

tag(source, target, opts \\ [])

@spec tag(String.t(), String.t(), keyword()) :: {:ok, :done} | {:error, term()}

Tags an image.

unpause(cmd_or_container, opts \\ [])

@spec unpause(
  Docker.Commands.Unpause.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Unpauses one or more containers.

version(opts \\ [])

@spec version(keyword()) :: {:ok, term()} | {:error, term()}

Runs docker version.

volume_create(cmd_or_name \\ %Commands.Volume.Create{}, opts \\ [])

@spec volume_create(
  Docker.Commands.Volume.Create.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Creates a volume.

volume_inspect(cmd_or_name, opts \\ [])

@spec volume_inspect(
  Docker.Commands.Volume.Inspect.t() | String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Inspects one or more volumes.

volume_ls(cmd_or_opts \\ [])

@spec volume_ls(Docker.Commands.Volume.Ls.t() | keyword()) ::
  {:ok, [map()]} | {:error, term()}

Lists volumes.

volume_prune(cmd_or_opts \\ [])

@spec volume_prune(Docker.Commands.Volume.Prune.t() | keyword()) ::
  {:ok, String.t()} | {:error, term()}

Removes all unused volumes.

volume_rm(cmd_or_name, opts \\ [])

@spec volume_rm(
  Docker.Commands.Volume.Rm.t() | String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Removes one or more volumes.