From bd63adf3b70f0e24b25f6a8951485d0bac513bd9 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Mon, 1 Jun 2015 15:27:53 -0700 Subject: [PATCH] Adjust the bashbrew README to be closer to the truth --- README.md | 128 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 86 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 61d3dc3..9cfffa3 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,62 @@ # Bashbrew -## Main Scripts - -### `build.sh` +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`). ```console -$ ./bashbrew/build.sh --help +$ bashbrew --help -usage: ./bashbrew/build.sh [options] [repo[:tag] ...] - ie: ./bashbrew/build.sh --all - ./bashbrew/build.sh debian ubuntu:12.04 +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 builds the Docker images specified using the Git repositories - specified in the library files. +This script processes the specified Docker images using the corresponding +repository manifest files. -options: +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 - --all Builds all Docker repos specified in library - --no-clone Don't pull the Git repos - --no-build Don't build, just echo what would have built - --library="./stackbrew/library" + --library="/home/tianon/docker/stackbrew/library" Where to find repository manifest files - --src="./stackbrew/bashbrew/src" - Where to store the cloned Git repositories - --logs="./stackbrew/bashbrew/logs" + --logs="/home/tianon/docker/stackbrew/bashbrew/logs" Where to store the build logs - --namespaces="library stackbrew" - Space separated list of namespaces to tag images in after - building + --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`](#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. @@ -42,33 +69,50 @@ 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. -### `push.sh` - -```console -$ ./bashbrew/push.sh --help - -usage: ./bashbrew/push.sh [options] [repo[:tag] ...] - ie: ./bashbrew/push.sh --all - ./bashbrew/push.sh debian ubuntu:12.04 - - This script pushes the specified Docker images from library that are built - and tagged in the specified namespaces. - -options: - --help, -h, -? Print this help message - --all Pushes all Docker images built for the given namespaces - --no-push Don't actually push the images to the Docker Hub - --library="./stackbrew/library" - Where to find repository manifest files - --namespaces="library stackbrew" - Space separated list of namespaces to tag images in after - building -``` +### `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: + +```console +$ # 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`