compose

package module
v0.37.0 Latest Latest
Warning

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

 Go to latest Published: Apr 25, 2025 License: MIT Imports: 30 Imported by: 28

Documentation

Index

Examples

Constants

This section is empty.

Variables

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

Functions

This section is empty.

Types

type ComposeLoggerOption 

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

func WithLogger 

func WithLogger(logger log.Logger) 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 deprecated 

func (o ComposeLoggerOption) ApplyToLocalCompose(opts *LocalDockerComposeOptions)

Deprecated: it will be removed in the next major release

type ComposeProfiles added in v0.34.0 

type ComposeProfiles []string

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 WithProfiles added in v0.34.0 

func WithProfiles(profiles ...string) ComposeStackOption

WithProfiles allows to enable/disable services based on the profiles defined in the compose file.

func WithStackFiles 

func WithStackFiles(filePaths ...string) ComposeStackOption

func WithStackReaders added in v0.31.0 

func WithStackReaders(readers ...io.Reader) ComposeStackOption

WithStackReaders supports reading the compose file/s from a reader.

type ComposeStackReaders added in v0.31.0 

type ComposeStackReaders []io.Reader

type ComposeVersion 

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

type DockerCompose 

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

func NewDockerCompose 

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

func NewDockerComposeWith 

func NewDockerComposeWith(opts ...ComposeStackOption) (*DockerCompose, error)
Example 
package main

import (
	"context"
	"fmt"
	"log"
	"slices"
	"strings"

	"github.com/testcontainers/testcontainers-go/modules/compose"
	"github.com/testcontainers/testcontainers-go/wait"
)

func main() {
	// defineComposeFile {
	composeContent := `services:
  nginx:
    image: nginx:stable-alpine
    environment:
      bar: ${bar}
      foo: ${foo}
    ports:
      - "8081:80"
  mysql:
    image: mysql:8.0.36
    environment:
      - MYSQL_DATABASE=db
      - MYSQL_ROOT_PASSWORD=my-secret-pw
    ports:
     - "3307:3306"
`
	// }

	// defineStackWithOptions {
	stack, err := compose.NewDockerComposeWith(
		compose.StackIdentifier("test"),
		compose.WithStackReaders(strings.NewReader(composeContent)),
	)
	if err != nil {
		log.Printf("Failed to create stack: %v", err)
		return
	}
	// }

	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// upComposeStack {
	err = stack.
		WithEnv(map[string]string{
			"bar": "BAR",
			"foo": "FOO",
		}).
		WaitForService("nginx", wait.ForListeningPort("80/tcp")).
		Up(ctx, compose.Wait(true))
	if err != nil {
		log.Printf("Failed to start stack: %v", err)
		return
	}
	defer func() {
		err = stack.Down(
			context.Background(),
			compose.RemoveOrphans(true),
			compose.RemoveVolumes(true),
			compose.RemoveImagesLocal,
		)
		if err != nil {
			log.Printf("Failed to stop stack: %v", err)
		}
	}()
	// }

	// getServiceNames {
	serviceNames := stack.Services()
	// }

	// both services are started
	fmt.Println(len(serviceNames))
	fmt.Println(slices.Contains(serviceNames, "nginx"))
	fmt.Println(slices.Contains(serviceNames, "mysql"))

	// nginx container is started
	// getServiceContainer {
	nginxContainer, err := stack.ServiceContainer(context.Background(), "nginx")
	if err != nil {
		log.Printf("Failed to get container: %v", err)
		return
	}
	// }

	inspect, err := nginxContainer.Inspect(context.Background())
	if err != nil {
		log.Printf("Failed to inspect container: %v", err)
		return
	}

	// the nginx container has the correct environment variables
	present := map[string]string{
		"bar": "BAR",
		"foo": "FOO",
	}
	for k, v := range present {
		keyVal := k + "=" + v
		fmt.Println(slices.Contains(inspect.Config.Env, keyVal))
	}

}

Output:

2
true
true
true
true
Example (WaitForService) 
package main

import (
	"context"
	"fmt"
	"log"
	"strings"
	"time"

	"github.com/testcontainers/testcontainers-go/modules/compose"
	"github.com/testcontainers/testcontainers-go/wait"
)

func main() {
	composeContent := `services:
  nginx:
    image: nginx:stable-alpine
    environment:
      bar: ${bar}
      foo: ${foo}
    ports:
      - "8081:80"
`

	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	stack, err := compose.NewDockerComposeWith(compose.WithStackReaders(strings.NewReader(composeContent)))
	if err != nil {
		log.Printf("Failed to create stack: %v", err)
		return
	}

	err = stack.
		WithEnv(map[string]string{
			"bar": "BAR",
		}).
		WaitForService("nginx", wait.NewHTTPStrategy("/").WithPort("80/tcp").WithStartupTimeout(10*time.Second)).
		Up(ctx, compose.Wait(true))
	if err != nil {
		log.Printf("Failed to start stack: %v", err)
		return
	}
	defer func() {
		err = stack.Down(
			context.Background(),
			compose.RemoveOrphans(true),
			compose.RemoveVolumes(true),
			compose.RemoveImagesLocal,
		)
		if err != nil {
			log.Printf("Failed to stop stack: %v", err)
		}
	}()

	serviceNames := stack.Services()

	fmt.Println(serviceNames)

}

Output:

[nginx]

func (*DockerCompose) Down 

func (d *DockerCompose) Down(ctx context.Context, opts ...StackDownOption) error

