project/PACKAGERS.md - third_party/github.com/moby/moby - Git at Google

 # Dear Packager,

 If you are looking to make Docker available on your favorite software
 distribution, this document is for you. It summarizes the requirements for
 building and running the Docker client and the Docker daemon.

 ## Getting Started

 We want to help you package Docker successfully. Before doing any packaging, a
 good first step is to introduce yourself on the [docker-dev mailing
 list](https://groups.google.com/d/forum/docker-dev), explain what you're trying
 to achieve, and tell us how we can help. Don't worry, we don't bite! There might
 even be someone already working on packaging for the same distro!

 You can also join the IRC channel - #docker and #docker-dev on Freenode are both
 active and friendly.

 We like to refer to Tianon ("@tianon" on GitHub and "tianon" on IRC) as our
 "Packagers Relations", since he's always working to make sure our packagers have
 a good, healthy upstream to work with (both in our communication and in our
 build scripts). If you're having any kind of trouble, feel free to ping him
 directly. He also likes to keep track of what distributions we have packagers
 for, so feel free to reach out to him even just to say "Hi!"

 ## Package Name

 If possible, your package should be called "docker". If that name is already
 taken, a second choice is "docker-engine". Another possible choice is "docker.io".

 ## Official Build vs Distro Build

 The Docker project maintains its own build and release toolchain. It is pretty
 neat and entirely based on Docker (surprise!). This toolchain is the canonical
 way to build Docker. We encourage you to give it a try, and if the circumstances
 allow you to use it, we recommend that you do.

 You might not be able to use the official build toolchain - usually because your
 distribution has a toolchain and packaging policy of its own. We get it! Your
 house, your rules. The rest of this document should give you the information you
 need to package Docker your way, without denaturing it in the process.

 ## Build Dependencies

 To build Docker, you will need the following:

 * A recent version of Git and Mercurial
 * Go version 1.6 or later
 * A clean checkout of the source added to a valid [Go
   workspace](https://golang.org/doc/code.html#Workspaces) under the path
   *src/github.com/docker/docker* (unless you plan to use `AUTO_GOPATH`,
   explained in more detail below)

 To build the Docker daemon, you will additionally need:

 * An amd64/x86_64 machine running Linux
 * SQLite version 3.7.9 or later
 * libdevmapper version 1.02.68-cvs (2012-01-26) or later from lvm2 version
   2.02.89 or later
 * btrfs-progs version 3.16.1 or later (unless using an older version is
   absolutely necessary, in which case 3.8 is the minimum)
 * libseccomp version 2.2.1 or later (for build tag seccomp)

 Be sure to also check out Docker's Dockerfile for the most up-to-date list of
 these build-time dependencies.

 ### Go Dependencies

 All Go dependencies are vendored under "./vendor". They are used by the official
 build, so the source of truth for the current version of each dependency is
 whatever is in "./vendor".

 To use the vendored dependencies, simply make sure the path to "./vendor" is
 included in `GOPATH` (or use `AUTO_GOPATH`, as explained below).

 If you would rather (or must, due to distro policy) package these dependencies
 yourself, take a look at "vendor.conf" for an easy-to-parse list of the
 exact version for each.

 NOTE: if you're not able to package the exact version (to the exact commit) of a
 given dependency, please get in touch so we can remediate! Who knows what
 discrepancies can be caused by even the slightest deviation. We promise to do
 our best to make everybody happy.

 ## Stripping Binaries

 Please, please, please do not strip any compiled binaries. This is really
 important.

 In our own testing, stripping the resulting binaries sometimes results in a
 binary that appears to work, but more often causes random panics, segfaults, and
 other issues. Even if the binary appears to work, please don't strip.

 See the following quotes from Dave Cheney, which explain this position better
 from the upstream Golang perspective.

 ### [go issue #5855, comment #3](https://code.google.com/p/go/issues/detail?id=5855#c3)

 > Super super important: Do not strip go binaries or archives. It isn't tested,
 > often breaks, and doesn't work.

 ### [launchpad golang issue #1200255, comment #8](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/8)

 > To quote myself: "Please do not strip Go binaries, it is not supported, not
 > tested, is often broken, and doesn't do what you want"
 >
 > To unpack that a bit
 >
 > * not supported, as in, we don't support it, and recommend against it when
 >   asked
 > * not tested, we don't test stripped binaries as part of the build CI process
 > * is often broken, stripping a go binary will produce anywhere from no, to
 >   subtle, to outright execution failure, see above

 ### [launchpad golang issue #1200255, comment #13](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/13)

 > To clarify my previous statements.
 >
 > * I do not disagree with the debian policy, it is there for a good reason
 > * Having said that, it stripping Go binaries doesn't work, and nobody is
 >   looking at making it work, so there is that.
 >
 > Thanks for patching the build formula.

 ## Building Docker

 Please use our build script ("./hack/make.sh") for all your compilation of
 Docker. If there's something you need that it isn't doing, or something it could
 be doing to make your life as a packager easier, please get in touch with Tianon
 and help us rectify the situation. Chances are good that other packagers have
 probably run into the same problems and a fix might already be in the works, but
 none of us will know for sure unless you harass Tianon about it. :)

 All the commands listed within this section should be run with the Docker source
 checkout as the current working directory.

 ### `AUTO_GOPATH`

 If you'd rather not be bothered with the hassles that setting up `GOPATH`
 appropriately can be, and prefer to just get a "build that works", you should
 add something similar to this to whatever script or process you're using to
 build Docker:

 ```bash
 export AUTO_GOPATH=1
 ```

 This will cause the build scripts to set up a reasonable `GOPATH` that
 automatically and properly includes both docker/docker from the local
 directory, and the local "./vendor" directory as necessary.

 ### `DOCKER_BUILDTAGS`

 If you're building a binary that may need to be used on platforms that include
 AppArmor, you will need to set `DOCKER_BUILDTAGS` as follows:
 ```bash
 export DOCKER_BUILDTAGS='apparmor'
 ```

 If you're building a binary that may need to be used on platforms that include
 SELinux, you will need to use the `selinux` build tag:
 ```bash
 export DOCKER_BUILDTAGS='selinux'
 ```

 If you're building a binary that may need to be used on platforms that include
 seccomp, you will need to use the `seccomp` build tag:
 ```bash
 export DOCKER_BUILDTAGS='seccomp'
 ```

 There are build tags for disabling graphdrivers as well. By default, support
 for all graphdrivers are built in.

 To disable btrfs:
 ```bash
 export DOCKER_BUILDTAGS='exclude_graphdriver_btrfs'
 ```

 To disable devicemapper:
 ```bash
 export DOCKER_BUILDTAGS='exclude_graphdriver_devicemapper'
 ```

 To disable aufs:
 ```bash
 export DOCKER_BUILDTAGS='exclude_graphdriver_aufs'
 ```

 NOTE: if you need to set more than one build tag, space separate them:
 ```bash
 export DOCKER_BUILDTAGS='apparmor selinux exclude_graphdriver_aufs'
 ```

 ### Static Daemon

 If it is feasible within the constraints of your distribution, you should
 seriously consider packaging Docker as a single static binary. A good comparison
 is Busybox, which is often packaged statically as a feature to enable mass
 portability. Because of the unique way Docker operates, being similarly static
 is a "feature".

 To build a static Docker daemon binary, run the following command (first
 ensuring that all the necessary libraries are available in static form for
 linking - see the "Build Dependencies" section above, and the relevant lines
 within Docker's own Dockerfile that set up our official build environment):

 ```bash
 ./hack/make.sh binary
 ```

 This will create a static binary under
 "./bundles/$VERSION/binary/docker-$VERSION", where "$VERSION" is the contents of
 the file "./VERSION". This binary is usually installed somewhere like
 "/usr/bin/docker".

 ### Dynamic Daemon / Client-only Binary

 If you are only interested in a Docker client binary, you can build using:

 ```bash
 ./hack/make.sh binary-client
 ```

 If you need to (due to distro policy, distro library availability, or for other
 reasons) create a dynamically compiled daemon binary, or if you are only
 interested in creating a client binary for Docker, use something similar to the
 following:

 ```bash
 ./hack/make.sh dynbinary-client
 ```

 This will create "./bundles/$VERSION/dynbinary-client/docker-$VERSION", which for
 client-only builds is the important file to grab and install as appropriate.

 ## System Dependencies

 ### Runtime Dependencies

 To function properly, the Docker daemon needs the following software to be
 installed and available at runtime:

 * iptables version 1.4 or later
 * procps (or similar provider of a "ps" executable)
 * e2fsprogs version 1.4.12 or later (in use: mkfs.ext4, tune2fs)
 * xfsprogs (in use: mkfs.xfs)
 * XZ Utils version 4.9 or later
 * a [properly
   mounted](https://github.com/tianon/cgroupfs-mount/blob/master/cgroupfs-mount)
   cgroupfs hierarchy (having a single, all-encompassing "cgroup" mount point
   [is](https://github.com/docker/docker/issues/2683)
   [not](https://github.com/docker/docker/issues/3485)
   [sufficient](https://github.com/docker/docker/issues/4568))

 Additionally, the Docker client needs the following software to be installed and
 available at runtime:

 * Git version 1.7 or later

 ### Kernel Requirements

 The Docker daemon has very specific kernel requirements. Most pre-packaged
 kernels already include the necessary options enabled. If you are building your
 own kernel, you will either need to discover the options necessary via trial and
 error, or check out the [Gentoo
 ebuild](https://github.com/tianon/docker-overlay/blob/master/app-emulation/docker/docker-9999.ebuild),
 in which a list is maintained (and if there are any issues or discrepancies in
 that list, please contact Tianon so they can be rectified).

 Note that in client mode, there are no specific kernel requirements, and that
 the client will even run on alternative platforms such as Mac OS X / Darwin.

 ### Optional Dependencies

 Some of Docker's features are activated by using optional command-line flags or
 by having support for them in the kernel or userspace. A few examples include:

 * AUFS graph driver (requires AUFS patches/support enabled in the kernel, and at
   least the "auplink" utility from aufs-tools)
 * BTRFS graph driver (requires BTRFS support enabled in the kernel)
 * ZFS graph driver (requires userspace zfs-utils and a corresponding kernel module)
 * Libseccomp to allow running seccomp profiles with containers

 ## Daemon Init Script

 Docker expects to run as a daemon at machine startup. Your package will need to
 include a script for your distro's process supervisor of choice. Be sure to
 check out the "contrib/init" folder in case a suitable init script already
 exists (and if one does not, contact Tianon about whether it might be
 appropriate for your distro's init script to live there too!).

 In general, Docker should be run as root, similar to the following:

 ```bash
 dockerd
 ```

 Generally, a `DOCKER_OPTS` variable of some kind is available for adding more
 flags (such as changing the graph driver to use BTRFS, switching the location of
 "/var/lib/docker", etc).

 ## Communicate

 As a final note, please do feel free to reach out to Tianon at any time for
 pretty much anything. He really does love hearing from our packagers and wants
 to make sure we're not being a "hostile upstream". As should be a given, we
 appreciate the work our packagers do to make sure we have broad distribution!
	# Dear Packager,

	If you are looking to make Docker available on your favorite software
	distribution, this document is for you. It summarizes the requirements for
	building and running the Docker client and the Docker daemon.

	## Getting Started

	We want to help you package Docker successfully. Before doing any packaging, a
	good first step is to introduce yourself on the [docker-dev mailing
	list](https://groups.google.com/d/forum/docker-dev), explain what you're trying
	to achieve, and tell us how we can help. Don't worry, we don't bite! There might
	even be someone already working on packaging for the same distro!

	You can also join the IRC channel - #docker and #docker-dev on Freenode are both
	active and friendly.

	We like to refer to Tianon ("@tianon" on GitHub and "tianon" on IRC) as our
	"Packagers Relations", since he's always working to make sure our packagers have
	a good, healthy upstream to work with (both in our communication and in our
	build scripts). If you're having any kind of trouble, feel free to ping him
	directly. He also likes to keep track of what distributions we have packagers
	for, so feel free to reach out to him even just to say "Hi!"

	## Package Name

	If possible, your package should be called "docker". If that name is already
	taken, a second choice is "docker-engine". Another possible choice is "docker.io".

	## Official Build vs Distro Build

	The Docker project maintains its own build and release toolchain. It is pretty
	neat and entirely based on Docker (surprise!). This toolchain is the canonical
	way to build Docker. We encourage you to give it a try, and if the circumstances
	allow you to use it, we recommend that you do.

	You might not be able to use the official build toolchain - usually because your
	distribution has a toolchain and packaging policy of its own. We get it! Your
	house, your rules. The rest of this document should give you the information you
	need to package Docker your way, without denaturing it in the process.

	## Build Dependencies

	To build Docker, you will need the following:

	* A recent version of Git and Mercurial
	* Go version 1.6 or later
	* A clean checkout of the source added to a valid [Go
	workspace](https://golang.org/doc/code.html#Workspaces) under the path
	src/github.com/docker/docker (unless you plan to use `AUTO_GOPATH`,
	explained in more detail below)

	To build the Docker daemon, you will additionally need:

	* An amd64/x86_64 machine running Linux
	* SQLite version 3.7.9 or later
	* libdevmapper version 1.02.68-cvs (2012-01-26) or later from lvm2 version
	2.02.89 or later
	* btrfs-progs version 3.16.1 or later (unless using an older version is
	absolutely necessary, in which case 3.8 is the minimum)
	* libseccomp version 2.2.1 or later (for build tag seccomp)

	Be sure to also check out Docker's Dockerfile for the most up-to-date list of
	these build-time dependencies.

	### Go Dependencies

	All Go dependencies are vendored under "./vendor". They are used by the official
	build, so the source of truth for the current version of each dependency is
	whatever is in "./vendor".

	To use the vendored dependencies, simply make sure the path to "./vendor" is
	included in `GOPATH` (or use `AUTO_GOPATH`, as explained below).

	If you would rather (or must, due to distro policy) package these dependencies
	yourself, take a look at "vendor.conf" for an easy-to-parse list of the
	exact version for each.

	NOTE: if you're not able to package the exact version (to the exact commit) of a
	given dependency, please get in touch so we can remediate! Who knows what
	discrepancies can be caused by even the slightest deviation. We promise to do
	our best to make everybody happy.

	## Stripping Binaries

	Please, please, please do not strip any compiled binaries. This is really
	important.

	In our own testing, stripping the resulting binaries sometimes results in a
	binary that appears to work, but more often causes random panics, segfaults, and
	other issues. Even if the binary appears to work, please don't strip.

	See the following quotes from Dave Cheney, which explain this position better
	from the upstream Golang perspective.

	### [go issue #5855, comment #3](https://code.google.com/p/go/issues/detail?id=5855#c3)

	> Super super important: Do not strip go binaries or archives. It isn't tested,
	> often breaks, and doesn't work.

	### [launchpad golang issue #1200255, comment #8](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/8)

	> To quote myself: "Please do not strip Go binaries, it is not supported, not
	> tested, is often broken, and doesn't do what you want"
	>
	> To unpack that a bit
	>
	> * not supported, as in, we don't support it, and recommend against it when
	> asked
	> * not tested, we don't test stripped binaries as part of the build CI process
	> * is often broken, stripping a go binary will produce anywhere from no, to
	> subtle, to outright execution failure, see above

	### [launchpad golang issue #1200255, comment #13](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/13)

	> To clarify my previous statements.
	>
	> * I do not disagree with the debian policy, it is there for a good reason
	> * Having said that, it stripping Go binaries doesn't work, and nobody is
	> looking at making it work, so there is that.
	>
	> Thanks for patching the build formula.

	## Building Docker

	Please use our build script ("./hack/make.sh") for all your compilation of
	Docker. If there's something you need that it isn't doing, or something it could
	be doing to make your life as a packager easier, please get in touch with Tianon
	and help us rectify the situation. Chances are good that other packagers have
	probably run into the same problems and a fix might already be in the works, but
	none of us will know for sure unless you harass Tianon about it. :)

	All the commands listed within this section should be run with the Docker source
	checkout as the current working directory.

	### `AUTO_GOPATH`

	If you'd rather not be bothered with the hassles that setting up `GOPATH`
	appropriately can be, and prefer to just get a "build that works", you should
	add something similar to this to whatever script or process you're using to
	build Docker:

	```bash
	export AUTO_GOPATH=1
	```

	This will cause the build scripts to set up a reasonable `GOPATH` that
	automatically and properly includes both docker/docker from the local
	directory, and the local "./vendor" directory as necessary.

	### `DOCKER_BUILDTAGS`

	If you're building a binary that may need to be used on platforms that include
	AppArmor, you will need to set `DOCKER_BUILDTAGS` as follows:
	```bash
	export DOCKER_BUILDTAGS='apparmor'
	```

	If you're building a binary that may need to be used on platforms that include
	SELinux, you will need to use the `selinux` build tag:
	```bash
	export DOCKER_BUILDTAGS='selinux'
	```

	If you're building a binary that may need to be used on platforms that include
	seccomp, you will need to use the `seccomp` build tag:
	```bash
	export DOCKER_BUILDTAGS='seccomp'
	```

	There are build tags for disabling graphdrivers as well. By default, support
	for all graphdrivers are built in.

	To disable btrfs:
	```bash
	export DOCKER_BUILDTAGS='exclude_graphdriver_btrfs'
	```

	To disable devicemapper:
	```bash
	export DOCKER_BUILDTAGS='exclude_graphdriver_devicemapper'
	```

	To disable aufs:
	```bash
	export DOCKER_BUILDTAGS='exclude_graphdriver_aufs'
	```

	NOTE: if you need to set more than one build tag, space separate them:
	```bash
	export DOCKER_BUILDTAGS='apparmor selinux exclude_graphdriver_aufs'
	```

	### Static Daemon

	If it is feasible within the constraints of your distribution, you should
	seriously consider packaging Docker as a single static binary. A good comparison
	is Busybox, which is often packaged statically as a feature to enable mass
	portability. Because of the unique way Docker operates, being similarly static
	is a "feature".

	To build a static Docker daemon binary, run the following command (first
	ensuring that all the necessary libraries are available in static form for
	linking - see the "Build Dependencies" section above, and the relevant lines
	within Docker's own Dockerfile that set up our official build environment):

	```bash
	./hack/make.sh binary
	```

	This will create a static binary under
	"./bundles/$VERSION/binary/docker-$VERSION", where "$VERSION" is the contents of
	the file "./VERSION". This binary is usually installed somewhere like
	"/usr/bin/docker".

	### Dynamic Daemon / Client-only Binary

	If you are only interested in a Docker client binary, you can build using:

	```bash
	./hack/make.sh binary-client
	```

	If you need to (due to distro policy, distro library availability, or for other
	reasons) create a dynamically compiled daemon binary, or if you are only
	interested in creating a client binary for Docker, use something similar to the
	following:

	```bash
	./hack/make.sh dynbinary-client
	```

	This will create "./bundles/$VERSION/dynbinary-client/docker-$VERSION", which for
	client-only builds is the important file to grab and install as appropriate.

	## System Dependencies

	### Runtime Dependencies

	To function properly, the Docker daemon needs the following software to be
	installed and available at runtime:

	* iptables version 1.4 or later
	* procps (or similar provider of a "ps" executable)
	* e2fsprogs version 1.4.12 or later (in use: mkfs.ext4, tune2fs)
	* xfsprogs (in use: mkfs.xfs)
	* XZ Utils version 4.9 or later
	* a [properly
	mounted](https://github.com/tianon/cgroupfs-mount/blob/master/cgroupfs-mount)
	cgroupfs hierarchy (having a single, all-encompassing "cgroup" mount point
	[is](https://github.com/docker/docker/issues/2683)
	[not](https://github.com/docker/docker/issues/3485)
	[sufficient](https://github.com/docker/docker/issues/4568))

	Additionally, the Docker client needs the following software to be installed and
	available at runtime:

	* Git version 1.7 or later

	### Kernel Requirements

	The Docker daemon has very specific kernel requirements. Most pre-packaged
	kernels already include the necessary options enabled. If you are building your
	own kernel, you will either need to discover the options necessary via trial and
	error, or check out the [Gentoo
	ebuild](https://github.com/tianon/docker-overlay/blob/master/app-emulation/docker/docker-9999.ebuild),
	in which a list is maintained (and if there are any issues or discrepancies in
	that list, please contact Tianon so they can be rectified).

	Note that in client mode, there are no specific kernel requirements, and that
	the client will even run on alternative platforms such as Mac OS X / Darwin.

	### Optional Dependencies

	Some of Docker's features are activated by using optional command-line flags or
	by having support for them in the kernel or userspace. A few examples include:

	* AUFS graph driver (requires AUFS patches/support enabled in the kernel, and at
	least the "auplink" utility from aufs-tools)
	* BTRFS graph driver (requires BTRFS support enabled in the kernel)
	* ZFS graph driver (requires userspace zfs-utils and a corresponding kernel module)
	* Libseccomp to allow running seccomp profiles with containers

	## Daemon Init Script

	Docker expects to run as a daemon at machine startup. Your package will need to
	include a script for your distro's process supervisor of choice. Be sure to
	check out the "contrib/init" folder in case a suitable init script already
	exists (and if one does not, contact Tianon about whether it might be
	appropriate for your distro's init script to live there too!).

	In general, Docker should be run as root, similar to the following:

	```bash
	dockerd
	```

	Generally, a `DOCKER_OPTS` variable of some kind is available for adding more
	flags (such as changing the graph driver to use BTRFS, switching the location of
	"/var/lib/docker", etc).

	## Communicate

	As a final note, please do feel free to reach out to Tianon at any time for
	pretty much anything. He really does love hearing from our packagers and wants
	to make sure we're not being a "hostile upstream". As should be a given, we
	appreciate the work our packagers do to make sure we have broad distribution!