25thfloor/docker-make-stub

•Updated over 7 years ago

Just use the docker-make-stub, without having to copy .mk files

Image

1.7K

25thfloor/docker-make-stub repository overview

⁠Docker Make Stub

The idea behind this project is to provide a generalized, (more or less) opinioated and convenient make/Makefile stub, focused on "All things Docker". It can be utilized by developers and maschines alike (e.g. TeamCity, Jenkins, GoCD, ...)

Except for the auto-generated help, the stub does not implement any make. Its purpose is to provide a common target-naming for different purposes, the means to easily define variables and a color-coded (xterm-256), auto-generated usage/help.

Currently available stubs:

docker.mk for docker
docker-compose.mk for docker-compose
rancher-compose.mk for rancher-compose

⁠How to use it

⁠The Makefile

To make it work, the only thing you have to add at least the common.mk to your project/repository. Add other .mk files depending on your context (pure Docker, docker-compose, Rancher using rancher-compose) Next add add the following at the beginning of your Makefile

# Include available stubs
include *.mk

Every .mk comes with an opinionated list of targets relevant for the corresponding context and a "default documentation". Targets that have been implemented in your Makefile are color-coded as yellow (name) and green (documentation), all others are displayed in red.

⁠Implement stub targets

It is totally up to you how targets behave and what they do. To implement a target, add the following to your Makefile:

.PHONY: target
target:: ##@MyCategory This is a description of what this target does.
	@echo "Yay!"

Valid target descriptions are:

##@MyCategory<space>Description
##@My<space>category<space>rocks<tab>Description

Important: You have to implement targets as Double-Colon Rule⁠ because the .mk files define it this way.

If the stub defines a target pre-categorized in e.g. Docker, you can also override this in your own documentation:

run:: ##@Compose I want run in Compose not Docker

The make help auto-generation will detect this and display only one run categorized under Compose instead of both of them (one below Docker and one below Compose)

⁠Variables and adding variables

When creating all this, the following requirements had been defined:

any (overrideable) variable relevant for any target's behaviour and its value should be automatically displayed in make help
variables must be overrideable as you'd expect it from make using e.g.
- make VAR=value mytarget
- VAR=value make mytarget or
- export VAR=value; make mytarget
all (and only) these variables should be able to pass to a sub-process, which can use them to interpolate them (e.g. in docker-compose.yml)
internal make variables should not pollute the usage/help

⁠Defining variables

Do define a variable that suffices these criteria, add the following at the beginnging of your Makefile

# Docker
$(eval $(call defw,NS,mydockerhub.mydomain.com/mynamespace))
$(eval $(call defw,REPO,myprojectrepo))
$(eval $(call defw,VERSION,latest))

Your CI (e.g. TeamCity) can then define a build-step like this:

make VERSION=build-%build.counter% deploy

⁠The special `$(shell_env)`

In order to pass all your defined variables to a sub-process for further use in e.g. docker-compose.yml add the special variable $(shell_env) in front of your call:

$(eval $(call defw,MY_VAR1,value1))
$(eval $(call defw,MY_VAR2,value2))
...

.PHONY: deploy
deploy: ##@MyTargets this is a target
	$(shell_env) rancher-compose up -d

This results in rancher-compose up -d being called with

MY_VAR1="value1" MY_VAR2="value2" rancher-compose up -d

For an example see below.

⁠Note

We already experimented with integrating Hasicorp's Vault⁠ for variables that contain secrets which should not be stored in any VCS, for example:

