docker

Documentation

Overview

Package docker is a Docker Engine API implementation of runtime.Runtime.

It uses github.com/moby/moby/client (the canonical post-split SDK path). We chose moby over github.com/docker/docker/client to favor the upstream module that the broader Go container ecosystem is converging on, avoiding two near-duplicate transitive trees when downstream consumers also depend on moby/moby/api.

All methods accept context.Context; streaming endpoints (PullImage, BuildImage, follow logs) are wrapped with runtime.CancellableCopy so ctx cancellation always returns within milliseconds.

Index

• type Options
• type Runtime
  • func New(ctx context.Context, opts Options) (*Runtime, error)
  • func (r *Runtime) BuildImage(ctx context.Context, spec runtime.BuildSpec, events chan<- runtime.BuildEvent) (runtime.ImageRef, error)
  • func (r *Runtime) Capabilities() runtime.Capabilities
  • func (r *Runtime) Close() error
  • func (r *Runtime) ComposeContainerID(ctx context.Context, spec runtime.ComposePsSpec, service string) (string, error)
  • func (r *Runtime) ComposeDown(ctx context.Context, spec runtime.ComposeDownSpec) error
  • func (r *Runtime) ComposeUp(ctx context.Context, spec runtime.ComposeUpSpec, ...) error
  • func (r *Runtime) ContainerLogs(ctx context.Context, id string, w io.Writer, follow bool) error
  • func (r *Runtime) CreateNetwork(ctx context.Context, spec runtime.NetworkSpec) (string, error)
  • func (r *Runtime) CreateVolume(ctx context.Context, spec runtime.VolumeSpec) (string, error)
  • func (r *Runtime) ExecContainer(ctx context.Context, id string, opts runtime.ExecOptions) (runtime.ExecResult, error)
  • func (r *Runtime) FindContainerByLabel(ctx context.Context, key, value string) (*runtime.Container, error)
  • func (r *Runtime) InspectContainer(ctx context.Context, id string) (*runtime.ContainerDetails, error)
  • func (r *Runtime) InspectImage(ctx context.Context, ref string) (*runtime.ImageDetails, error)
  • func (r *Runtime) ListContainers(ctx context.Context, filter runtime.LabelFilter) ([]runtime.Container, error)
  • func (r *Runtime) ListImages(ctx context.Context, filter runtime.LabelFilter) ([]runtime.ImageRef, error)
  • func (r *Runtime) PullImage(ctx context.Context, ref string, events chan<- runtime.BuildEvent) (runtime.ImageRef, error)
  • func (r *Runtime) RemoveContainer(ctx context.Context, id string, opts runtime.RemoveOptions) error
  • func (r *Runtime) RemoveImage(ctx context.Context, ref string) error
  • func (r *Runtime) RemoveNetwork(ctx context.Context, id string) error
  • func (r *Runtime) RemoveVolume(ctx context.Context, name string) error
  • func (r *Runtime) RunContainer(ctx context.Context, spec runtime.RunSpec) (*runtime.Container, error)
  • func (r *Runtime) StartContainer(ctx context.Context, id string) error
  • func (r *Runtime) StopContainer(ctx context.Context, id string, opts runtime.StopOptions) error

Types

type Options

type Options struct {
	// Host overrides DOCKER_HOST (e.g. "unix:///var/run/docker.sock"
	// or "tcp://192.168.0.1:2375"). Empty falls back to env.
	Host string
}

Options configure New. The zero value is valid: it builds a client that reads DOCKER_HOST/DOCKER_API_VERSION/etc. from the environment and negotiates the API version with the daemon.

type Runtime

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime is the Docker Engine implementation of runtime.Runtime (and runtime.ComposeRuntime).

func New

func New(ctx context.Context, opts Options) (*Runtime, error)

New constructs a Docker runtime. If the daemon is unreachable the returned error is a *runtime.DaemonUnavailableError.

func (*Runtime) BuildImage

func (r *Runtime) BuildImage(ctx context.Context, spec runtime.BuildSpec, events chan<- runtime.BuildEvent) (runtime.ImageRef, error)

BuildImage builds an image from a build context directory and tags it. Implements runtime.Runtime.BuildImage.

Streaming progress messages are mapped onto the events channel as runtime.BuildEvents (drop-on-full). Build failures surface as a non-nil error including any structured error returned by the daemon.

BuildKit is required. The classic builder synthesizes one intermediate container per Dockerfile step and routes every container API through the daemon's authorization pipeline, which — behind an authz plugin — turns a sub-second build into a multi-minute one (~140× slowdown observed in production). BuildKit uses a single streaming session and is unaffected. Docker Engine has shipped with BuildKit enabled by default since 23.0 (Feb 2023); requiring it here is in line with the lib's modern-spec stance.

