compose

package
v5.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 23, 2026 License: Apache-2.0 Imports: 105 Imported by: 6

Documentation

Overview

Copyright 2020 Docker Compose CLI authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

Constants

View Source
const (
	ErrorType     = "error"
	InfoType      = "info"
	SetEnvType    = "setenv"
	RawSetEnvType = "rawsetenv"
	DebugType     = "debug"
)
View Source
const (
	PreparingPhase         = "Preparing"
	WaitingPhase           = "waiting"
	PullingFsPhase         = "Pulling fs layer"
	DownloadingPhase       = "Downloading"
	DownloadCompletePhase  = "Download complete"
	ExtractingPhase        = "Extracting"
	VerifyingChecksumPhase = "Verifying Checksum"
	AlreadyExistsPhase     = "Already exists"
	PullCompletePhase      = "Pull complete"
)
View Source
const (

	// DockerEngineV28_1 is the specific version string for Docker Engine 28.1
	DockerEngineV28_1 = "v28.1"
)

Docker Engine version strings for user-facing error messages. These should be used in error messages to provide clear version requirements.

View Source
const ServiceConditionRunningOrHealthy = "running_or_healthy"

ServiceConditionRunningOrHealthy is a service condition on status running or healthy

Variables

This section is empty.

Functions

func ImageDigestResolver

func ImageDigestResolver(ctx context.Context, file *configfile.ConfigFile, apiClient client.APIClient) func(named reference.Named) (digest.Digest, error)

ImageDigestResolver creates a func able to resolve image digest from a docker ref,

func InDependencyOrder

func InDependencyOrder(ctx context.Context, project *types.Project, fn func(context.Context, string) error, options ...func(*graphTraversal)) error

InDependencyOrder applies the function to the services of the project taking in account the dependency order

func InReverseDependencyOrder

func InReverseDependencyOrder(ctx context.Context, project *types.Project, fn func(context.Context, string) error, options ...func(*graphTraversal)) error

InReverseDependencyOrder applies the function to the services of the project in reverse order of dependencies

func NetworkHash

func NetworkHash(o *types.NetworkConfig) (string, error)

NetworkHash computes the configuration hash for a network.

func NewComposeService

func NewComposeService(dockerCli command.Cli, options ...Option) (api.Compose, error)

NewComposeService creates a Compose service using Docker CLI. This is the standard constructor that requires command.Cli for full functionality.

Example usage:

dockerCli, _ := command.NewDockerCli()
service := NewComposeService(dockerCli)

For advanced configuration with custom overrides, use ServiceOption functions:

service := NewComposeService(dockerCli,
    WithPrompt(prompt.NewPrompt(cli.In(), cli.Out()).Confirm),
    WithOutputStream(customOut),
    WithErrorStream(customErr),
    WithInputStream(customIn))

Or set all streams at once:

service := NewComposeService(dockerCli,
    WithStreams(customOut, customErr, customIn))

func Run

func Run(ctx context.Context, pf progressFunc, operation string, bus api.EventProcessor) error

func ServiceHash

func ServiceHash(o types.ServiceConfig) (string, error)

ServiceHash computes the configuration hash for a service.

func ToMobyEnv

func ToMobyEnv(environment compose.MappingWithEquals) []string

ToMobyEnv convert into []string

func ToSeconds

func ToSeconds(d *compose.Duration) *int

ToSeconds convert into seconds

func VolumeHash

func VolumeHash(o types.VolumeConfig) (string, error)

VolumeHash computes the configuration hash for a volume.

func WithDryRun

func WithDryRun(s *composeService) error

WithDryRun configure Compose to run without actually applying changes

func WithRootNodesAndDown

func WithRootNodesAndDown(nodes []string) func(*graphTraversal)

Types

type CommandMetadata

type CommandMetadata struct {
	Parameters []ParameterMetadata `json:"parameters"`
}

func (CommandMetadata) CheckRequiredParameters

func (c CommandMetadata) CheckRequiredParameters(provider types.ServiceProviderConfig) error

func (CommandMetadata) GetParameter

func (c CommandMetadata) GetParameter(paramName string) (ParameterMetadata, bool)

type ContainerStdin

type ContainerStdin struct {
	client.HijackedResponse
}

ContainerStdin implement WriteCloser for moby.HijackedResponse