$(deval $(call defw,RANCHER_ACCESS_KEY,$(call vault,rancher/api,.data.access_key)
$(deval $(call defw,RANCHER_SECRET_KEY,$(call vault,rancher/api,.data.secret_key)

This is still experimental and has not been added to this repository yet! It's documented here just to give you an idea of what could (should) be possible.

⁠Docker image

See https://hub.docker.com/r/25thfloor/docker-make-stub/⁠ - documentation pending!

⁠Implementation examples

⁠docker

# Docker
$(eval $(call defw,NS,myhub.docker.example.com/mynamespace))
$(eval $(call defw,REPO,myrepo))
$(eval $(call defw,VERSION,latest))
$(eval $(call defw,NAME,my-run-name))

.PHONY: build
build:: ##@Docker Build an image
	docker build --pull -t $(NS)/$(REPO):$(VERSION) .

.PHONY: ship
ship:: ##@Docker Ship the image (build, ship)
ship:: build
	docker push $(NS)/$(REPO):$(VERSION)

.PHONY: run
run:: ##@Docker Run a container (build, run attached)
run:: build
	docker run --rm --name $(NAME) $(PORTS) $(VOLUMES) $(ENVS) $(NS)/$(REPO):$(VERSION)

.PHONY: start
start:: ##@Docker Run a container (build, run detached)
start:: build start
	docker run -d --name $(NAME) $(PORTS) $(VOLUMES) $(ENVS) $(NS)/$(REPO):$(VERSION)

.PHONY: stop
stop:: ##@Docker Stop the running container
	docker stop $(NAME)
    
.PHONY: clean
clean:: ##@Docker Remove the container
	docker rm -f $(NAME)

.PHONY: release
release:: ##@Docker Build and Ship
release:: build ship

⁠Usage example

make build
make VERSION=testing build
make PORTS="-p 8080:80" run
make NAME=justtesting start

⁠docker-compose

.PHONY: up
up:: ##@Compose Start the whole thing
	docker-compose up

⁠rancher-compose

.PHONY: deploy
deploy:: ##@Rancher Deploy/Upgrade the stack, finishing earlier upgrades (build, ship, finish, deploy)
deploy:: build ship finish
    $(shell_env) rancher-compose -p $(RANCHER_STACK_NAME) up -d --upgrade

.PHONY: finish
finish:: ##@Rancher Finish an earlier upgrade
    $(shell_env) rancher-compose -p $(RANCHER_STACK_NAME) up -d --confirm-upgrade

.PHONY: rollback
rollback:: ##@Rancher Rollback an active upgrade
    $(shell_env) rancher-compose -p $(RANCHER_STACK_NAME) up -d --rollback

For information regarding the $(shell_env)) see above.

⁠rancher-compose with traefik labels

myapp:
  labels:
    io.rancher.container.pull_image: always
    io.rancher.container.hostname_override: container_name
    traefik.frontend.rule: ${TRAEFIK_FRONTEND_RULE}
    traefik.port: ${TRAEFIK_PORT}
  image: ${NS}/${REPO}:${VERSION}

$(eval $(call defw,TRAEFIK_FRONTEND_RULE,Host:www.myapp.com))
$(eval $(call defw,TRAEFIK_PORT,8080))

.PHONY: deploy
deploy:: ##@Rancher Deploy/Upgrade the stack, finishing earlier upgrades (build, ship, finish, deploy)
deploy:: build ship finish
    $(shell_env) rancher-compose -p $(RANCHER_STACK_NAME) up -d --upgrade

⁠Functions

You can redefine functions (update-safe) by adding e.g. .stub/z-common.mk with:

define verbose_info
	@echo ${TURQUOISE}
	@echo ------------------------------ I like dashes more ------------------------------
	@echo ${1}
	@echo ------------------------------
	@echo
	@tput -Txterm sgr0 # ${RESET} won't work here for some reason
endef

⁠verbose_info

target:: ##@Category Description
	$(call verbose_info,Doing something here)
	...

⁠verbose_warning

target:: ##@Category Description
	$(call verbose_warning,Doing something here)
	...

⁠verbose_error

target:: ##@Category Description
	$(call verbose_error,Doing something here)
	...

⁠Example output

Clone this repository and just call make help and/or make all.

⁠Credits

prwhite⁠ for the initial idea of self-documenting targets (https://gist.github.com/prwhite/8168133⁠)
lordnynex⁠ for https://gist.github.com/prwhite/8168133#gistcomment-1712123⁠
HarasimowiczKamil⁠ for https://gist.github.com/prwhite/8168133#gistcomment-1727513⁠
boutin⁠ and dready⁠ for feedback and challenging the idea/concept

⁠Todo

allow categorization for variables too, maybe even bundle categorized variables with their correspondig, categorized targets for make help
add example implementations for docker, docker-compose and rancher-compose

Tag summary

Recent tags

Content type

Image

Digest

Size

109.6 MB

Last updated

over 7 years ago

docker pull 25thfloor/docker-make-stub