Documentation
¶
Overview ¶
Package compose reads compose files: a project's instances, networks and volumes, described together in YAML as Docker Compose describes containers, and turned into the definitions the client creates them from.
A project's instances are found again by their labels: LabelProject names the project, LabelService the service, and LabelConfigHash is a digest of the definition, so that a service whose definition has changed can be told from one that has not.
Index ¶
Constants ¶
const ( // LabelPrefix starts every label dicer compose sets. A compose file may // not set one of its own. LabelPrefix = "dicer.compose." // LabelProject is the name of the project an instance belongs to. LabelProject = LabelPrefix + "project" // LabelService is the service an instance runs. LabelService = LabelPrefix + "service" // LabelConfigHash is ConfigHash of the definition the instance was // created from. LabelConfigHash = LabelPrefix + "config-hash" )
The labels a project's instances carry.
Variables ¶
var FileNames = []string{"dicer-compose.yaml", "dicer-compose.yml", "compose.yaml", "compose.yml"}
FileNames are the names a compose file is looked for under, in order.
var SubnetPool = netip.MustParsePrefix("10.213.0.0/16")
SubnetPool is where a project network's subnet is picked from when the file gives none: one /24 of it per network.
Functions ¶
func ConfigHash ¶
func ConfigHash(spec dicer.InstanceSpec) string
ConfigHash digests an instance's definition, leaving out its config-hash label. Two definitions with the same hash define the same instance.
func FreeSubnet ¶ added in v0.4.0
FreeSubnet returns the first subnet in SubnetPool that overlaps none of taken, the subnets of the networks there are already.
func Unsupported ¶ added in v0.3.0
Unsupported returns the service keys of Docker Compose's that dicer compose refuses, and why, for the compose file reference to list.
Types ¶
type Condition ¶
type Condition string
Condition is what a service waits for from one it depends on.
const ( // ConditionStarted waits for the service to be running. The default. ConditionStarted Condition = "service_started" // ConditionHealthy waits for the service's health check to pass. ConditionHealthy Condition = "service_healthy" // ConditionCompletedSuccessfully waits for the service to end, with // exit code 0. ConditionCompletedSuccessfully Condition = "service_completed_successfully" )
The conditions depends_on takes, named as Docker Compose names them.
type Dependency ¶
Dependency is a service another waits for, and what it waits for.
type Network ¶
type Network struct {
// Key is the network's name in the file, and Name the daemon's.
Key string
Name string
// External networks are not created or deleted with the project.
External bool
// Spec defines the network. It is nil for an external one. Its subnet
// is empty if the file gives none: up picks a free one, with FreeSubnet.
Spec *dicer.NetworkSpec
}
Network is a network a project uses: its own, created with it, or an external one that must already exist.
type Options ¶
type Options struct {
// File is the compose file. Empty means the first of FileNames in
// WorkDir or the nearest directory above it that has one.
File string
// WorkDir is where to look for the file. Empty means the current
// directory.
WorkDir string
// ProjectDir is the directory relative paths are taken from, and the
// .env file read from. Empty means the file's directory.
ProjectDir string
// ProjectName overrides the file's name and the directory's.
ProjectName string
// EnvFile holds variables for substitution. Empty means .env in the
// project directory, if there is one.
EnvFile string
// Lookup finds the environment's variables, which win over the env
// file's. Nil means the process's.
Lookup Lookup
}
Options say where a project's file is and how to read it.
type Project ¶
type Project struct {
// Name is the project's name, which its resources' names start with.
Name string
// Dir is the directory relative paths in the file are taken from.
Dir string
// File is the compose file's path.
File string
Services map[string]*Service
Networks map[string]*Network
Volumes map[string]*Volume
// Written is the file with its anchors expanded and its extensions left
// out, but its variables as they are written: ${DB_PASSWORD}, not the
// password.
Written []byte
// Resolved is the file as it was read: its variables substituted, its
// anchors expanded and its extensions left out.
Resolved []byte
}
Project is a compose file, checked and resolved: its variables substituted, its relative paths made absolute, and its names made the daemon's.
func (*Project) Order ¶
Order returns the services named, and every service they depend on, each after those it depends on. No names means every service.
func (*Project) Select ¶
Select returns the services named, and nothing they depend on, in the order Order would give them. No names means every service.
func (*Project) ServiceFor ¶
ServiceFor returns the service an instance of the project runs, if it does.
func (*Project) ServiceNames ¶
ServiceNames returns the names of the project's services, sorted.
type Service ¶
type Service struct {
// Name is the service's name in the file.
Name string
// Instance is the definition of the service's instance. Its labels
// include the project's.
Instance dicer.InstanceSpec
// DependsOn are the services to start first, in the order given.
DependsOn []Dependency
}
Service is one of a project's services: an instance, and what it waits for before it starts.
type Volume ¶
type Volume struct {
// Key is the volume's name in the file, and Name the daemon's.
Key string
Name string
// External volumes are not created or deleted with the project.
External bool
// SizeBytes is the size the volume is created with. It is zero for an
// external one.
SizeBytes int64
}
Volume is a volume a project uses: its own, created with it, or an external one that must already exist.
Source Files