compose

Documentation

Index

• Variables
• func NewDockerCompose(filePaths ...string) (*dockerCompose, error)
• func NewDockerComposeWith(opts ...ComposeStackOption) (*dockerCompose, error)
• type ComposeLoggerOption
  • func WithLogger(logger testcontainers.Logging) ComposeLoggerOption
  • func (o ComposeLoggerOption) ApplyToLocalCompose(opts *LocalDockerComposeOptions)
• type ComposeStack
• type ComposeStackFiles
• type ComposeStackOption
  • func WithStackFiles(filePaths ...string) ComposeStackOption
• type ComposeVersion
• type DockerCompose
• type ExecError
• type IgnoreOrphans
• type LocalDockerCompose
  • func NewLocalDockerCompose(filePaths []string, identifier string, opts ...LocalDockerComposeOption) *LocalDockerCompose
  • func (dc *LocalDockerCompose) Down() ExecError
  • func (dc *LocalDockerCompose) Invoke() ExecError
  • func (dc *LocalDockerCompose) WaitForService(service string, strategy wait.Strategy) DockerCompose
  • func (dc *LocalDockerCompose) WithCommand(cmd []string) DockerCompose
  • func (dc *LocalDockerCompose) WithEnv(env map[string]string) DockerCompose
  • func (dc *LocalDockerCompose) WithExposedService(service string, port int, strategy wait.Strategy) DockerCompose
• type LocalDockerComposeOption
• type LocalDockerComposeOptions
• type LocalDockerComposeOptionsFunc
  • func (f LocalDockerComposeOptionsFunc) ApplyToLocalCompose(opts *LocalDockerComposeOptions)
• type RemoveImages
• type RemoveOrphans
• type StackDownOption
• type StackIdentifier
  • func (f StackIdentifier) String() string
• type StackUpOption
  • func RunServices(serviceNames ...string) StackUpOption
• type Wait

Examples

• LocalDockerCompose
• LocalDockerCompose.Down
• LocalDockerCompose.Invoke
• LocalDockerCompose.WithCommand
• LocalDockerCompose.WithEnv
• NewLocalDockerCompose

Variables

var ErrNoStackConfigured = errors.New("no stack files configured")

Functions

func NewDockerCompose

func NewDockerCompose(filePaths ...string) (*dockerCompose, error)

func NewDockerComposeWith

func NewDockerComposeWith(opts ...ComposeStackOption) (*dockerCompose, error)

Types

type ComposeLoggerOption

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

func WithLogger

func WithLogger(logger testcontainers.Logging) ComposeLoggerOption

WithLogger is a generic option that implements LocalDockerComposeOption It replaces the global Logging implementation with a user defined one e.g. to aggregate logs from testcontainers with the logs of specific test case

func (ComposeLoggerOption) ApplyToLocalCompose

func (o ComposeLoggerOption) ApplyToLocalCompose(opts *LocalDockerComposeOptions)

type ComposeStack

type ComposeStack interface {
	Up(ctx context.Context, opts ...StackUpOption) error
	Down(ctx context.Context, opts ...StackDownOption) error
	Services() []string
	WaitForService(s string, strategy wait.Strategy) ComposeStack
	WithEnv(m map[string]string) ComposeStack
	WithOsEnv() ComposeStack
	ServiceContainer(ctx context.Context, svcName string) (*testcontainers.DockerContainer, error)
}

ComposeStack defines operations that can be applied to a parsed compose stack

type ComposeStackFiles

type ComposeStackFiles []string

type ComposeStackOption

type ComposeStackOption interface {
	// contains filtered or unexported methods
}

func WithStackFiles

func WithStackFiles(filePaths ...string) ComposeStackOption

type ComposeVersion

type ComposeVersion interface {
	Format(parts ...string) string
}

type DockerCompose

type DockerCompose interface {
	Down() ExecError
	Invoke() ExecError
	WaitForService(string, wait.Strategy) DockerCompose
	WithCommand([]string) DockerCompose
	WithEnv(map[string]string) DockerCompose
	WithExposedService(string, int, wait.Strategy) DockerCompose
}

DockerCompose defines the contract for running Docker Compose Deprecated: DockerCompose is the old shell escape based API use ComposeStack instead

type ExecError

type ExecError struct {
	Command      []string
	StdoutOutput []byte
	StderrOutput []byte
	Error        error
	Stdout       error
	Stderr       error
}

ExecError is super struct that holds any information about an execution error, so the client code can handle the result

type IgnoreOrphans

type IgnoreOrphans bool

IgnoreOrphans - Ignore legacy containers for services that are not defined in the project

type LocalDockerCompose

type LocalDockerCompose struct {
	ComposeVersion
	*LocalDockerComposeOptions
	Executable       string
	ComposeFilePaths []string

	Identifier string
	Cmd        []string
	Env        map[string]string
	Services   map[string]interface{}

	WaitStrategyMap map[waitService]wait.Strategy
	// contains filtered or unexported fields
}

LocalDockerCompose represents a Docker Compose execution using local binary docker-compose or docker-compose.exe, depending on the underlying platform

Example

