dockerutils

README

dockerutils

dockerutils is a small library which extends the official docker library to create and start images over a builder. Additionally the library provide functions for easy removeing resources based on ids, names or labels which the official library does not directly supports.

Installing

Install the library by the following command:

go get git.cryptic.systems/volker.raschek/dockerutils

Usage

Example: Create and remove postgreSQL container

package main

import "git.cryptic.systems/volker.raschek/dockerutils"

func noErr(err){
  if err != nil {
    panic(err)
  }
}

func main(){
  dockerClient, err := dockerutils.New()
  noErr(err)

  postgresContainerID, err := dockerClient.NewBuilder("postgres:13-alpine").
    Port(fmt.Sprintf("5432:5432/tcp", postgresHostPort)).
    Pull().
    AddEnv("PGTZ", "Europe/Berlin").
    AddEnv("POSTGRES_PASSWORD", postgres).
    AddEnv("TZ", "Europe/Berlin").
    Mount("/etc/localtime", "/etc/localtime").
    Start(context.Background())
  noErr(err)
  defer func(){dockerClient.ContainerRemoveByIDs(context.Background(), postgresContainerID)}
}

Example: Create and remove container network

package main

import (
  "git.cryptic.systems/volker.raschek/dockerutils"
  "github.com/docker/docker/api/types"
)

func noErr(err){
  if err != nil {
    panic(err)
  }
}

func main(){
  dockerClient, err := dockerutils.New()
  noErr(err)

  containerNetwork, err := dockerClient.NetworkCreate(ctx, "my-network", tt.NetworkCreate{Labels: map[string]string{"key": "value"}})
  noErr(err)
  defer func(){dockerClient.NetworkRemove(context.Background(), containerNetwork.ID)}
}

Documentation

Index

• Variables
• type Builder
  • func (builder *Builder) AddEnv(key string, value string) *Builder
  • func (builder *Builder) AddLabel(key string, value string) *Builder
  • func (builder *Builder) Env(env map[string]string) *Builder
  • func (builder *Builder) Labels(labels map[string]string) *Builder
  • func (builder *Builder) Memory(limit int64) *Builder
  • func (builder *Builder) Mount(source string, dest string) *Builder
  • func (builder *Builder) Mounts(mounts map[string]string) *Builder
  • func (builder *Builder) Network(networkName string, aliasses ...string) *Builder
  • func (builder *Builder) Port(port string) *Builder
  • func (builder *Builder) Ports(ports []string) *Builder
  • func (builder *Builder) Pull() *Builder
  • func (builder *Builder) Start(ctx context.Context) (string, error)
  • func (builder *Builder) WaitForHealthy() *Builder
  • func (builder *Builder) WithName(containerName string) *Builder
• type Client
  • func New() (*Client, error)
  • func (client *Client) Close() error
  • func (client *Client) ContainerListByLabels(ctx context.Context, all bool, containerLabels map[string]string) ([]types.Container, error)
  • func (client *Client) ContainerListByNames(ctx context.Context, all bool, containerNames ...string) ([]types.Container, error)
  • func (client *Client) ContainerRemoveByIDs(ctx context.Context, containerIDs ...string) error
  • func (client *Client) ContainerRemoveByLabels(ctx context.Context, containerLabels map[string]string) error
  • func (client *Client) ContainerRemoveByNames(ctx context.Context, containerNames ...string) error
  • func (client *Client) ContainerStopByIDs(ctx context.Context, timeout time.Duration, containerIDs ...string) error
  • func (client *Client) ContainerStopByLabels(ctx context.Context, timeout time.Duration, containerLabels map[string]string) error
  • func (client *Client) ContainerStopByNames(ctx context.Context, timeout time.Duration, containerNames ...string) error
  • func (client *Client) GetWatcher() *Watcher
  • func (client *Client) NetworkListByLabels(ctx context.Context, networkLabels map[string]string) ([]types.NetworkResource, error)
  • func (client *Client) NetworkListByNames(ctx context.Context, networkNames ...string) ([]types.NetworkResource, error)
  • func (client *Client) NetworkRemoveByIDs(ctx context.Context, containerIDs ...string) error
  • func (client *Client) NetworkRemoveByLabels(ctx context.Context, containerLabels map[string]string) error
  • func (client *Client) NetworkRemoveByNames(ctx context.Context, networkNames ...string) error
  • func (client *Client) NewBuilder(image string) *Builder
  • func (client *Client) Pull(ctx context.Context, image string, w io.Writer) error
  • func (client *Client) PullQuiet(ctx context.Context, image string) error
  • func (client *Client) VolumeListByLabels(ctx context.Context, volumeLabels map[string]string) (volume.VolumeListOKBody, error)
  • func (client *Client) VolumeListByNames(ctx context.Context, volumeNames ...string) (volume.VolumeListOKBody, error)
  • func (client *Client) VolumeRemoveByLabels(ctx context.Context, volumeLabels map[string]string) error
  • func (client *Client) VolumeRemoveByNames(ctx context.Context, volumeNames ...string) error
