ContainerCreate is the Docker Go SDK operation that creates a container from a prepared configuration. Creation is distinct from starting: it defines the container and returns a response containing its ID; ContainerStart then runs that created container. This separation lets orchestration code record the ID, inspect errors at each step, and manage the container later. section 3.2 section 3.4
Use ContainerCreate after pulling the required image. Build a container configuration from task-level settings, then pass it with host requirements and a name. The container configuration carries settings such as image, environment variables, exposed ports, and TTY behavior. Host configuration carries host-facing requirements such as restart policy, memory, CPU allocation, and port publishing. section 3.4
Listing 3.10 The Docker client’s ContainerCreate method
func (cli *Client) ContainerCreate( ctx context.Context, config *container.Config, hostConfig *container.HostConfig, networkingConfig *network.NetworkingConfig, platform *specs.Platform, containerName string) (container.ContainerCreateCreatedBody, error)
The method signature makes the boundary explicit: a context controls the request, configuration objects describe the container and host, optional networking and platform values refine placement, and a string supplies the name. section 3.4
The call accepts six inputs:
- A context.Context for the request. section 3.4
- A container.Config pointer describing the container itself. section 3.4
- A container.HostConfig pointer describing host requirements. section 3.4
- A network.NetworkingConfig pointer for network IDs, links, and IP addresses; passing nil leaves those details to Docker. section 3.4
- A specs.Platform pointer for CPU architecture and operating system details; it can be nil when unused. section 3.4
- A string container name. section 3.4
A practical Run flow prepares restart and resource settings, builds container.Config and container.HostConfig values, and calls ContainerCreate with nil networking and platform configuration. Check the returned error before proceeding. On success, pass resp.ID to ContainerStart, save that ID in runtime state, and use it for logs, stopping, and removal. section 3.4 section 3.2
Creating a PostgreSQL container
A task named test-container-1 uses the postgres:13 image and supplies POSTGRES_USER and POSTGRES_PASSWORD environment variables. After creating a Docker client from the environment, the task runs the pull-create-start sequence. The resulting container ID identifies the running container for a later stop-and-remove operation. section 3.4
ContainerCreate is useful when container lifecycle control belongs in an orchestration system rather than in shell commands. The Docker SDK handles HTTP methods, status codes, and request serialization, allowing task code to focus on configuration and lifecycle decisions. Alongside ContainerStart and ContainerStop, it provides programmatic counterparts to familiar Docker command-line operations. section 3.2 section 3.5
