docker

README

Libkermit

When green is all there is to be
It could make you wonder why
But why wonder why wonder
I am green, and it'll do fine
It's beautiful,
and I think it's what I want to be.
-- Kermit the Frog

When Docker meets with integration/acceptance tests to make you see everything in green. Libkermit is a Go(lang) library that aims to ease the writing of integration tests (any non unit tests actually) with the helps of Docker and it's ecosystem (mainly libcompose).

The goals are :

• Easy docker manipulation, from managing a simple container to boot up a whole stack.
  • create, delete, pause, … containers
  • check for a certain state containers (inspect them)
  • support compose files to allow starting a whole stack
• Testing suite and functions, in a simple fashion.
• Works seamlessly with the Go(lang) testing framework.
• Try to not force any testing framework but also tries to integrate with them (go-check, testify, …).

Note: This is experimental and not even implemented yet. You are on your own right now

Package docker

This package holds functions and structs to ease docker uses.

package yours

import (
    "testing"

    "github.com/libkermit/docker"
)

func TestItMyFriend(t *testing.T) {
    project, err := docker.NewProjectFromEnv()
    if err != nil {
        t.Fatal(err)
    }
    container, err := project.Start("vdemeester/myawesomeimage")
    if err != nil {
        t.Fatal(err)
    }

    // Do your stuff
    // […]

    // Clean the containers managed by libkermit
    err = project.Clean()
    if err != nil {
        t.Fatal(err)
    }
}

Package docker/testing

This package map the docker package but takes a *testing.T struct on all methods. The idea is to write even less. Let's write the same example as above.

package yours

import (
    "testing"

    docker "github.com/libkermit/docker/testing"
)

func TestItMyFriend(t *testing.T) {
    project := docker.NewProjectFromEnv(t)
    container := project.Start(t, "vdemeester/myawesomeimage")

    // Do your stuff
    // […]

    // Clean the containers managed by libkermit
    project.Clean(t)
}

Other packages to come

• suite : functions and structs to setup tests suites.

Documentation

Overview

Package docker aims to provide simple "helper" methods to ease the use of docker in (integration) tests.

It does support a subset of options compared to actual client api, as it is more focused on needs for integration tests.

Index

• Constants
• Variables
• type APIClient
• type ContainerConfig
• type Project
  • func NewProject(client APIClient) *Project
  • func NewProjectFromEnv() (*Project, error)
  • func (p *Project) Clean(keep bool) error
  • func (p *Project) Create(image string) (types.ContainerJSON, error)
  • func (p *Project) CreateWithConfig(image string, containerConfig ContainerConfig) (types.ContainerJSON, error)
  • func (p *Project) Inspect(containerID string) (types.ContainerJSON, error)
  • func (p *Project) IsPaused(containerID string) (bool, error)
  • func (p *Project) IsRunning(containerID string) (bool, error)
  • func (p *Project) IsStopped(containerID string) (bool, error)
  • func (p *Project) List() ([]types.Container, error)
  • func (p *Project) Pull(ref string) error
  • func (p *Project) Remove(containerID string) error
  • func (p *Project) Start(image string) (types.ContainerJSON, error)
  • func (p *Project) StartWithConfig(image string, containerConfig ContainerConfig) (types.ContainerJSON, error)
  • func (p *Project) Stop(containerID string) error
  • func (p *Project) StopWithTimeout(containerID string, timeout int) error

Constants

const (
	// KermitLabel is the label used to add to containers
	KermitLabel = "com.github.vdemeester.libkermit"
)

Variables

var (
	// KermitHeader defines default kermit headers to pass through the API
	KermitHeader = map[string]string{
		"User-Agent": "libkermit-1.0",
	}

	// KermitLabels defines default docker labels kermit will but on
	// containers and such.
	KermitLabels = map[string]string{
		KermitLabel: "true",
	}

	// KermitLabelFilter is the filter to use to find containers managed by kermit
	KermitLabelFilter = fmt.Sprintf("label=%s", KermitLabel)

	// DefaultStopTimeout is the default timeout for the stop command
	DefaultStopTimeout = 10

	// CurrentAPIVersion defines the current "lower" docker API version
	// supported by libkermit.
	CurrentAPIVersion = "v1.21"
)

Types

type APIClient

type APIClient interface {
	client.ContainerAPIClient
	client.ImageAPIClient
}

APIClient is a lightweight representation of docker client.APIClient

type ContainerConfig

type ContainerConfig struct {
	Name       string
	Cmd        []string
	Entrypoint []string
	Labels     map[string]string
}

ContainerConfig holds container libkermit configuration possibilities

type Project

type Project struct {
	Client APIClient
	Labels map[string]string
}

Project holds docker related project attributes, like docker client, labels to put on the containers, and so on.

func NewProject

func NewProject(client APIClient) *Project

NewProject creates a project with the given client and the default attributes.

func NewProjectFromEnv

func NewProjectFromEnv() (*Project, error)

NewProjectFromEnv creates a project with a client that is build from environment variables.

func (*Project) Clean

func (p *Project) Clean(keep bool) error

Clean stops and removes (by default, controllable with the keep) kermit containers

func (*Project) Create

func (p *Project) Create(image string) (types.ContainerJSON, error)

Create lets you create a container with the specified image, and default configuration.

func (*Project) CreateWithConfig

func (p *Project) CreateWithConfig(image string, containerConfig ContainerConfig) (types.ContainerJSON, error)

CreateWithConfig lets you create a container with the specified image, and some custom simple configuration.

func (*Project) Inspect

func (p *Project) Inspect(containerID string) (types.ContainerJSON, error)

Inspect returns the container informations

func (*Project) IsPaused

func (p *Project) IsPaused(containerID string) (bool, error)

IsPaused checks if the container is running or not

func (*Project) IsRunning

func (p *Project) IsRunning(containerID string) (bool, error)

IsRunning checks if the container is running or not

func (*Project) IsStopped

func (p *Project) IsStopped(containerID string) (bool, error)

IsStopped checks if the container is running or not

func (*Project) List

func (p *Project) List() ([]types.Container, error)

List lists the containers managed by kermit

func (*Project) Pull

func (p *Project) Pull(ref string) error

Pull pulls the given reference (image)

func (*Project) Remove

func (p *Project) Remove(containerID string) error

Remove removes the container

func (*Project) Start

func (p *Project) Start(image string) (types.ContainerJSON, error)

Start lets you create and start a container with the specified image, and default configuration.

func (*Project) StartWithConfig

func (p *Project) StartWithConfig(image string, containerConfig ContainerConfig) (types.ContainerJSON, error)

StartWithConfig lets you create and start a container with the specified image, and some custom simple configuration.

func (*Project) Stop

func (p *Project) Stop(containerID string) error

Stop stops the container with a default timeout.

func (*Project) StopWithTimeout

func (p *Project) StopWithTimeout(containerID string, timeout int) error

StopWithTimeout stops the container with the specified timeout.