_ = LocalDockerCompose{
	Executable: "docker-compose",
	ComposeFilePaths: []string{
		"/path/to/docker-compose.yml",
		"/path/to/docker-compose-1.yml",
		"/path/to/docker-compose-2.yml",
		"/path/to/docker-compose-3.yml",
	},
	Identifier: "my_project",
	Cmd: []string{
		"up", "-d",
	},
	Env: map[string]string{
		"FOO": "foo",
		"BAR": "bar",
	},
}

func NewLocalDockerCompose

func NewLocalDockerCompose(filePaths []string, identifier string, opts ...LocalDockerComposeOption) *LocalDockerCompose

NewLocalDockerCompose returns an instance of the local Docker Compose, using an array of Docker Compose file paths and an identifier for the Compose execution.

It will iterate through the array adding '-f compose-file-path' flags to the local Docker Compose execution. The identifier represents the name of the execution, which will define the name of the underlying Docker network and the name of the running Compose services.

Deprecated: NewLocalDockerCompose returns a DockerCompose compatible instance which is superseded by ComposeStack use NewDockerCompose instead to get a ComposeStack compatible instance

Example

path := "/path/to/docker-compose.yml"

_ = NewLocalDockerCompose([]string{path}, "my_project")

func (*LocalDockerCompose) Down

func (dc *LocalDockerCompose) Down() ExecError

Down executes docker-compose down

Example

path := "/path/to/docker-compose.yml"

compose := NewLocalDockerCompose([]string{path}, "my_project")

execError := compose.WithCommand([]string{"up", "-d"}).Invoke()
if execError.Error != nil {
	_ = fmt.Errorf("Failed when running: %v", execError.Command)
}

execError = compose.Down()
if execError.Error != nil {
	_ = fmt.Errorf("Failed when running: %v", execError.Command)
}

func (*LocalDockerCompose) Invoke

func (dc *LocalDockerCompose) Invoke() ExecError

Invoke invokes the docker compose

Example

path := "/path/to/docker-compose.yml"

compose := NewLocalDockerCompose([]string{path}, "my_project")

execError := compose.
	WithCommand([]string{"up", "-d"}).
	WithEnv(map[string]string{
		"bar": "BAR",
	}).
	Invoke()
if execError.Error != nil {
	_ = fmt.Errorf("Failed when running: %v", execError.Command)
}

func (*LocalDockerCompose) WaitForService

func (dc *LocalDockerCompose) WaitForService(service string, strategy wait.Strategy) DockerCompose

WaitForService sets the strategy for the service that is to be waited on

func (*LocalDockerCompose) WithCommand

func (dc *LocalDockerCompose) WithCommand(cmd []string) DockerCompose

WithCommand assigns the command

Example

path := "/path/to/docker-compose.yml"

compose := NewLocalDockerCompose([]string{path}, "my_project")

compose.WithCommand([]string{"up", "-d"})

func (*LocalDockerCompose) WithEnv

func (dc *LocalDockerCompose) WithEnv(env map[string]string) DockerCompose

WithEnv assigns the environment

Example

path := "/path/to/docker-compose.yml"

compose := NewLocalDockerCompose([]string{path}, "my_project")

compose.WithEnv(map[string]string{
	"FOO": "foo",
	"BAR": "bar",
})

func (*LocalDockerCompose) WithExposedService

func (dc *LocalDockerCompose) WithExposedService(service string, port int, strategy wait.Strategy) DockerCompose

WithExposedService sets the strategy for the service that is to be waited on. If multiple strategies are given for a single service running on different ports, both strategies will be applied on the same container

type LocalDockerComposeOption

type LocalDockerComposeOption interface {
	ApplyToLocalCompose(opts *LocalDockerComposeOptions)
}

LocalDockerComposeOption defines a common interface to modify LocalDockerComposeOptions These options can be passed to NewLocalDockerCompose in a variadic way to customize the returned LocalDockerCompose instance

type LocalDockerComposeOptions

type LocalDockerComposeOptions struct {
	Logger testcontainers.Logging
}

LocalDockerComposeOptions defines options applicable to LocalDockerCompose

type LocalDockerComposeOptionsFunc

type LocalDockerComposeOptionsFunc func(opts *LocalDockerComposeOptions)

LocalDockerComposeOptionsFunc is a shorthand to implement the LocalDockerComposeOption interface

func (LocalDockerComposeOptionsFunc) ApplyToLocalCompose

func (f LocalDockerComposeOptionsFunc) ApplyToLocalCompose(opts *LocalDockerComposeOptions)

type RemoveImages

type RemoveImages uint8

RemoveImages used by services

const (
	// RemoveImagesAll - remove all images used by the stack
	RemoveImagesAll RemoveImages = iota
	// RemoveImagesLocal - remove only images that don't have a tag
	RemoveImagesLocal
)

type RemoveOrphans

type RemoveOrphans bool

RemoveOrphans will cleanup containers that are not declared on the compose model but own the same labels

type StackDownOption

type StackDownOption interface {
	// contains filtered or unexported methods
}

type StackIdentifier

type StackIdentifier string

func (StackIdentifier) String

func (f StackIdentifier) String() string

type StackUpOption

type StackUpOption interface {
	// contains filtered or unexported methods
}

func RunServices

func RunServices(serviceNames ...string) StackUpOption

RunServices is comparable to 'docker-compose run' as it only creates a subset of containers instead of all services defined by the project

type Wait

type Wait bool

Wait won't return until containers reached the running|healthy state