Add Docker Compose support

Introduces Docker Compose file support via CLI subprocess, enabling
multi-service test environments from docker-compose.yml files.

New modules:
- DockerCompose: builder struct for compose configuration
- Compose.Cli: subprocess wrapper for docker compose commands
- Compose.ComposeService: lightweight service representation
- Compose.ComposeEnvironment: started state with service accessors

Integration with existing GenServer (start_compose/stop_compose) and
ExUnit (compose/3 macro) following established patterns. Supports
per-service wait strategies by bridging to existing WaitStrategy protocol.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jarlah

lib/compose/cli.ex

@@ -0,0 +1,212 @@
+defmodule Testcontainers.Compose.Cli do
+  @moduledoc """
+  Subprocess wrapper for Docker Compose CLI interaction.
+  """
+
+  require Logger
+
+  alias Testcontainers.DockerCompose
+
+  @doc """
+  Runs `docker compose up -d --wait` with the given compose configuration.
+  """
+  def up(%DockerCompose{} = compose) do
+    args = build_up_args(compose)
+
+    case execute(compose, args) do
+      {_output, 0} -> :ok
+      {output, exit_code} -> {:error, {:compose_up_failed, exit_code, output}}
+    end
+  end
+
+  @doc """
+  Runs `docker compose down` with the given compose configuration.
+  """
+  def down(%DockerCompose{} = compose) do
+    args = build_down_args(compose)
+
+    case execute(compose, args) do
+      {_output, 0} -> :ok
+      {output, exit_code} -> {:error, {:compose_down_failed, exit_code, output}}
+    end
+  end
+
+  @doc """
+  Runs `docker compose ps --format=json` and parses the output into a list of maps.
+  """
+  def ps(%DockerCompose{} = compose) do
+    args = build_ps_args(compose)
+
+    case execute(compose, args) do
+      {output, 0} -> {:ok, parse_ps_output(output)}
+      {output, exit_code} -> {:error, {:compose_ps_failed, exit_code, output}}
+    end
+  end
+
+  @doc """
+  Runs `docker compose pull` with the given compose configuration.
+  """
+  def pull(%DockerCompose{} = compose) do
+    args = build_pull_args(compose)
+
+    case execute(compose, args) do
+      {_output, 0} -> :ok
+      {output, exit_code} -> {:error, {:compose_pull_failed, exit_code, output}}
+    end
+  end
+
+  @doc """
+  Runs `docker compose logs <service>` and returns the output.
+  """
+  def logs(%DockerCompose{} = compose, service_name) when is_binary(service_name) do
+    args = build_logs_args(compose, service_name)
+
+    case execute(compose, args) do
+      {output, 0} -> {:ok, output}
+      {output, exit_code} -> {:error, {:compose_logs_failed, exit_code, output}}
+    end
+  end
+
+  # Command building functions - public for testability
+
+  @doc """
+  Builds the argument list for `docker compose up`.
+  """
+  def build_up_args(%DockerCompose{} = compose) do
+    base_args(compose) ++ ["up", "-d", "--wait"] ++ build_args(compose) ++ compose.services
+  end
+
+  @doc """
+  Builds the argument list for `docker compose down`.
+  """
+  def build_down_args(%DockerCompose{} = compose) do
+    args = base_args(compose) ++ ["down"]
+
+    if compose.remove_volumes do
+      args ++ ["-v"]
+    else
+      args
+    end
+  end
+
+  @doc """
+  Builds the argument list for `docker compose ps`.
+  """
+  def build_ps_args(%DockerCompose{} = compose) do
+    base_args(compose) ++ ["ps", "--format=json"]
+  end
+
+  @doc """
+  Builds the argument list for `docker compose pull`.
+  """
+  def build_pull_args(%DockerCompose{} = compose) do
+    base_args(compose) ++ ["pull"]
+  end
+
+  @doc """
+  Builds the argument list for `docker compose logs`.
+  """
+  def build_logs_args(%DockerCompose{} = compose, service_name) do
+    base_args(compose) ++ ["logs", service_name]
+  end
+
+  @doc """
+  Parses the JSON output from `docker compose ps`.
+
+  Each line is a separate JSON object with fields like Service, ID, State, Publishers.
+  """
+  def parse_ps_output(output) when is_binary(output) do
+    output
+    |> String.trim()
+    |> String.split("\n", trim: true)
+    |> Enum.flat_map(fn line ->
+      case Jason.decode(line) do
+        {:ok, %{} = parsed} ->
+          [parsed]
+
+        {:ok, list} when is_list(list) ->
+          list
+
+        {:error, _} ->
+          []
+      end
+    end)
+  end
+
+  @doc """
+  Parses the Publishers field from a `docker compose ps` JSON entry
+  into a list of `{container_port, host_port}` tuples.
+  """
+  def parse_publishers(nil), do: []
+  def parse_publishers([]), do: []
+
+  def parse_publishers(publishers) when is_list(publishers) do
+    publishers
+    |> Enum.filter(fn pub ->
+      published = Map.get(pub, "PublishedPort", 0)
+      published != 0
+    end)
+    |> Enum.map(fn pub ->
+      target = Map.get(pub, "TargetPort", 0)
+      published = Map.get(pub, "PublishedPort", 0)
+      {target, published}
+    end)
+    |> Enum.uniq()
+  end
+
+  # Private functions
+
+  defp base_args(%DockerCompose{} = compose) do
+    args = ["compose"]
+
+    args =
+      if compose.project_name do
+        args ++ ["-p", compose.project_name]
+      else
+        args
+      end
+
+    args =
+      Enum.reduce(compose.compose_files, args, fn file, acc ->
+        acc ++ ["-f", file]
+      end)
+
+    Enum.reduce(compose.profiles, args, fn profile, acc ->
+      acc ++ ["--profile", profile]
+    end)
+  end
+
+  defp build_args(%DockerCompose{} = compose) do
+    args = []
+
+    args =
+      if compose.build do
+        args ++ ["--build"]
+      else
+        args
+      end
+
+    case compose.pull do
+      :always -> args ++ ["--pull", "always"]
+      :never -> args ++ ["--pull", "never"]
+      :missing -> args
+    end
+  end
+
+  defp execute(%DockerCompose{} = compose, args) do
+    dir = resolve_directory(compose.filepath)
+    env_vars = Enum.map(compose.env, fn {k, v} -> {to_string(k), to_string(v)} end)
+
+    Logger.debug("Running: docker #{Enum.join(args, " ")} in #{dir}")
+
+    System.cmd("docker", args, cd: dir, env: env_vars, stderr_to_stdout: true)
+  end
+
+  defp resolve_directory(filepath) do
+    if File.dir?(filepath) do
+      filepath
+    else
+      Path.dirname(filepath)
+    end
+  end
+end

lib/compose/compose_environment.ex

@@ -0,0 +1,34 @@
+defmodule Testcontainers.Compose.ComposeEnvironment do
+  @moduledoc """
+  Represents the started state of a Docker Compose environment.
+  """
+
+  alias Testcontainers.Compose.ComposeService
+
+  defstruct [:compose, :project_name, :docker_host, services: %{}]
+
+  @doc """
+  Returns the service struct for the given service name.
+  """
+  def get_service(%__MODULE__{} = env, service_name) when is_binary(service_name) do
+    Map.get(env.services, service_name)
+  end
+
+  @doc """
+  Returns the docker host for a service.
+  """
+  def get_service_host(%__MODULE__{} = env, _service_name) do
+    env.docker_host
+  end
+
+  @doc """
+  Returns the mapped host port for a service and container port.
+  """
+  def get_service_port(%__MODULE__{} = env, service_name, port)
+      when is_binary(service_name) and is_integer(port) do
+    case get_service(env, service_name) do
+      nil -> nil
+      service -> ComposeService.mapped_port(service, port)
+    end
+  end
+end

lib/compose/compose_service.ex

@@ -0,0 +1,23 @@
+defmodule Testcontainers.Compose.ComposeService do
+  @moduledoc """
+  A lightweight struct representing a service within a Docker Compose environment.
+  """
+
+  defstruct [
+    :service_name,
+    :container_id,
+    :state,
+    exposed_ports: []
+  ]
+
+  @doc """
+  Returns the mapped host port for the given container port.
+  """
+  def mapped_port(%__MODULE__{} = service, port) when is_integer(port) do
+    service.exposed_ports
+    |> Enum.find_value(nil, fn
+      {^port, host_port} -> host_port
+      _ -> nil
+    end)
+  end
+end