func (ContainerStdin) Close

func (c ContainerStdin) Close() error

Close implement io.WriteCloser

func (ContainerStdin) Write

func (c ContainerStdin) Write(p []byte) (n int, err error)

Write implement io.WriteCloser

type ContainerStdout

type ContainerStdout struct {
	client.HijackedResponse
}

ContainerStdout implement ReadCloser for moby.HijackedResponse

func (ContainerStdout) Close

func (l ContainerStdout) Close() error

Close implement io.ReadCloser

func (ContainerStdout) Read

func (l ContainerStdout) Read(p []byte) (n int, err error)

Read implement io.ReadCloser

type Containers

type Containers []container.Summary

Containers is a set of moby Container

type Graph

type Graph struct {
	Vertices map[string]*Vertex
	// contains filtered or unexported fields
}

Graph represents project as service dependencies

func NewGraph

func NewGraph(project *types.Project, initialStatus ServiceStatus) (*Graph, error)

NewGraph returns the dependency graph of the services

func (*Graph) AddEdge

func (g *Graph) AddEdge(source string, destination string) error

AddEdge adds a relationship of dependency between vertices `source` and `destination`

func (*Graph) AddVertex

func (g *Graph) AddVertex(key string, service string, initialStatus ServiceStatus)

AddVertex adds a vertex to the Graph

func (*Graph) FilterChildren

func (g *Graph) FilterChildren(key string, status ServiceStatus) []*Vertex

FilterChildren returns children of a certain vertex that are in a certain status

func (*Graph) FilterParents

func (g *Graph) FilterParents(key string, status ServiceStatus) []*Vertex

FilterParents returns the parents of a certain vertex that are in a certain status

func (*Graph) HasCycles

func (g *Graph) HasCycles() (bool, error)

HasCycles detects cycles in the graph

func (*Graph) Leaves

func (g *Graph) Leaves() []*Vertex

Leaves returns the slice of leaves of the graph

func (*Graph) Roots

func (g *Graph) Roots() []*Vertex

Roots returns the slice of "Roots" of the graph

func (*Graph) UpdateStatus

func (g *Graph) UpdateStatus(key string, status ServiceStatus)

UpdateStatus updates the status of a certain vertex

type ImagePruneMode

type ImagePruneMode string

ImagePruneMode controls how aggressively images associated with the project are removed from the engine.

const (
	// ImagePruneNone indicates that no project images should be removed.
	ImagePruneNone ImagePruneMode = ""
	// ImagePruneLocal indicates that only images built locally by Compose
	// should be removed.
	ImagePruneLocal ImagePruneMode = "local"
	// ImagePruneAll indicates that all project-associated images, including
	// remote images should be removed.
	ImagePruneAll ImagePruneMode = "all"
)

type ImagePruneOptions

type ImagePruneOptions struct {
	Mode ImagePruneMode

	// RemoveOrphans will result in the removal of images that were built for
	// the project regardless of whether they are for a known service if true.
	RemoveOrphans bool
}

ImagePruneOptions controls the behavior of image pruning.

type ImagePruner

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

ImagePruner handles image removal during Compose `down` operations.

func NewImagePruner

func NewImagePruner(imageClient client.ImageAPIClient, project *types.Project) *ImagePruner

NewImagePruner creates an ImagePruner object for a project.

func (*ImagePruner) ImagesToPrune

func (p *ImagePruner) ImagesToPrune(ctx context.Context, opts ImagePruneOptions) ([]string, error)

ImagesToPrune returns the set of images that should be removed.

type JsonMessage

type JsonMessage struct {
	Type    string `json:"type"`
	Message string `json:"message"`
}

type Model

type Model struct {
	Id      string   `json:"id"`
	Tags    []string `json:"tags"`
	Created int      `json:"created"`
	Config  struct {
		Format       string `json:"format"`
		Quantization string `json:"quantization"`
		Parameters   string `json:"parameters"`
		Architecture string `json:"architecture"`
		Size         string `json:"size"`
	} `json:"config"`
}

type ObservedContainer added in v5.2.0

