scratchbuild: Index | Examples | Files

package scratchbuild

import ""

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!



Package Files

auth.go build.go doc.go send.go tar.go types.go


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"


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

func TarDirectory Uses

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.

type Client Uses

type Client struct {

Client lets you send a container up to a repository


o := scratchbuild.Options{
    Dir:      "./testdata",
    Name:     "philpearl/test",
    BaseURL:  "",
    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)

func New Uses

func New(o *Options) *Client

New creates a new Client

func (*Client) Auth Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

type Manifest struct {

    // 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 Uses

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
    // For GCR it is
    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 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 Uses

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 Uses

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

Package scratchbuild imports 17 packages (graph). Updated 2018-06-29. Refresh now. Tools for package owners.