Docker Compose

Docker Compose is Docker’s official tool for defining and running multi-container applications. A single compose.yaml file describes every service, network, and volume an application needs, and the docker compose CLI plugin turns that definition into running containers with commands like up, down, build, scale, logs, and exec. It replaced the legacy Python implementation with a Go rewrite that talks directly to the Docker Engine API and delegates builds to BuildKit/Buildx, while staying aligned with the community-governed Compose Specification via the compose-spec/compose-go parser.

Beyond the CLI, the project ships pkg/api and pkg/compose as an importable Go SDK, so other tools can load, validate, and manage Compose projects programmatically instead of shelling out to the binary. It is one of the most widely used developer tools in the container ecosystem, underpinning local development environments, CI test fixtures, and small-scale production deployments alike.

What You Get

• A declarative compose.yaml format for services, networks, volumes, and dependencies, validated against the open Compose Specification
• A full lifecycle CLI (up, down, build, pull, push, scale, logs, exec, restart, watch, and more) as a native docker compose plugin
• A Go SDK (pkg/api, pkg/compose) for embedding project loading and orchestration logic into custom tooling
• BuildKit/Buildx-powered image builds with caching, multi-platform support, and Bake integration
• A compose watch mode that rebuilds and syncs services automatically as source files change
• Docker Desktop integration and OpenTelemetry-based tracing for observability into compose operations

Common Use Cases

• Spinning up local development environments with an app, database, and supporting services in one command
• Provisioning ephemeral service dependencies (databases, brokers) inside CI pipelines for integration tests
• Running small-team production or staging stacks on a single host or Docker Swarm without a full Kubernetes cluster
• Embedding Compose’s project-loading and lifecycle APIs into internal deployment or platform tooling

Under The Hood

Architecture The CLI entry point in cmd/main.go wires up a Cobra-style command tree under cmd/compose (one file per subcommand — up.go, down.go, build.go, exec.go, and dozens more), which calls into pkg/compose’s composeService — the concrete implementation of the pkg/api.Service interface. That service loads and validates projects through compose-spec/compose-go/v2 types, talks to the Docker Engine over moby/moby/client, and delegates image builds to BuildKit. Cross-cutting concerns are layered in cleanly: internal/tracing wraps every operation in OpenTelemetry spans, internal/desktop bridges to Docker Desktop when present, and pkg/dryrun intercepts calls for dry-run mode. The separation between pkg/api (contracts) and pkg/compose (implementation) is deliberate — it’s what lets the same orchestration logic be driven by the CLI, by the Go SDK, or by dry-run tooling without duplication.

Tech Stack Written in modern Go (module targeting Go 1.26) with Cobra-flavored command wiring, compose-spec/compose-go/v2 for spec parsing, docker/cli and moby/moby/client for engine communication, and moby/buildkit/containerd for image builds. Structured logging goes through logrus, tracing through OpenTelemetry, and process orchestration through errgroup and clockwork for testable timing. CI (.github/workflows/ci.yml) runs linting, go.mod validation, doc validation, and mock validation as separate matrix jobs, then builds release binaries via a shared Bake workflow.

Code Quality The repository carries an extensive test suite (over 100 _test.go files) exercised with testify-style assertions, enforced by a testifylint linter rule. golangci-lint is configured with errcheck, errorlint, gocognit (deliberately preferred over gocyclo, per an inline comment explaining the tradeoff), revive, staticcheck, nakedret, and forbidigo, giving the codebase rigorous, consistently enforced style and correctness rules. Errors follow Go’s sentinel-error idiom (pkg/api/errors.go defines ErrNotFound, ErrForbidden, etc., each with an errors.Is-based IsXError helper) rather than ad hoc string matching. Mocks for interfaces are generated and validated in CI (validate-mocks), and header/doc consistency is checked automatically as well.

API Design The Go SDK (documented in docs/sdk.md) exposes a NewComposeService(dockerCli) constructor and a small, consistently named set of option functions (WithPrompt, WithOutputStream, and similar) for advanced configuration. Getting started requires a moderate amount of boilerplate — constructing a Docker CLI client, initializing it, then constructing the compose service — reflecting that the SDK’s primary consumer is the CLI itself rather than being designed API-first for third parties. Method names mirror the CLI subcommands directly (Up, Down, Build), which keeps the mental model consistent between the two surfaces, and documentation includes a complete worked example for the common load-and-start path.