• type ErrorMapper
• type Watcher
  • func (watcher *Watcher) AddListener(containerID string, errorChannel chan<- error, doneChannel chan<- struct{}) error
  • func (watcher *Watcher) AddListenerWithErrorMapper(containerID string, errorChannel chan<- error, doneChannel chan<- struct{}, ...) error

Variables

var (
	ErrDied      = errors.New("died")
	ErrUnhealthy = errors.New("went unhealthy")
)

Types

type Builder

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

Builder is a wrapper around the official docker API to start a container image.

func (*Builder) AddEnv

func (builder *Builder) AddEnv(key string, value string) *Builder

AddEnv to the container

func (*Builder) AddLabel

func (builder *Builder) AddLabel(key string, value string) *Builder

AddLabel to the container

func (*Builder) Env

func (builder *Builder) Env(env map[string]string) *Builder

Env set environment variables to the container

func (*Builder) Labels

func (builder *Builder) Labels(labels map[string]string) *Builder

Labels set labels to the container

func (*Builder) Memory

func (builder *Builder) Memory(limit int64) *Builder

Memory defines a memory limit for the container

func (*Builder) Mount

func (builder *Builder) Mount(source string, dest string) *Builder

Mount a source volume or hostpath into the filesystem of the container

func (*Builder) Mounts

func (builder *Builder) Mounts(mounts map[string]string) *Builder

Mounts a set of source volumes or hostpath into the filesystem of the container

func (*Builder) Network

func (builder *Builder) Network(networkName string, aliasses ...string) *Builder

Network add the container with aliasses to a specific network

func (*Builder) Port

func (builder *Builder) Port(port string) *Builder

Port defines a port forwarding from the host machine to the container Examples: - 8080:8080 - 10.6.231.10:8080:8080 - 10.6.231.10:8080:8080/tcp

func (*Builder) Ports

func (builder *Builder) Ports(ports []string) *Builder

Ports defines a set port forwarding rules from the host machine to the container Examples: - 8080:8080 - 10.6.231.10:8080:8080 - 10.6.231.10:8080:8080/tcp

func (*Builder) Pull

func (builder *Builder) Pull() *Builder

Pull the image if absent

func (*Builder) Start

func (builder *Builder) Start(ctx context.Context) (string, error)

Start the container

func (*Builder) WaitForHealthy

func (builder *Builder) WaitForHealthy() *Builder

WaitForHealthy set the option to wait during the start process until the container is healthy.

func (*Builder) WithName

func (builder *Builder) WithName(containerName string) *Builder

WithName set the name of the container

type Client

type Client struct {
	*client.Client
	// contains filtered or unexported fields
}

Client from the docker API with additional functions

func New

func New() (*Client, error)

New returns a new dockerutil client

func (*Client) Close

func (client *Client) Close() error

Close docker connection

func (*Client) ContainerListByLabels

func (client *Client) ContainerListByLabels(ctx context.Context, all bool, containerLabels map[string]string) ([]types.Container, error)

ContainerListByLabels returns only containers which match by given labels

func (*Client) ContainerListByNames

func (client *Client) ContainerListByNames(ctx context.Context, all bool, containerNames ...string) ([]types.Container, error)

ContainerListByNames returns only containers which match by given labels

func (*Client) ContainerRemoveByIDs

func (client *Client) ContainerRemoveByIDs(ctx context.Context, containerIDs ...string) error

