docker-library
/
bashbrew
mirror of https://github.com/docker-library/bashbrew.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Adjust the bashbrew README to be closer to the truth

This commit is contained in:
Tianon Gravi 2015-06-01 15:27:53 -07:00
parent 8e5d85dc7e
commit bd63adf3b7
1 changed files with 86 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
README.md
View File

@ -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`