type ObservedContainer struct {
	ID          string
	Name        string
	State       container.ContainerState // "running", "exited", "created", "restarting", etc.
	ConfigHash  string                   // label com.docker.compose.config-hash
	ImageDigest string                   // label com.docker.compose.image
	Number      int                      // label com.docker.compose.container-number

	// ConnectedNetworks maps network IDs found in the container's network
	// settings. Key is the network name as seen by Docker, value is the
	// network ID.
	ConnectedNetworks map[string]string

	// Raw summary kept for the executor which needs it to call Moby APIs.
	Summary container.Summary
}

ObservedContainer holds the relevant state extracted from a running or stopped container, with label values pre-parsed for efficient comparison.

type ObservedNetwork added in v5.2.0

type ObservedNetwork struct {
	ID          string
	Name        string
	ConfigHash  string // label com.docker.compose.config-hash
	ProjectName string // label com.docker.compose.project
}

ObservedNetwork holds the state of a Docker network that belongs to the project, identified by the com.docker.compose.network label.

type ObservedState added in v5.2.0

type ObservedState struct {
	ProjectName string
	Containers  map[string][]ObservedContainer // service name → containers
	Orphans     []ObservedContainer            // containers with no matching service
	Networks    map[string]ObservedNetwork     // compose network key → observed
	Volumes     map[string]ObservedVolume      // compose volume key → observed
}

ObservedState captures the current state of all Docker resources belonging to a Compose project. It is a snapshot taken before reconciliation so that the reconciler can compare desired state (types.Project) with reality without making any further API calls.

type ObservedVolume added in v5.2.0

type ObservedVolume struct {
	Name        string
	ConfigHash  string // label com.docker.compose.config-hash
	ProjectName string // label com.docker.compose.project
	Driver      string
}

ObservedVolume holds the state of a Docker volume that belongs to the project, identified by the com.docker.compose.volume label.

type Operation added in v5.2.0

type Operation struct {
	Type       OperationType
	ResourceID string // e.g. "service:web:1", "network:backend", "volume:data"
	Cause      string // why this operation is needed

	// Resource-specific data (only the relevant fields are set per operation type)
	Service      *types.ServiceConfig // for container operations
	Container    *container.Summary   // existing container (for stop/remove)
	Inherited    *container.Summary   // container to inherit anonymous volumes from (for create-as-replacement)
	Number       int                  // container replica number (for create)
	Name         string               // target container/resource name
	Network      *types.NetworkConfig // for network operations
	Volume       *types.VolumeConfig  // for volume operations
	Timeout      *time.Duration       // for stop operations
	CreateNodeID int                  // for OpRenameContainer: ID of the CreateContainer node whose result to rename
}

Operation describes a single atomic action to be performed by the executor.

type OperationType added in v5.2.0

type OperationType int

OperationType identifies the kind of atomic operation in a reconciliation plan. Each operation maps to exactly one Docker API call.

const (
	// Network operations
	OpCreateNetwork     OperationType = 1
	OpRemoveNetwork     OperationType = 2
	OpDisconnectNetwork OperationType = 3
	OpConnectNetwork    OperationType = 4

	// Volume operations
	OpCreateVolume OperationType = 10
	OpRemoveVolume OperationType = 11

	// Container operations
	OpCreateContainer OperationType = 20
	OpStartContainer  OperationType = 21
	OpStopContainer   OperationType = 22
	OpRemoveContainer OperationType = 23
	OpRenameContainer OperationType = 24

	// Provider operations
	OpRunProvider OperationType = 30
)

OperationType values are explicit so that adding a new op in the middle of the list does not silently shift other values.

func (OperationType) String added in v5.2.0

func (o OperationType) String() string

String returns the human-readable name of an OperationType.

type Option

type Option func(service *composeService) error

func WithContextInfo

func WithContextInfo(info api.ContextInfo) Option

WithContextInfo sets custom Docker context information

func WithErrorStream

func WithErrorStream(err io.Writer) Option

WithErrorStream sets a custom error stream

func WithEventProcessor

func WithEventProcessor(bus api.EventProcessor) Option

WithEventProcessor configure component to get notified on Compose operation and progress events. Typically used to configure a progress UI

func WithInputStream

func WithInputStream(in io.Reader) Option

WithInputStream sets a custom input stream

func WithMaxConcurrency

func WithMaxConcurrency(maxConcurrency int) Option

WithMaxConcurrency defines upper limit for concurrent operations against engine API

func WithOutputStream

