README.md

Bashbrew

The recommended way to use bashbrew.sh is to install a symlink in your PATH somewhere as bashbrew, for example ~/bin/bashbrew -> /path/to/official-images/bashbrew/bashbrew.sh (assuming ~/bin is in PATH).

$ bashbrew --help

usage: bashbrew [build|push|list] [options] [repo[:tag] ...]
   ie: bashbrew build --all
       bashbrew push debian ubuntu:12.04
       bashbrew list --namespaces='_' debian:7 hello-world

This script processes the specified Docker images using the corresponding
repository manifest files.

common options:
  --all              Build all repositories specified in library
  --docker="docker"
                     Use a custom Docker binary
  --retries="4"
                     How many times to try again if the build/push fails before
                     considering it a lost cause (always attempts a minimum of
                     one time, but maximum of one plus this number)
  --help, -h, -?     Print this help message
  --library="/home/tianon/docker/stackbrew/library"
                     Where to find repository manifest files
  --logs="/home/tianon/docker/stackbrew/bashbrew/logs"
                     Where to store the build logs
  --namespaces="_"
                     Space separated list of image namespaces to act upon
                     
                     Note that "_" is a special case here for the unprefixed
                     namespace (ie, "debian" vs "library/debian"), and as such
                     will be implicitly ignored by the "push" subcommand
                     
                     Also note that "build" will always tag to the unprefixed
                     namespace because it is necessary to do so for dependent
                     images to use FROM correctly (think "onbuild" variants that
                     are "FROM base-image:some-version")
  --uniq
                     Only process the first tag of identical images
                     This is not recommended for build or push
                     i.e. process python:2.7, but not python:2

build options:
  --no-build         Don't build, print what would build
  --no-clone         Don't pull/clone Git repositories
  --src="/home/tianon/docker/stackbrew/bashbrew/src"
                     Where to store cloned Git repositories (GOPATH style)

push options:
  --no-push          Don't push, print what would push

Subcommands

bashbrew build

This script reads the library files for the images specified and then clones the required Git repositories into the specified --src directory. If the Git repository already exists, the script verifies that the Git ref specified in the library file exists and does git fetch as necessary.

The next step in the script is to build each image specified. All the image:tag combinations are placed into a queue. The processing order is determined by the order of items passed in on the command line (or alphabetical if --all is used). When a whole image, like debian, is specified the image:tag combinations are added to the queue in the order that they appear in the library file. For each image:tag to be processed, the system checks out the specified commit and sets mtimes (see git-set-mtimes) of all files in the Git repository to take advantage of Docker caching. If the image:tag is FROM another image that is later in the queue, it is deferred to the end of the queue.

After the image is built, the final step of the script is to tag the image into each of the given --namespaces.

The --no-clone option skips the git clone step and will cause the script to fail on the build step if the Git repository does not exist or is missing the required Git refs.

The --no-build option skips all the building, including setting the mtimes.

WARNING: setting --src so that it uses a local working copy of your Git directory for a specified build will delete untracked and uncommitted changes, and will disable gc.auto. It is not recommended to symlink in your working directories for use during build.

bashbrew push

This script takes advantage of docker login and does a docker push on each image:tag specified for the given --namespaces. The script will warn if a given namespace/image:tag does not exist.

The --no-push option prints out the docker push instructions that would have been executed.

bashbrew list

Takes the same arguments as bashbrew build and bashbrew push, but prints a list of image names and quits.

For example:

$ # count the number of tags in the official library
$ bashbrew list --all | wc -l
802
$ # count the number of _unique_ tags in the official library
$ bashbrew list --all --uniq | wc -l
296

$ # pull all officially supported tags of "debian"
$ bashbrew list debian | xargs -n1 --verbose docker pull
...

$ # list all unique supported tags of "python"
$ bashbrew list --uniq python
python:2.7.10
python:2.7.10-onbuild
python:2.7.10-slim
python:2.7.10-wheezy
python:3.2.6
python:3.2.6-onbuild
python:3.2.6-slim
python:3.2.6-wheezy
python:3.3.6
python:3.3.6-onbuild
python:3.3.6-slim
python:3.3.6-wheezy
python:3.4.3
python:3.4.3-onbuild
python:3.4.3-slim
python:3.4.3-wheezy

Helper Scripts

git-set-mtimes

Since Docker caching of layers is based upon the mtimes of files and folders, this script sets each file's mtime to the time of the commit that most recently modified it and sets each directory's mtime to be the most recent mtime of any file or folder contained within it. This gives a deterministic time for all files and folders in the Git repository.