Getting started

This page covers how to get a development build of dockerd running and how to drive the test suites. The full contributor walk-through lives in docs/contributing/.

Prerequisites

• A working Docker installation (Moby's build runs inside a docker-dev container).
• make and git. Most other dependencies (Go toolchain, build tools) live in the Dockerfile.
• Linux is the primary development OS. Windows and macOS contributors typically use a Linux VM or remote machine.
• For rootless development see docs/rootless.md and daemon/internal/rootless/.

Build

Build the dev container and produce the daemon binary:

make           # default target == binary
make binary    # statically linked Linux binaries via buildx bake
make dynbinary # dynamically linked variant
make cross     # cross-compile non-linux binaries

Outputs land in bundles/. The build is driven by docker-bake.hcl and the multi-stage Dockerfile.

To enter the dev container interactively:

make shell

Inside the shell hack/make.sh exposes a long list of build phases (binary, dynbinary, cross, test-unit, test-integration, cross, validate, etc.).

Run the daemon

Run a daemon inside the dev container:

make run

This calls hack/make.sh install-binary run, which starts the freshly built dockerd listening on /var/run/docker.sock inside the container.

For a faster edit/run loop:

make dev

hack/dev.sh rebuilds and restarts the daemon as you change files.

Test

make test-unit          # unit tests (hack/test/unit)
make test-integration   # API integration tests (under integration/)
make test               # unit + integration + docker-py
make test-docker-py     # the Python SDK conformance suite

You can scope unit tests with environment variables:

TESTDIRS=./daemon/... TESTFLAGS='-run TestName' make test-unit

For integration tests, scope by package directory:

TEST_INTEGRATION_DIR=./integration/container make test-integration
TEST_FILTER=TestContainerCreate make test-integration

The legacy integration-cli/ suite is deprecated and frozen; new tests must live under integration/. See TESTING.md for the full policy.

Validate

make validate runs DCO, gofmt, golangci-lint, swagger, vendor consistency, and a few other checks. Sub-checks: make validate-gofmt, make validate-vendor, make validate-swagger, etc.

Edit the API

The Engine API is defined in api/swagger.yaml. After editing:

make swagger-gen   # regenerate types if you changed types
make swagger-docs  # preview the HTML docs locally

hack/validate/swagger is run by make validate.

Talk to the daemon from Go

Use the client module:

import "github.com/moby/moby/client"

apiClient, err := client.New(client.FromEnv)
ctrs, err := apiClient.ContainerList(ctx, client.ContainerListOptions{All: true})

Useful pointers

• Architecture for the big picture.
• Patterns and conventions before opening a PR.
• Debugging for daemon logs and pprof.