The way we Go
Boilerplate provides a simple tool which you can use to provision a new Go project with a Makefile, Dockerfile, and associated files.
Boilerplate revolves around 3 concepts, each of which are used to set up your new project:
repository: the name of the source control repository (e.g. github.com)
namespace: the name of the organization/group in the repository (e.g. zulily)
project: the name of the binary (e.g. fizzbuzz)
Boilerplate makes/enforces several assumptions about the structure and conventions of a Go project. Among them:
- The project contains a single binary (aka
package main). The name of this binary is the same as that of the project.
- All dependencies are managed via godep.
- All builds are compiled in a Docker container, using a pinned version of Go (v1.4.2 at the time of writing)
- Binaries are compiled as true static binaries, with no cgo or dynamically-linked networking packages.
- Binaries have the
main.BuildSHAvar set to the latest
gitSHA in the repo. This is accomplished using the Go linker's
- A Docker image is created for the resulting binary, which
execs the binary as the entrypoint.
- The Docker image uses the naming convention
<namespace>/<project>, and is tagged with the latest
gitSHA in the repo.
boilerplate depends on having the following installed on the host machine:
boot2dockerfor OSX users)
boilerplate may be invoked with no arguments, in which case you will be
interactively prompted for the
$ go get github.com/zulily/boilerplate $ boilerplate Enter the name of git repository (e.g. github.com): github.com Enter the namespace in the repository (e.g. zulily): dcarney Enter the name of the project (e.g. fizzbuzz): whizbang GOPATH is: /home/dcarney/go Creating a new project at: /home/dcarney/go/src/github.com/dcarney/whizbang Creating new: .dockerignore Creating new: .gitignore Creating new: Dockerfile Creating new: Makefile Creating new: main.go Initializing git repo Initializing godeps Done
Values for the
project can also be supplied using command line flags:
$ boilerplate -repository=github.com -namespace=zulily -project=fizzbuzz GOPATH is: /home/dcarney/go Creating a new project at: /home/dcarney/go/src/foobar/zulily/fizzbuzz Creating new: .dockerignore Creating new: .gitignore Creating new: Dockerfile Creating new: Makefile Creating new: main.go Initializing git repo Initializing godeps Done
The resulting project can be compiled, linted, and "Dockerized" using the supplied
$ cd $GOPATH/src/foobar/zulily/fizzbuzz $ make building binary for fizzbuzz... $ make lint linting code... main.go:8:6: exported type Foobar should have comment or be unexported main.go:15:2: can probably use "var slice string" instead $ make dockerize building binary for fizzbuzz... running tests for fizzbuzz... building Docker image 'zulily/fizzbuzz'... $ docker images | grep fizzbuzz zulily/fizzbuzz HEAD 4f679023d74c 5 seconds ago 1.94 MB
See the generated
Makefile in your
boilerplate-created project for more details and build targets
Limitations and known issues
Boilerplate was developed on, and is used daily on, various Linux OSes. It has been known to work on OSX with
boot2docker. It has not been used on Windows. (pull requests welcome!)