Using containers

The container-related types and structures of the circuit API are in a dedicated package:

	import "github.com/gocircuit/circuit/client/docker"

Container element manipulations and semantics are exactly analogous to their process element counterparts.

Given an anchor object, new containers are created using the anchor method:

	MakeDocker(docker.Run) (docker.Container, error)

The docker.Run argument above is analogous to the Cmd argument in the MakeProc method. It specifies the execution parameters of the container, and is defined as:

type Run struct {
	Image string
	Memory int64
	CpuShares int64
	Lxc []string
	Volume []string
	Dir string
	Entry string
	Env []string
	Path string
	Args []string
	Scrub bool
}

Excluding the field Scrub, all fields exactly match the standard Docker execution parameters which are explained in Docker's help:

	docker help run

The field Scrub is also analogous to its counterpart in the process execution structure Cmd. If Scrub is set, the container element will automatically be detached from the anchor and discarded, as soon as the underlying Docker container exits. If Scrub is not set, the container element will remain attached to the anchor even after the underlying Docker container dies.

The methods of the container element interface are otherwise identical in form and meaning as those of the process element:

type Container interface {
	Scrub()
	Peek() (*docker.Stat, error)
	Signal(sig string) error
	Wait() (*docker.Stat, error)
	Stdin() io.WriteCloser
	Stdout() io.ReadCloser
	Stderr() io.ReadCloser
}

Finally, the docker.Stat structure (not shown here for space considerations) exactly captures all the container status variables that are available through the docker inspect command.

Example

The following snippet shows an example of creating a Docker container with an Ubuntu image, which runs the ls command inside, while also specifying some resource limits and mapping some file system volumes:

	proc, err := anchor.MakeDocker(
		docker.Run{
			Image: "ubuntu",
			Memory: 1000000000,
			CpuShares: 3,
			Volume: []string{"/webapp", "/src/webapp:/opt/webapp:ro"},
			Dir: "/",
			Path: "/bin/ls",
			Args: []string{"/"},
			Scrub: true,
		})

Docker elements are similar to processes.