libmason

README

Libmason 🐳 👷

Libmason an helper library to build client-driven docker container image builder. It is still very experimental.

The goal of libmason is to provide few helpers to ease the pain of creating client-side docker image builder for those who find the Dockerfile and docker build a little bit too limited.

It uses engine-api and is pretty tied to it (some structs of engine-api are popping up for now).

Helpers & Builders

As previously said, libmason provides some helpers to create client-side builders, from the most low-level (almost API level) to some higher level (with concept of Steps, commit/non-commit step, etc…). Those helpers are designed to be composable.

Base

The base Helper is located in the main package (libmason). It's a low level interface (and implementation) of commands that might be needed for a builder (get the image, create a container, commit a container to an image, etc.).

import (
    "github.com/vdemeester/libmason"
    "github.com/docker/engine-api/types"
    "github.com/docker/engine-api/types/container"
)
// […]

ctx := context.Background()

helper := libmason.Newhelper(client)
// […]

image, err := helper.GetImage(ctx, "busybox", types.ImagePullOptions{})
// […]

resp, err := helper.ContainerCreate(ctx, types.ContainerCreateConfig{
    Config: &container.Config{
        Image: image.ID,
    }
}
// […]

imageID, err := helper.ContainerCommit(ctx, resp.ID, types.ContainerCommitOptions{})
// […]

Builder

The builder package currently holds a StepBuilder which consists of a composition of Step executed in order.

import (
    "github.com/vdemeester/libmason/builder"
)
// […]

steps := []Step{
    &MyStep{},
    // A step with that needs to create a container
    builder.WithDefaultCreate(&AnotherStep{}),
    // A step that will commit the container
    builder.WithCommit(&AThirdStep{}),
    // Or remove the container
    builder.WithRemove(&AFourthStep{}),
    // Or all of them ?
    builder.WithCreate(build.WithCommitAndRemove(&MyStep{})),
}

builder := builder.WithSteps(builder.DefaultBuilder(client))
image, err := builder.Run()
// […]

See the godoc on how to create steps.

Documentation

Overview

Package libmason provides the base helper for building client-side builder. It consists of an interface (so that you could use the same helper but with a different backend) and implementation and utils function.

Index

• type DefaultHelper
  • func NewHelper(cli DockerClient) *DefaultHelper
  • func (h *DefaultHelper) ContainerAttach(ctx context.Context, container string, stdin io.Reader, ...) error
  • func (h *DefaultHelper) ContainerCommit(ctx context.Context, container string, options types.ContainerCommitOptions) (string, error)
  • func (h *DefaultHelper) ContainerCreate(ctx context.Context, createConfig types.ContainerCreateConfig) (types.ContainerCreateResponse, error)
  • func (h *DefaultHelper) ContainerKill(ctx context.Context, containerID string) error
  • func (h *DefaultHelper) ContainerRemove(ctx context.Context, container string, options types.ContainerRemoveOptions) error
  • func (h *DefaultHelper) ContainerStart(ctx context.Context, container string) error
  • func (h *DefaultHelper) ContainerWait(ctx context.Context, container string, timeout time.Duration) (int, error)
  • func (h *DefaultHelper) CopyToContainer(ctx context.Context, container string, destPath, srcPath string, ...) error
  • func (h *DefaultHelper) GetImage(ctx context.Context, ref string, options types.ImagePullOptions) (types.ImageInspect, error)
  • func (h *DefaultHelper) TagImage(ctx context.Context, image string, newReference string) error
  • func (h *DefaultHelper) WithOutputWriter(w io.Writer) *DefaultHelper
• type DockerClient
• type Helper

Types

type DefaultHelper

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

DefaultHelper is a client-side builder base helper implementation.

func NewHelper

func NewHelper(cli DockerClient) *DefaultHelper

NewHelper creates a new Helper from a docker client

func (*DefaultHelper) ContainerAttach

func (h *DefaultHelper) ContainerAttach(ctx context.Context, container string, stdin io.Reader, stdout, stderr io.Writer) error

ContainerAttach attaches to container.

func (*DefaultHelper) ContainerCommit

func (h *DefaultHelper) ContainerCommit(ctx context.Context, container string, options types.ContainerCommitOptions) (string, error)

ContainerCommit creates a new Docker image from an existing Docker container.

func (*DefaultHelper) ContainerCreate

func (h *DefaultHelper) ContainerCreate(ctx context.Context, createConfig types.ContainerCreateConfig) (types.ContainerCreateResponse, error)

ContainerCreate creates a new Docker container and returns potential warnings FIXME(vdemeester) should validate options ?

func (*DefaultHelper) ContainerKill

func (h *DefaultHelper) ContainerKill(ctx context.Context, containerID string) error

ContainerKill stops the container execution abruptly.

func (*DefaultHelper) ContainerRemove

func (h *DefaultHelper) ContainerRemove(ctx context.Context, container string, options types.ContainerRemoveOptions) error

ContainerRemove removes a container specified by `id`.

func (*DefaultHelper) ContainerStart

func (h *DefaultHelper) ContainerStart(ctx context.Context, container string) error

ContainerStart starts a new container

func (*DefaultHelper) ContainerWait

func (h *DefaultHelper) ContainerWait(ctx context.Context, container string, timeout time.Duration) (int, error)

ContainerWait stops processing until the given container is stopped.

func (*DefaultHelper) CopyToContainer

func (h *DefaultHelper) CopyToContainer(ctx context.Context, container string, destPath, srcPath string, decompress bool) error

CopyToContainer copies/extracts a source FileInfo to a destination path inside a container specified by a container object.

func (*DefaultHelper) GetImage

func (h *DefaultHelper) GetImage(ctx context.Context, ref string, options types.ImagePullOptions) (types.ImageInspect, error)

GetImage looks up a Docker image referenced by `name` and pull it if needed.

func (*DefaultHelper) TagImage

func (h *DefaultHelper) TagImage(ctx context.Context, image string, newReference string) error

TagImage tags an image with newTag

func (*DefaultHelper) WithOutputWriter

func (h *DefaultHelper) WithOutputWriter(w io.Writer) *DefaultHelper

WithOutputWriter lets you specify a writer for the small amount of output this package will generate (Pull & such)

type DockerClient

type DockerClient interface {
	client.ContainerAPIClient
	client.ImageAPIClient
}

DockerClient defines methods a docker client should provide to libmason. It's simply Container & Image methods from docker client.APIClient.

type Helper

type Helper interface {
	// GetImage looks up a Docker image referenced by `name` and pull it if needed.
	GetImage(ctx context.Context, name string, options types.ImagePullOptions) (types.ImageInspect, error)

	// TagImage tags an image with newTag
	TagImage(ctx context.Context, image string, newReference string) error

	// ContainerCreate creates a new Docker container and returns potential warnings
	ContainerCreate(ctx context.Context, config types.ContainerCreateConfig) (types.ContainerCreateResponse, error)

	// ContainerAttach attaches to container.
	ContainerAttach(ctx context.Context, container string, stdin io.Reader, stdout, stderr io.Writer) error

	// ContainerStart starts a new container
	ContainerStart(ctx context.Context, container string) error

	// ContainerKill stops the container execution abruptly.
	ContainerKill(ctx context.Context, container string) error

	// ContainerRm removes a container specified by `id`.
	ContainerRemove(ctx context.Context, container string, options types.ContainerRemoveOptions) error

	// Commit creates a new Docker image from an existing Docker container.
	ContainerCommit(ctx context.Context, container string, options types.ContainerCommitOptions) (string, error)

	// ContainerWait stops processing until the given container is stopped.
	ContainerWait(ctx context.Context, container string, timeout time.Duration) (int, error)

	// CopyToContainer copies/extracts a source FileInfo to a destination path inside a container
	// specified by a container object.
	CopyToContainer(ctx context.Context, container string, destPath, srcPath string, decompress bool) error
}

Helper abstracts calls to a Docker Daemon for a client-side builder. It is based on a extraction "revisited" of builder/builder.go from the docker project, and define methods a client-side builder might need.