func WithOutputStream(out io.Writer) Option

WithOutputStream sets a custom output stream

func WithPrompt

func WithPrompt(prompt Prompt) Option

WithPrompt configure a UI component for Compose service to interact with user and confirm actions

func WithProxyConfig

func WithProxyConfig(config map[string]string) Option

WithProxyConfig sets custom HTTP proxy configuration for builds

func WithStreams

func WithStreams(out, err io.Writer, in io.Reader) Option

WithStreams sets custom I/O streams for output and interaction

type ParameterMetadata

type ParameterMetadata struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Required    bool   `json:"required"`
	Type        string `json:"type"`
	Default     string `json:"default,omitempty"`
}

type Plan added in v5.2.0

type Plan struct {
	Nodes []*PlanNode
	// contains filtered or unexported fields
}

Plan is a directed acyclic graph of operations produced by the reconciler. Nodes are stored in topological order (dependencies before dependents).

func (*Plan) IsEmpty added in v5.2.0

func (p *Plan) IsEmpty() bool

IsEmpty returns true if the plan contains no operations.

func (*Plan) String added in v5.2.0

func (p *Plan) String() string

String renders the plan as a human-readable graph for testing and debugging.

Format per line: [dep1,dep2] -> #id resource, operation, cause [group]

Examples:

[] -> #1 network:default, CreateNetwork, not found
[1] -> #2 service:web:1, CreateContainer, no existing container
[2] -> #3 service:web:1, StopContainer, replaced by #2 [recreate:web:1]

type PlanNode added in v5.2.0

type PlanNode struct {
	ID        int // numeric identifier (#1, #2, ...)
	Operation Operation
	DependsOn []*PlanNode // prerequisite operations
	Group     string      // event grouping key (e.g. "recreate:web:1"); empty for ungrouped nodes
}

PlanNode is a single node in the reconciliation DAG. It represents one atomic operation and its dependencies on other nodes.

type Prompt

type Prompt func(message string, defaultValue bool) (bool, error)

func AlwaysOkPrompt

func AlwaysOkPrompt() Prompt

AlwaysOkPrompt returns a Prompt implementation that always returns true without user interaction.

type ProviderMetadata

type ProviderMetadata struct {
	Description string           `json:"description"`
	Up          CommandMetadata  `json:"up"`
	Down        CommandMetadata  `json:"down"`
	Stop        *CommandMetadata `json:"stop,omitempty"`
}

func (ProviderMetadata) IsEmpty

func (p ProviderMetadata) IsEmpty() bool

type ReconcileOptions added in v5.2.0

type ReconcileOptions struct {
	Services             []string       // targeted services (empty = all)
	Recreate             string         // "diverged", "force", "never" for targeted services
	RecreateDependencies string         // same for non-targeted services
	Inherit              bool           // inherit anonymous volumes on recreate
	Timeout              *time.Duration // for stop operations
	RemoveOrphans        bool
	SkipProviders        bool
}

ReconcileOptions controls how the reconciler compares desired and observed state.

type ServiceStatus

type ServiceStatus int

ServiceStatus indicates the status of a service

const (
	ServiceStopped ServiceStatus = iota
	ServiceStarted
)

Services status flags

type Vertex

type Vertex struct {
	Key      string
	Service  string
	Status   ServiceStatus
	Children map[string]*Vertex
	Parents  map[string]*Vertex
}

Vertex represents a service in the dependencies structure

func NewVertex

func NewVertex(key string, service string, initialStatus ServiceStatus) *Vertex

NewVertex is the constructor function for the Vertex

func (*Vertex) GetChildren

func (v *Vertex) GetChildren() []*Vertex

GetChildren returns a slice with the child vertices of the Vertex

func (*Vertex) GetParents

func (v *Vertex) GetParents() []*Vertex

GetParents returns a slice with the parent vertices of the Vertex

type WatchFunc

type WatchFunc func(ctx context.Context, project *types.Project, options api.WatchOptions) (func() error, error)

type Watcher

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

func NewWatcher

func NewWatcher(project *types.Project, options api.UpOptions, w WatchFunc, consumer api.LogConsumer) (*Watcher, error)

func (*Watcher) Start

func (w *Watcher) Start(ctx context.Context) error

func (*Watcher) Stop

func (w *Watcher) Stop() error

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL