added README and examples

README.md

@@ -1,27 +1,148 @@
-# Template Docker Makefile
-This is a template Makefile for building and releasing Docker images and build the Docker image based on your git tag.
+# Generic Docker Makefile
+When working with the Docker hub, two little things bothered me:
 
+1. Waiting for your build to start
+2. No easy control over the tags for the images.
 
-The release of your docker image is kept in the file .release and uses the following format:
-
-	<major>.<minor>.<patch>
-
-the git tag will have the format:
-
-	docker-$(NAME)-<major>.<minor>.<patch>
-
-and will allow you to tag different Docker containers in a single Git repository.
-
+To resolve these to issues, I created a generic Makefile that allows you to build and release docker images based upon git tags, whenever you want.
 
+## Makefile targets
 
 The Makefile has the following targets:
 ```
 make patch-release	increments the patch release level
 make minor-release	increments the minor release level and sets patch level to 0
 make major-release	increments the major release level and sets both minor and patch level to 0
 make build		builds a new version of your Docker image and tags it
-make release		builds a new version of your Docker images and pushes it to your repository
-make check-status	will check whether there are outstanding changes 
+make check-status	will check whether there are outstanding changes
 make check-release	will check whether the current directory matches the tagged release in git.
+make showver		will show the current release tag based on the directory content.
+```
+
+
+## How to use it.
+copy the Makefile and .make-release-support into your Docker git project:
+
+```bash
+wget https://raw.githubusercontent.com/mvanholsteijn/docker-makefile/master/Makefile
+wget https://raw.githubusercontent.com/mvanholsteijn/docker-makefile/master/.make-release-support
+```
+
+## Change registry, user or image name
+By default, the registry is set to docker.io and the user to the current user. To override this, edit the Makefile
+and set the variables REGISTRY_HOST, USERNAME and NAME.
+
+```Makefile
+REGISTRY_HOST=myregistry.io
+USERNAME=mvanholsteijn
+NAME=awesome-image
+```
+
+## Building an image
+to build an image, just type make:
+
+```bash
+make
+```
+
+##  Release
+To make a release and tag it, commit add the changes and type:
+
+```bash
+make	patch-release
+```
+
+This will bump the patch-release number, build the image and push it to the registry. It will only
+release if there are no outstanding changes and the content of the directory equals the tagged content.
+
+Alternatively you can choose 'make minor-release' or 'make major-release' to bump the associated number.
+
+## Release number
+The release of your docker image is kept in the file .release and uses the following format:
+
+	release=<major>.<minor>.<patch>
+
+The name of the git tag is kept in the same file, and by default will have the format:
+
+	tag=<directory-name>.<minor>.<patch>
+
+This will allow you to have track and tag mulitple images in a single Git repository.
+
+If you want to use a different tag prefix, change it in the .release.
+
+## Image name and tag
+The name of the image will be created as follows:
+
+```
+	<registry-host>/<username>/<directory name>:<tag>
+```
+
+The tag is has the following format:
+
+<table >
+<tr><th>format</th><th>when</th></tr>
+<tr><td valign=top>&lt;release> </td><td>  the contents of the directory is equal to tagged content in git
+
+</td></tr>
+<tr><td valign=top> &lt;release>-&lt;commit> </td><td>  the contents of the directory is not equal to the tagged content
+</td>
+</tr>
+<tr><td valign=top> &lt;release>-&lt;commit>-dirty <td> the contents of the directory has uncommitted changes
+</td></tr>
+</table>
+
+## Multiple docker images in a single git repository.
+
+If you want to maintain multiple docker images in a single git repository, you can use an alternate setup where the Makefile is located in a  silbing directory.
+
+```
+├── (multiple-example)
+│   ├── [image1](multiple-example/image1)
+│   │   ├── [.release](multiple-example/image1/.release)
+│   │   ├── [Dockerfile](multiple-example/image1/Dockerfile)
+│   │   └── [Makefile](multiple-example/image1/Makefile)
+│   ├── [image2](multiple-example/image2)
+│   │   ├── [.release](multiple-example/image2/.release)
+│   │   ├── [Dockerfile](multiple-example/image2/Dockerfile)
+│   │   └── [Makefile](multiple-example/image2/Makefile)
+│   ├── ...
+│   └── [make](multiple-example/make)
+│       ├── [.make-release-support](multiple-example/make/.make-release-support)
+│       └── [Makefile](multiple-example/make/Makefile)
+```
+The image directories will include the generic Makefile. In this Makefile you can alter the names and tailor the build by adding pre and post build targets.
+
+
+
+### Create the generic make directory
+
+To create the generic make directory, type:
+
+```bash
+mkdir make
+cd make
+wget  https://raw.githubusercontent.com/mvanholsteijn/docker-makefile/master/Makefile  
+wget  https://raw.githubusercontent.com/mvanholsteijn/docker-makefile/master/.make-release-support
+sed -i ""  -e 's/^RELEASE_SUPPORT=.*/RELEASE_SUPPORT=..\/make\/.make-release-support/' Makefil``
+
+### Create docker image directory
+For each docker images, you create a sibling directory:
+
+```bash
+mkdir ../image1
+cd ../image1
+
+cat > Makefile <<!
+include ../make/Makefile
+
+USERNAME=mvanholsteijn
+
+pre-build:
+	@echo do some stuff before the docker build
+
+post-build:
+	@echo do some stuff after the docker build
+!
 ```
 
+Now you can use the make build and release instructions to build these images.

multiple-example/image1/.release

@@ -0,0 +1,2 @@
+release=0.0.0
+tag=image1-0.0.0

multiple-example/image1/Dockerfile

@@ -0,0 +1 @@
+FROM busybox

multiple-example/image1/Makefile

@@ -0,0 +1,2 @@
+include ../make/Makefile
+

multiple-example/image2/.release

@@ -0,0 +1,2 @@
+release=0.0.0
+tag=image2-0.0.0

multiple-example/image2/Dockerfile

@@ -0,0 +1 @@
+FROM busybox

multiple-example/image2/Makefile

@@ -0,0 +1,8 @@
+include ../make/Makefile
+
+pre-build:
+	@echo do some stuff before the docker build
+
+post-build:
+	@echo do some stuff after the docker build
+

multiple-example/make/.make-release-support

@@ -0,0 +1 @@
+../../.make-release-support

multiple-example/make/Makefile

@@ -0,0 +1,77 @@
+#
+#   Copyright 2015  Xebia Nederland B.V.
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+REGISTRY_HOST=docker.io
+USERNAME=$(USER)
+NAME=$(shell basename $(PWD))
+
+RELEASE_SUPPORT=../make/.make-release-support
+IMAGE=$(REGISTRY_HOST)/$(USERNAME)/$(NAME)
+
+VERSION=$(shell . $(RELEASE_SUPPORT) ; getVersion)
+TAG=$(shell . $(RELEASE_SUPPORT); getTag)
+
+SHELL=/bin/bash
+
+.PHONY: pre-build docker-build post-build build release patch-release minor-release major-release tag check-status check-release showver
+
+build: pre-build docker-build post-build
+
+pre-build:
+
+
+post-build:
+
+
+docker-build: .release
+	docker build -t $(IMAGE):$(VERSION) .
+	docker tag  -f $(IMAGE):$(VERSION) $(IMAGE):latest
+
+.release: 
+	@echo "release=0.0.0" > .release
+	@echo "tag=$(NAME)-0.0.0" >> .release
+	@echo INFO: .release created
+	@cat .release
+
+release: check-status check-release build
+	docker push $(IMAGE):$(VERSION)
+	docker push $(IMAGE):latest
+
+showver: .release
+	@. $(RELEASE_SUPPORT); getVersion
+
+patch-release: VERSION = $(shell . $(RELEASE_SUPPORT); nextPatchLevel)
+patch-release: tag release
+
+minor-release: VERSION = $(shell . $(RELEASE_SUPPORT); nextMinorLevel)
+minor-release: tag release
+
+major-release: VERSION = $(shell . $(RELEASE_SUPPORT); nextMajorLevel)
+major-release: tag release
+
+tag: TAG=$(shell . $(RELEASE_SUPPORT); getTag $(VERSION))
+tag: check-status
+	@. $(RELEASE_SUPPORT) ; ! tagExists $(TAG) || (echo "ERROR: tag $(TAG) for version $(VERSION) already tagged in git" >&2 && exit 1) ;
+	@. $(RELEASE_SUPPORT) ; setRelease $(VERSION)
+	git add .release
+	git commit -m "bumped to version $(VERSION)" ;
+	git tag $(TAG) ;
+
+check-status:
+	@. $(RELEASE_SUPPORT) ; ! hasChanges || (echo "ERROR: there are still outstanding changes" >&2 && exit 1) ;
+
+check-release:
+	@. $(RELEASE_SUPPORT) ; tagExists $(TAG) || (echo "ERROR: version not yet tagged in git. make [minor,major,patch]-release." >&2 && exit 1) ;
+	@. $(RELEASE_SUPPORT) ; ! differsFromRelease $(TAG) || (echo "ERROR: current directory differs from tagged $(TAG). make [minor,major,patch]-release." ; exit 1)

multiple-example/make/install

@@ -0,0 +1,4 @@
+#!/bin/bash
+sed -e 's/^RELEASE_SUPPORT=.*/RELEASE_SUPPORT=..\/make\/.make-release-support/' ../../Makefile > Makefile
+ln -sf ../../.make-release-support .
+

single-example/.make-release-support

@@ -0,0 +1 @@
+../.make-release-support

single-example/.release

@@ -0,0 +1,2 @@
+release=0.0.0
+tag=example-0.0.0

single-example/Dockerfile

@@ -0,0 +1 @@
+FROM busybox

single-example/Makefile

@@ -0,0 +1 @@
+../Makefile