scratchbuild

README

A library and tiny app for directly building very simple docker images & pushing them to a repository without involving the docker daemon, and with no complex dependencies.

	o := scratchbuild.Options{
		Dir:      "./testdata",
		Name:     "philpearl/test",
		BaseURL:  "https://index.docker.io",
		Tag:      "latest",
		User:     "philpearl",
		Password: "sekret",
	}

	b := &bytes.Buffer{}
	if err := scratchbuild.TarDirectory("./testdata", b); err != nil {
		log.Fatalf("failed to tar layer. %s", err)
	}

	c := scratchbuild.New(&o)

	token, err := c.Auth()
	if err != nil {
		log.Fatalf("failed to authorize. %s", err)
	}
	c.Token = token

	if err := c.BuildImage(&scratchbuild.ImageConfig{
		Entrypoint: []string{"/app"},
	}, b.Bytes()); err != nil {
		log.Fatalf("failed to build and send image. %s", err)
	}

Documentation

Overview

Package scratchbuild builds and uploads simple containers. It was built with scratch containers for Go binaries in mind. It requires very few dependencies, does not need a Docker daemon or to run as root!

Index

• Constants
• Variables
• func TarDirectory(dir string, w io.Writer) error
• type Client
  • func New(o *Options) *Client
  • func (c *Client) Auth() (string, error)
  • func (c *Client) BuildImage(imageConfig *ImageConfig, layer []byte) error
• type Descriptor
• type History
• type Image
• type ImageConfig
• type Manifest
• type Options
• type RootFS
• type Versioned

Examples

• Client

Constants

const (
	// MediaTypeManifest specifies the mediaType for the current version.
	MediaTypeManifest = "application/vnd.docker.distribution.manifest.v2+json"

	// MediaTypeImageConfig specifies the mediaType for the image configuration.
	MediaTypeImageConfig = "application/vnd.docker.container.image.v1+json"

	// MediaTypePluginConfig specifies the mediaType for plugin configuration.
	MediaTypePluginConfig = "application/vnd.docker.plugin.v1+json"

	// MediaTypeLayer is the mediaType used for layers referenced by the
	// manifest.
	MediaTypeLayer = "application/vnd.docker.image.rootfs.diff.tar.gzip"

	// MediaTypeForeignLayer is the mediaType used for layers that must be
	// downloaded from foreign URLs.
	MediaTypeForeignLayer = "application/vnd.docker.image.rootfs.foreign.diff.tar.gzip"

	// MediaTypeUncompressedLayer is the mediaType used for layers which
	// are not compressed.
	MediaTypeUncompressedLayer = "application/vnd.docker.image.rootfs.diff.tar"
)

Variables

var (
	// SchemaVersion provides a pre-initialized version structure for this
	// packages version of the manifest.
	SchemaVersion = Versioned{
		SchemaVersion: 2,
		MediaType:     MediaTypeManifest,
	}
)

Functions

func TarDirectory

func TarDirectory(dir string, w io.Writer) error

TarDirectory builds a directory into a tar file. At the moment it does not support subdirectories. dir is the name of the directory to copy into the tar file. The tar file is written into w.

Types

type Client

type Client struct {
	Options
}

Client lets you send a container up to a repository

Example

package main

import (
	"bytes"
	"log"

	"github.com/philpearl/scratchbuild"
)

func main() {
	o := scratchbuild.Options{
		Dir:      "./testdata",
		Name:     "philpearl/test",
		BaseURL:  "https://index.docker.io",
		Tag:      "latest",
		User:     "philpearl",
		Password: "sekret",
	}

	b := &bytes.Buffer{}
	if err := scratchbuild.TarDirectory("./testdata", b); err != nil {
		log.Fatalf("failed to tar layer. %s", err)
	}

	c := scratchbuild.New(&o)

	token, err := c.Auth()
	if err != nil {
		log.Fatalf("failed to authorize. %s", err)
	}
	c.Token = func() string { return token }

	if err := c.BuildImage(&scratchbuild.ImageConfig{
		Entrypoint: []string{"/app"},
	}, b.Bytes()); err != nil {
		log.Fatalf("failed to build and send image. %s", err)
	}
}

func New

func New(o *Options) *Client

New creates a new Client

func (*Client) Auth

func (c *Client) Auth() (string, error)

Auth gets a bearer token from the repository using the user and password from the client Options. If authentication is needed for your repository, call Auth before calling BuildImage

func (*Client) BuildImage

func (c *Client) BuildImage(imageConfig *ImageConfig, layer []byte) error

BuildImage builds a simple container image from a single layer and uploads it to a repository

type Descriptor

type Descriptor struct {
	// MediaType describe the type of the content. All text based formats are
	// encoded as utf-8.
	MediaType string `json:"mediaType,omitempty"`

	// Size in bytes of content.
	Size int64 `json:"size,omitempty"`

	// Digest uniquely identifies the content. A byte stream can be verified
	// against against this digest.
	Digest digest.Digest `json:"digest,omitempty"`

	// URLs contains the source URLs of this content.
	URLs []string `json:"urls,omitempty"`
}

Descriptor contains a reference to a blob

type History

type History struct {
	// Created is the combined date and time at which the layer was created, formatted as defined by RFC 3339, section 5.6.
	Created *time.Time `json:"created,omitempty"`

	// CreatedBy is the command which created the layer.
	CreatedBy string `json:"created_by,omitempty"`

	// Author is the author of the build point.
	Author string `json:"author,omitempty"`

	// Comment is a custom message set when creating the layer.
	Comment string `json:"comment,omitempty"`

	// EmptyLayer is used to mark if the history item created a filesystem diff.
	EmptyLayer bool `json:"empty_layer,omitempty"`
}

History describes the history of a layer.

type Image

type Image struct {
	// Created is the combined date and time at which the image was created, formatted as defined by RFC 3339, section 5.6.
	Created *time.Time `json:"created,omitempty"`

	// Author defines the name and/or email address of the person or entity which created and is responsible for maintaining the image.
	Author string `json:"author,omitempty"`

	// Architecture is the CPU architecture which the binaries in this image are built to run on.
	Architecture string `json:"architecture"`

	// OS is the name of the operating system which the image is built to run on.
	OS string `json:"os"`

	// Config defines the execution parameters which should be used as a base when running a container using the image.
	Config ImageConfig `json:"config,omitempty"`

	// RootFS references the layer content addresses used by the image.
	RootFS RootFS `json:"rootfs"`

	// History describes the history of each layer.
	History []History `json:"history,omitempty"`
}

Image is the JSON structure which describes some basic information about the image. This provides the `application/vnd.oci.image.config.v1+json` mediatype when marshalled to JSON.

type ImageConfig

type ImageConfig struct {
	// User defines the username or UID which the process in the container should run as.
	User string `json:"User,omitempty"`

	// ExposedPorts a set of ports to expose from a container running this image.
	ExposedPorts map[string]struct{} `json:"ExposedPorts,omitempty"`

	// Env is a list of environment variables to be used in a container.
	Env []string `json:"Env,omitempty"`

	// Entrypoint defines a list of arguments to use as the command to execute when the container starts.
	Entrypoint []string `json:"Entrypoint,omitempty"`

	// Cmd defines the default arguments to the entrypoint of the container.
	Cmd []string `json:"Cmd,omitempty"`

	// Volumes is a set of directories describing where the process is likely write data specific to a container instance.
	Volumes map[string]struct{} `json:"Volumes,omitempty"`

	// WorkingDir sets the current working directory of the entrypoint process in the container.
	WorkingDir string `json:"WorkingDir,omitempty"`

	// Labels contains arbitrary metadata for the container.
	Labels map[string]string `json:"Labels,omitempty"`

	// StopSignal contains the system call signal that will be sent to the container to exit.
	StopSignal string `json:"StopSignal,omitempty"`
}

ImageConfig defines the execution parameters which should be used as a base when running a container using an image.

type Manifest

type Manifest struct {
	Versioned

	// Config references the image configuration as a blob.
	Config Descriptor `json:"config"`

	// Layers lists descriptors for the layers referenced by the
	// configuration.
	Layers []Descriptor `json:"layers"`
}

Manifest describes a container image

type Options

type Options struct {
	// Dir is the directory that we build the container from
	Dir string
	// Name is the name of the repository
	Name string
	// BaseURL is the base URL of the repository. For Docker this is https://index.docker.io
	// For GCR it is https://gcr.io
	BaseURL string
	//
	User     string
	Password string
	// Token is the bearer token for the repository. For GCR you can use $(gcloud auth print-access-token).
	// For Docker, supply your Docker Hub username and password instead.
	Token func() string
	// Tag is the tag for the image. Set to "latest" if you're out of ideas
	Tag string
}

Options contains configuration options for the client

type RootFS

type RootFS struct {
	// Type is the type of the rootfs.
	Type string `json:"type"`

	// DiffIDs is an array of layer content hashes (DiffIDs), in order from bottom-most to top-most.
	DiffIDs []digest.Digest `json:"diff_ids"`
}

RootFS describes a layer content addresses

type Versioned

type Versioned struct {
	// SchemaVersion is the image manifest schema that this image follows
	SchemaVersion int `json:"schemaVersion"`

	// MediaType is the media type of this schema.
	MediaType string `json:"mediaType,omitempty"`
}

Versioned indicates the schema version and media type. It is embedded within other types to indicate what the type is