func (*Runtime) Capabilities

func (r *Runtime) Capabilities() runtime.Capabilities

Capabilities advertises the docker backend's compose feature set. All flags true: docker has been the compose reference target since v2 shipped, so every gated feature is available.

func (*Runtime) Close

func (r *Runtime) Close() error

Close releases the underlying HTTP client. Safe to call multiple times.

func (*Runtime) ComposeContainerID

func (r *Runtime) ComposeContainerID(ctx context.Context, spec runtime.ComposePsSpec, service string) (string, error)

ComposeContainerID resolves the container id for a service via `docker compose ps -q <service>`. Returns "" if the service isn't running (compose returns empty stdout, exit 0).

func (*Runtime) ComposeDown

func (r *Runtime) ComposeDown(ctx context.Context, spec runtime.ComposeDownSpec) error

ComposeDown stops and (optionally) cleans the project.

func (*Runtime) ComposeUp

func (r *Runtime) ComposeUp(ctx context.Context, spec runtime.ComposeUpSpec, events chan<- runtime.BuildEvent) error

ComposeUp brings the project up in detached mode.

func (*Runtime) ContainerLogs

func (r *Runtime) ContainerLogs(ctx context.Context, id string, w io.Writer, follow bool) error

func (*Runtime) CreateNetwork

func (r *Runtime) CreateNetwork(ctx context.Context, spec runtime.NetworkSpec) (string, error)

CreateNetwork creates a docker network. Idempotent on (name, label match) — if a network with the same name already exists and its labels are a superset of ours, we return its ID without recreating. Different-label collisions surface as a typed error.

func (*Runtime) CreateVolume

func (r *Runtime) CreateVolume(ctx context.Context, spec runtime.VolumeSpec) (string, error)

CreateVolume creates a named docker volume. Idempotent on (name, label match) — same shape as CreateNetwork.

func (*Runtime) ExecContainer

func (r *Runtime) ExecContainer(ctx context.Context, id string, opts runtime.ExecOptions) (runtime.ExecResult, error)

func (*Runtime) FindContainerByLabel

func (r *Runtime) FindContainerByLabel(ctx context.Context, key, value string) (*runtime.Container, error)

func (*Runtime) InspectContainer

func (r *Runtime) InspectContainer(ctx context.Context, id string) (*runtime.ContainerDetails, error)

func (*Runtime) InspectImage

func (r *Runtime) InspectImage(ctx context.Context, ref string) (*runtime.ImageDetails, error)

func (*Runtime) ListContainers

func (r *Runtime) ListContainers(ctx context.Context, filter runtime.LabelFilter) ([]runtime.Container, error)

ListContainers returns containers matching every label in filter. Includes stopped containers — the orchestrator needs to find containers from prior Ups that may have exited.

func (*Runtime) ListImages

func (r *Runtime) ListImages(ctx context.Context, filter runtime.LabelFilter) ([]runtime.ImageRef, error)

ListImages returns local images matching every label in filter. Used by Down --rmi local: built images carry a project label so teardown can prune by label.

func (*Runtime) PullImage

func (r *Runtime) PullImage(ctx context.Context, ref string, events chan<- runtime.BuildEvent) (runtime.ImageRef, error)

func (*Runtime) RemoveContainer

func (r *Runtime) RemoveContainer(ctx context.Context, id string, opts runtime.RemoveOptions) error

func (*Runtime) RemoveImage

func (r *Runtime) RemoveImage(ctx context.Context, ref string) error

RemoveImage removes a local image by ID or reference. Force=false matches compose's `down --rmi local` semantics — refuse to remove images that still have running containers attached.

func (*Runtime) RemoveNetwork

func (r *Runtime) RemoveNetwork(ctx context.Context, id string) error

RemoveNetwork removes a network by ID. Missing-network errors are swallowed so callers can call this defensively at teardown.

func (*Runtime) RemoveVolume

func (r *Runtime) RemoveVolume(ctx context.Context, name string) error

RemoveVolume removes a named volume. Missing volumes are no-ops.

func (*Runtime) RunContainer

func (r *Runtime) RunContainer(ctx context.Context, spec runtime.RunSpec) (*runtime.Container, error)

func (*Runtime) StartContainer

func (r *Runtime) StartContainer(ctx context.Context, id string) error

func (*Runtime) StopContainer

func (r *Runtime) StopContainer(ctx context.Context, id string, opts runtime.StopOptions) error