compose

Documentation

Overview

Package compose provides a Go wrapper around Docker Compose, useful for integration testing.

// Define Compose config.
var composeYML =`
test_mockserver:
  container_name: ms
  image: jamesdbloom/mockserver
  ports:
    - "10000:1080"
    - "${SOME_ENV_VAR}" # This is replaced with the value of SOME_ENV_VAR.
test_postgres:
  container_name: pg
  image: postgres
  ports:
    - "5432"
`

// Start containers.
c, err := compose.Start(composeYML, true, true)
if err != nil {
	panic(err)
}
defer c.Kill()

// Build MockServer public URL.
mockServerURL := fmt.Sprintf(
	"http://%v:%v",
	compose.MustInferDockerHost(),
	c.Containers["ms"].MustGetFirstPublicPort(1080, "tcp"))

// Wait for MockServer to start accepting connections.
MustConnectWithDefaults(func() error {
	_, err := http.Get(mockServerURL)
	return err
})
...

Index

• func Connect(retryCount int, baseRetryDelay time.Duration, connectFunc func() error) error
• func ConnectWithDefaults(connectFunc func() error) error
• func InferDockerHost() (string, error)
• func MustConnect(retryCount int, baseRetryDelay time.Duration, connectFunc func() error)
• func MustConnectWithDefaults(connectFunc func() error)
• func MustInferDockerHost() string
• type Compose
  • func MustStart(dockerComposeYML string, forcePull, killFirst bool) *Compose
  • func Start(dockerComposeYML string, forcePull, rmFirst bool) (*Compose, error)
  • func (c *Compose) Kill() error
  • func (c *Compose) MustKill()
• type Config
• type Container
  • func Inspect(id string) (*Container, error)
  • func MustInspect(id string) *Container
  • func (c *Container) GetFirstPublicPort(exposedPort uint32, proto string) (uint32, error)
  • func (c *Container) MustGetFirstPublicPort(exposedPort uint32, proto string) uint32
• type NetworkSettings
• type PortBinding
• type State

Functions

func Connect

func Connect(retryCount int, baseRetryDelay time.Duration, connectFunc func() error) error

Connect attempts to connect to a container using the given connector function. Use retryCount and retryDelay to configure the number of retries and the time waited between them (using exponential backoff).

func ConnectWithDefaults

func ConnectWithDefaults(connectFunc func() error) error

ConnectWithDefaults is like Connect, with default values for retryCount and retryDelay.

func InferDockerHost

func InferDockerHost() (string, error)

InferDockerHost returns the current docker host based on the contents of the DOCKER_HOST environment variable. If DOCKER_HOST is not set, it returns "localhost".

func MustConnect

func MustConnect(retryCount int, baseRetryDelay time.Duration, connectFunc func() error)

MustConnect is like Connect, but panics on error.

func MustConnectWithDefaults

func MustConnectWithDefaults(connectFunc func() error)

MustConnectWithDefaults is like ConnectWithDefaults, but panics on error.

func MustInferDockerHost

func MustInferDockerHost() string

MustInferDockerHost is like InferDockerHost, but panics on error.

Types

type Compose

type Compose struct {
	Containers map[string]*Container
	// contains filtered or unexported fields
}

Compose is the main type exported by the package, used to interact with a running Docker Compose configuration.

func MustStart

func MustStart(dockerComposeYML string, forcePull, killFirst bool) *Compose

MustStart is like Start, but panics on error.

func Start

func Start(dockerComposeYML string, forcePull, rmFirst bool) (*Compose, error)

Start starts a Docker Compose configuration. If forcePull is true, it attempts do pull newer versions of the images. If rmFirst is true, it attempts to kill and delete containers before starting new ones.

func (*Compose) Kill

func (c *Compose) Kill() error

Kill kills any running containers for the current configuration.

func (*Compose) MustKill

func (c *Compose) MustKill()

MustKill is like Kill, but panics on error.

type Config

type Config struct {
	Hostname     string              `json:"Hostname,omitempty"`
	ExposedPorts map[string]struct{} `json:"ExposedPorts,omitempty"`
	Env          []string            `json:"Env,omitempty"`
	Cmd          []string            `json:"Cmd"`
	Image        string              `json:"Image,omitempty"`
	Labels       map[string]string   `json:"Labels,omitempty"`
}

Config models the config section of the `docker inspect` command output.

type Container

type Container struct {
	ID              string           `json:"Id"`
	Name            string           `json:"Name,omitempty"`
	Created         time.Time        `json:"Created,omitempty"`
	Config          *Config          `json:"Config,omitempty"`
	State           State            `json:"State,omitempty"`
	Image           string           `json:"Image,omitempty"`
	NetworkSettings *NetworkSettings `json:"NetworkSettings,omitempty"`
}

Container models the `docker inspect` command output.

func Inspect

func Inspect(id string) (*Container, error)

Inspect inspects a container using the `docker inspect` command and returns a parsed version of its output.

func MustInspect

func MustInspect(id string) *Container

MustInspect is like Inspect, but panics on error.

func (*Container) GetFirstPublicPort

func (c *Container) GetFirstPublicPort(exposedPort uint32, proto string) (uint32, error)

GetFirstPublicPort returns the first public public port mapped to the given exposedPort, for the given proto ("tcp", "udp", etc.), if found.

func (*Container) MustGetFirstPublicPort

func (c *Container) MustGetFirstPublicPort(exposedPort uint32, proto string) uint32

MustGetFirstPublicPort is like GetFirstPublicPort, but panics on error.

type NetworkSettings

type NetworkSettings struct {
	Ports map[string][]PortBinding `json:"Ports,omitempty"`
}

NetworkSettings models the network settings section of the `docker inspect` command.

type PortBinding

type PortBinding struct {
	HostIP   string `json:"HostIP,omitempty"`
	HostPort string `json:"HostPort,omitempty"`
}

PortBinding models a port binding in the network settings section of the `docker inspect command.

type State

type State struct {
	Running    bool      `json:"Running,omitempty"`
	Paused     bool      `json:"Paused,omitempty"`
	Restarting bool      `json:"Restarting,omitempty"`
	OOMKilled  bool      `json:"OOMKilled,omitempty"`
	Pid        int       `json:"Pid,omitempty"`
	ExitCode   int       `json:"ExitCode,omitempty"`
	Error      string    `json:"Error,omitempty"`
	StartedAt  time.Time `json:"StartedAt,omitempty"`
	FinishedAt time.Time `json:"FinishedAt,omitempty"`
}

State models the state section of the `docker inspect` command.