lib/compose/docker_compose.ex

@@ -0,0 +1,121 @@
+defmodule Testcontainers.DockerCompose do
+  @moduledoc """
+  A struct with builder functions for creating a Docker Compose configuration.
+  """
+
+  defstruct [
+    :filepath,
+    compose_files: [],
+    project_name: nil,
+    env: %{},
+    wait_strategies: %{},
+    wait_timeout: 120_000,
+    pull: :missing,
+    services: [],
+    build: false,
+    profiles: [],
+    remove_volumes: true
+  ]
+
+  @doc """
+  Creates a new DockerCompose configuration.
+
+  The `filepath` can be a path to a directory containing a docker-compose.yml file,
+  or a path to a specific compose file.
+  """
+  def new(filepath) when is_binary(filepath) do
+    %__MODULE__{
+      filepath: filepath,
+      project_name: generate_project_name()
+    }
+  end
+
+  @doc """
+  Sets an environment variable for the compose environment.
+  """
+  def with_env(%__MODULE__{} = config, key, value)
+      when (is_binary(key) or is_atom(key)) and is_binary(value) do
+    %__MODULE__{config | env: Map.put(config.env, to_string(key), value)}
+  end
+
+  @doc """
+  Sets a wait strategy for a specific service.
+  """
+  def with_wait_strategy(%__MODULE__{} = config, service_name, wait_strategy)
+      when is_binary(service_name) and is_struct(wait_strategy) do
+    strategies = Map.get(config.wait_strategies, service_name, [])
+
+    %__MODULE__{
+      config
+      | wait_strategies:
+          Map.put(config.wait_strategies, service_name, [wait_strategy | strategies])
+    }
+  end
+
+  @doc """
+  Sets the specific services to start. If empty, all services are started.
+  """
+  def with_services(%__MODULE__{} = config, services) when is_list(services) do
+    %__MODULE__{config | services: services}
+  end
+
+  @doc """
+  Sets whether to build images before starting containers.
+  """
+  def with_build(%__MODULE__{} = config, build) when is_boolean(build) do
+    %__MODULE__{config | build: build}
+  end
+
+  @doc """
+  Adds a profile to enable when starting compose.
+  """
+  def with_profile(%__MODULE__{} = config, profile) when is_binary(profile) do
+    %__MODULE__{config | profiles: [profile | config.profiles]}
+  end
+
+  @doc """
+  Sets the pull policy for compose services.
+  """
+  def with_pull(%__MODULE__{} = config, pull) when pull in [:always, :missing, :never] do
+    %__MODULE__{config | pull: pull}
+  end
+
+  @doc """
+  Sets whether to remove volumes when stopping compose.
+  """
+  def with_remove_volumes(%__MODULE__{} = config, remove_volumes)
+      when is_boolean(remove_volumes) do
+    %__MODULE__{config | remove_volumes: remove_volumes}
+  end
+
+  @doc """
+  Sets the wait timeout in milliseconds.
+  """
+  def with_wait_timeout(%__MODULE__{} = config, timeout)
+      when is_integer(timeout) and timeout > 0 do
+    %__MODULE__{config | wait_timeout: timeout}
+  end
+
+  @doc """
+  Sets the project name for the compose environment.
+  """
+  def with_project_name(%__MODULE__{} = config, project_name) when is_binary(project_name) do
+    %__MODULE__{config | project_name: project_name}
+  end
+
+  @doc """
+  Adds additional compose files to use with the -f flag.
+  """
+  def with_compose_file(%__MODULE__{} = config, file) when is_binary(file) do
+    %__MODULE__{config | compose_files: config.compose_files ++ [file]}
+  end
+
+  defp generate_project_name do
+    hex =
+      :crypto.strong_rand_bytes(8)
+      |> Base.encode16(case: :lower)
+      |> binary_part(0, 12)
+
+    "tc-#{hex}"
+  end
+end