ContainerRemoveByIDs deletes all containers which match by their container ids

func (*Client) ContainerRemoveByLabels

func (client *Client) ContainerRemoveByLabels(ctx context.Context, containerLabels map[string]string) error

ContainerRemoveByLabels deletes all containers which match by given labels

func (*Client) ContainerRemoveByNames

func (client *Client) ContainerRemoveByNames(ctx context.Context, containerNames ...string) error

ContainerRemoveByNames deletes all containers which match by their names

func (*Client) ContainerStopByIDs

func (client *Client) ContainerStopByIDs(ctx context.Context, timeout time.Duration, containerIDs ...string) error

ContainerStopByIDs deletes all containers which match by their container ids

func (*Client) ContainerStopByLabels

func (client *Client) ContainerStopByLabels(ctx context.Context, timeout time.Duration, containerLabels map[string]string) error

ContainerStopByLabels shutdown containters which match by given labels

func (*Client) ContainerStopByNames

func (client *Client) ContainerStopByNames(ctx context.Context, timeout time.Duration, containerNames ...string) error

ContainerStopByNames shutdown containters matching by their names

func (*Client) GetWatcher

func (client *Client) GetWatcher() *Watcher

GetWatcher returns a watcher for container health states

func (*Client) NetworkListByLabels

func (client *Client) NetworkListByLabels(ctx context.Context, networkLabels map[string]string) ([]types.NetworkResource, error)

NetworkListByLabels returns networks which match by given labels

func (*Client) NetworkListByNames

func (client *Client) NetworkListByNames(ctx context.Context, networkNames ...string) ([]types.NetworkResource, error)

NetworkListByNames returns networks which match by their names. If a network can not be found, the function returns an error

func (*Client) NetworkRemoveByIDs

func (client *Client) NetworkRemoveByIDs(ctx context.Context, containerIDs ...string) error

NetworkRemoveByIDs remove all networks match by their id

func (*Client) NetworkRemoveByLabels

func (client *Client) NetworkRemoveByLabels(ctx context.Context, containerLabels map[string]string) error

NetworkRemoveByLabels remove all networks which match by given labels

func (*Client) NetworkRemoveByNames

func (client *Client) NetworkRemoveByNames(ctx context.Context, networkNames ...string) error

NetworkRemoveByNames remove all networks match by their names. If a network can not be found, the function returns an error

func (*Client) NewBuilder

func (client *Client) NewBuilder(image string) *Builder

NewBuilder returns a new builder for containers

func (*Client) Pull

func (client *Client) Pull(ctx context.Context, image string, w io.Writer) error

Pull image

func (*Client) PullQuiet

func (client *Client) PullQuiet(ctx context.Context, image string) error

PullQuiet image

func (*Client) VolumeListByLabels

func (client *Client) VolumeListByLabels(ctx context.Context, volumeLabels map[string]string) (volume.VolumeListOKBody, error)

VolumeListByLabels returns volumes which match by given labels

func (*Client) VolumeListByNames

func (client *Client) VolumeListByNames(ctx context.Context, volumeNames ...string) (volume.VolumeListOKBody, error)

VolumeListByNames returns volumes which match by their names. If a volume can not be found, the function returns an error

func (*Client) VolumeRemoveByLabels

func (client *Client) VolumeRemoveByLabels(ctx context.Context, volumeLabels map[string]string) error

VolumeRemoveByLabels remove all volumes match by their labels

func (*Client) VolumeRemoveByNames

func (client *Client) VolumeRemoveByNames(ctx context.Context, volumeNames ...string) error

VolumeRemoveByNames remove all volumes match by their names. If a volume can not be found, the function returns an error

type ErrorMapper

type ErrorMapper func(error) error

type Watcher

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

Watcher is a helper to listen on docker API events to notify if a container is healthy or not.

func (*Watcher) AddListener

func (watcher *Watcher) AddListener(containerID string, errorChannel chan<- error, doneChannel chan<- struct{}) error

func (*Watcher) AddListenerWithErrorMapper

func (watcher *Watcher) AddListenerWithErrorMapper(containerID string, errorChannel chan<- error, doneChannel chan<- struct{}, errorMapper ErrorMapper) error