# `Docker`
[🔗](https://github.com/joshrotenberg/docker_wrapper_ex/blob/v0.1.2/lib/docker.ex#L1)

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")

# `build`

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

Builds an image from a Dockerfile.

# `compose_build`

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

Runs `docker compose build`.

# `compose_config`

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

Runs `docker compose config`.

# `compose_down`

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

Runs `docker compose down`.

# `compose_exec`

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

Runs `docker compose exec`.

# `compose_logs`

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

Runs `docker compose logs`.

# `compose_ps`

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

Runs `docker compose ps`.

# `compose_run`

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

Runs `docker compose run`.

# `compose_up`

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

Runs `docker compose up`.

# `container_prune`

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

Removes all stopped containers.

# `create`

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

Creates a container without starting it.

# `exec_cmd`

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

Executes a command in a running container.

# `generic`

```elixir
@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`

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

Shows the history of an image.

# `image_prune`

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

Removes unused images.

# `images`

```elixir
@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`

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

Imports a tarball to create a filesystem image.

# `info`

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

Runs `docker info`.

# `inspect_cmd`

```elixir
@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`

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

Kills one or more running containers.

# `load`

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

Loads an image from a tar archive.

# `logs`

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

Gets logs from a container.

# `network_connect`

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

Connects a container to a network.

# `network_create`

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

Creates a network.

# `network_disconnect`

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

Disconnects a container from a network.

# `network_inspect`

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

Inspects one or more networks.

# `network_ls`

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

Lists networks.

# `network_prune`

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

Removes all unused networks.

# `network_rm`

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

Removes one or more networks.

# `pause`

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

Pauses one or more containers.

# `ps`

```elixir
@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`

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

Pulls an image.

# `push`

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

Pushes an image.

# `restart`

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

Restarts one or more containers.

# `rm`

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

Removes one or more containers.

# `rmi`

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

Removes one or more images.

# `run`

```elixir
@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`

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

Saves one or more images to a tar archive.

# `search`

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

Searches Docker Hub for images.

# `start`

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

Starts one or more stopped containers.

# `stop`

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

Stops one or more running containers.

# `system_df`

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

Runs `docker system df`.

# `system_prune`

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

Runs `docker system prune`.

# `tag`

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

Tags an image.

# `unpause`

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

Unpauses one or more containers.

# `version`

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

Runs `docker version`.

# `volume_create`

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

Creates a volume.

# `volume_inspect`

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

Inspects one or more volumes.

# `volume_ls`

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

Lists volumes.

# `volume_prune`

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

Removes all unused volumes.

# `volume_rm`

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

Removes one or more volumes.

---

*Consult [api-reference.md](api-reference.md) for complete listing*