Documentation
¶
Overview ¶
Package docker provides a Go wrapper around the Docker Engine API for building images, running containers, health-checking, and garbage collection.
All long-running operations accept a context.Context for cancellation and timeout propagation.
Index ¶
- func StartGarbageCollector(ctx context.Context, client *DockerClient, interval time.Duration, ...)
- type Client
- type DockerClient
- func (dc *DockerClient) BuildImage(ctx context.Context, buildDir, imageName string, buildArgs map[string]string, ...) error
- func (dc *DockerClient) Close() error
- func (dc *DockerClient) Ping(ctx context.Context) error
- func (dc *DockerClient) PruneImages(ctx context.Context, retentionHours int) error
- func (dc *DockerClient) Raw() *client.Client
- func (dc *DockerClient) RemoveContainer(ctx context.Context, containerID string) error
- func (dc *DockerClient) RunContainer(ctx context.Context, imageName, containerName string, port int, ...) (string, error)
- func (dc *DockerClient) StopAndRemoveContainer(ctx context.Context, containerID string) error
- func (dc *DockerClient) StopContainer(ctx context.Context, containerID string) error
- func (dc *DockerClient) WaitForHealthy(ctx context.Context, containerID string, port int, healthPath string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func StartGarbageCollector ¶
func StartGarbageCollector(ctx context.Context, client *DockerClient, interval time.Duration, retentionHours int)
StartGarbageCollector runs PruneImages on a ticker at the given interval. It blocks until ctx is cancelled. Call this in a goroutine.
Types ¶
type Client ¶
type Client interface {
// Ping verifies the Docker daemon is reachable.
Ping(ctx context.Context) error
// BuildImage builds a Docker image from a build context directory.
// logFn is called with each line of build output.
BuildImage(ctx context.Context, buildDir, imageName string, buildArgs map[string]string, dockerfile string, logFn func(string)) error
// RunContainer creates and starts a new container, returning its ID.
RunContainer(ctx context.Context, imageName, containerName string, port int, labels map[string]string, envVars []string, network string) (string, error)
// StopContainer stops a running container by ID.
StopContainer(ctx context.Context, containerID string) error
// RemoveContainer removes a stopped container by ID.
RemoveContainer(ctx context.Context, containerID string) error
// StopAndRemoveContainer stops and then removes a container by ID.
StopAndRemoveContainer(ctx context.Context, containerID string) error
// WaitForHealthy polls a container until it is healthy or the context
// is cancelled/times out.
WaitForHealthy(ctx context.Context, containerID string, port int, healthPath string) error
// PruneImages removes dangling images and build cache older than the
// given number of hours.
PruneImages(ctx context.Context, retentionHours int) error
}
Client is the interface that all Docker operations depend on. It is implemented by DockerClient (real) and can be mocked in tests.
type DockerClient ¶
type DockerClient struct {
// contains filtered or unexported fields
}
DockerClient wraps the official Docker Engine API client and implements the Client interface for real Docker operations.
func NewClient ¶
func NewClient(socketPath string) (*DockerClient, error)
NewClient creates a new DockerClient connected to the Docker daemon at the given socket path (e.g., "unix:///var/run/docker.sock" or "npipe:////./pipe/docker_engine" on Windows).
func (*DockerClient) BuildImage ¶
func (dc *DockerClient) BuildImage(ctx context.Context, buildDir, imageName string, buildArgs map[string]string, dockerfile string, logFn func(string)) error
BuildImage creates a Docker image from the given build context directory. It streams each line of build output to the provided logFn callback.
func (*DockerClient) Close ¶
func (dc *DockerClient) Close() error
Close releases resources held by the underlying Docker client.
func (*DockerClient) Ping ¶
func (dc *DockerClient) Ping(ctx context.Context) error
Ping checks that the Docker daemon is reachable.
func (*DockerClient) PruneImages ¶
func (dc *DockerClient) PruneImages(ctx context.Context, retentionHours int) error
PruneImages removes dangling images and build cache older than the specified number of hours.
func (*DockerClient) Raw ¶
func (dc *DockerClient) Raw() *client.Client
Raw returns the underlying Docker SDK client for advanced operations.
func (*DockerClient) RemoveContainer ¶
func (dc *DockerClient) RemoveContainer(ctx context.Context, containerID string) error
RemoveContainer removes a stopped container by ID.
func (*DockerClient) RunContainer ¶
func (dc *DockerClient) RunContainer(ctx context.Context, imageName, containerName string, port int, labels map[string]string, envVars []string, networkName string) (string, error)
RunContainer creates and starts a new container from the given image. Returns the container ID on success.
func (*DockerClient) StopAndRemoveContainer ¶
func (dc *DockerClient) StopAndRemoveContainer(ctx context.Context, containerID string) error
StopAndRemoveContainer stops a container (if running) and then removes it.
func (*DockerClient) StopContainer ¶
func (dc *DockerClient) StopContainer(ctx context.Context, containerID string) error
StopContainer stops a running container by ID with a graceful timeout.
func (*DockerClient) WaitForHealthy ¶
func (dc *DockerClient) WaitForHealthy(ctx context.Context, containerID string, port int, healthPath string) error
WaitForHealthy polls a container until it is reachable or the context is cancelled/times out. If healthPath is non-empty, an HTTP GET to containerIP:port/healthPath must return 2xx. Otherwise, a TCP dial to containerIP:port is sufficient.