func (*DockerCompose) ServiceContainer added in v0.36.0 

func (d *DockerCompose) ServiceContainer(ctx context.Context, svcName string) (*testcontainers.DockerContainer, error)

func (*DockerCompose) Services added in v0.36.0 

func (d *DockerCompose) Services() []string

func (*DockerCompose) Up added in v0.36.0 

func (d *DockerCompose) Up(ctx context.Context, opts ...StackUpOption) (err error)

func (*DockerCompose) WaitForService 

func (d *DockerCompose) WaitForService(s string, strategy wait.Strategy) ComposeStack

func (*DockerCompose) WithEnv 

func (d *DockerCompose) WithEnv(m map[string]string) ComposeStack

func (*DockerCompose) WithOsEnv added in v0.36.0 

func (d *DockerCompose) WithOsEnv() ComposeStack

type DockerComposer deprecated added in v0.36.0 

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

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

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 deprecated 

type IgnoreOrphans bool

Deprecated: will be removed in the next major release IgnoreOrphans - Ignore legacy containers for services that are not defined in the project

type LocalDockerCompose deprecated 

type LocalDockerCompose struct {
	ComposeVersion
	*LocalDockerComposeOptions
	Executable string

	ComposeFilePaths []string

	Identifier string
	Cmd        []string
	Env        map[string]string
	Services   map[string]any

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

Deprecated: use ComposeStack instead LocalDockerCompose represents a Docker Compose execution using local binary docker compose or docker.exe compose, depending on the underlying platform

Example 
package main

import (
	"github.com/testcontainers/testcontainers-go/modules/compose"
)

func main() {
	_ = compose.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",
		},
	}
}

Output:

func NewLocalDockerCompose deprecated 

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

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

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.

Example 
package main

import (
	"github.com/testcontainers/testcontainers-go/modules/compose"
)

func main() {
	path := "/path/to/docker-compose.yml"

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

Output:

func (*LocalDockerCompose) Down deprecated 

func (dc *LocalDockerCompose) Down() ExecError

Deprecated: it will be removed in the next major release Down executes docker compose down

Example 
package main

import (
	"fmt"

	"github.com/testcontainers/testcontainers-go/modules/compose"
)

func main() {
	path := "/path/to/docker-compose.yml"

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

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

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

Output:

func (*LocalDockerCompose) Invoke deprecated 

func (dc *LocalDockerCompose) Invoke() ExecError

Deprecated: it will be removed in the next major release Invoke invokes the docker compose

Example 
package main

import (
	"fmt"

	"github.com/testcontainers/testcontainers-go/modules/compose"
)

func main() {
	path := "/path/to/docker-compose.yml"

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

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

Output:

func (*LocalDockerCompose) WaitForService deprecated 

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

Deprecated: it will be removed in the next major release WaitForService sets the strategy for the service that is to be waited on

func (*LocalDockerCompose) WithCommand deprecated 

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

Deprecated: it will be removed in the next major release WithCommand assigns the command

Example 
package main

import (
	"github.com/testcontainers/testcontainers-go/modules/compose"
)

func main() {
	path := "/path/to/docker-compose.yml"

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

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

Output:

func (*LocalDockerCompose) WithEnv deprecated 

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

Deprecated: it will be removed in the next major release WithEnv assigns the environment

Example 
package main

import (
	"github.com/testcontainers/testcontainers-go/modules/compose"
)

func main() {
	path := "/path/to/docker-compose.yml"

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

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

Output:

func (*LocalDockerCompose) WithExposedService deprecated 

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

Deprecated: it will be removed in the next major release 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 deprecated 

type LocalDockerComposeOption interface {
	ApplyToLocalCompose(opts *LocalDockerComposeOptions)
}

Deprecated: it will be removed in the next major release 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 deprecated 

type LocalDockerComposeOptions struct {
	Logger log.Logger
}

Deprecated: it will be removed in the next major release LocalDockerComposeOptions defines options applicable to LocalDockerCompose

type LocalDockerComposeOptionsFunc deprecated 

type LocalDockerComposeOptionsFunc func(opts *LocalDockerComposeOptions)

Deprecated: it will be removed in the next major release LocalDockerComposeOptionsFunc is a shorthand to implement the LocalDockerComposeOption interface

func (LocalDockerComposeOptionsFunc) ApplyToLocalCompose deprecated 

func (f LocalDockerComposeOptionsFunc) ApplyToLocalCompose(opts *LocalDockerComposeOptions)

Deprecated: it will be removed in the next major release

type Recreate added in v0.31.0 

type Recreate string

Recreate will recreate the containers that are already running

type RecreateDependencies added in v0.31.0 

type RecreateDependencies string

RecreateDependencies will recreate the dependencies of the services that are already running

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 clean up containers that are not declared on the compose model but own the same labels

type RemoveVolumes added in v0.19.0 

type RemoveVolumes bool

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

func WithRecreate added in v0.31.0 

func WithRecreate(recreate string) StackUpOption

WithRecreate defines the strategy to apply on existing containers. If any other value than api.RecreateNever, api.RecreateForce or api.RecreateDiverged is provided, the default value api.RecreateForce will be used.

func WithRecreateDependencies added in v0.31.0 

func WithRecreateDependencies(recreate string) StackUpOption

WithRecreateDependencies defines the strategy to apply on container dependencies. If any other value than api.RecreateNever, api.RecreateForce or api.RecreateDiverged is provided, the default value api.RecreateForce will be used.

type Wait 

type Wait bool

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.