project/PACKAGERS.md

   1 # Dear Packager,
   2
   3 If you are looking to make Docker available on your favorite software
   4 distribution, this document is for you. It summarizes the requirements for
   5 building and running the Docker client and the Docker daemon.
   6
   7 ## Getting Started
   8
   9 We want to help you package Docker successfully. Before doing any packaging, a
  10 good first step is to introduce yourself on the [docker-dev mailing
  11 list](https://groups.google.com/d/forum/docker-dev), explain what you're trying
  12 to achieve, and tell us how we can help. Don't worry, we don't bite! There might
  13 even be someone already working on packaging for the same distro!
  14
  15 You can also join the IRC channel - #docker and #docker-dev on Freenode are both
  16 active and friendly.
  17
  18 We like to refer to Tianon ("@tianon" on GitHub and "tianon" on IRC) as our
  19 "Packagers Relations", since he's always working to make sure our packagers have
  20 a good, healthy upstream to work with (both in our communication and in our
  21 build scripts). If you're having any kind of trouble, feel free to ping him
  22 directly. He also likes to keep track of what distributions we have packagers
  23 for, so feel free to reach out to him even just to say "Hi!"
  24
  25 ## Package Name
  26
  27 If possible, your package should be called "docker". If that name is already
  28 taken, a second choice is "docker-engine". Another possible choice is "docker.io".
  29
  30 ## Official Build vs Distro Build
  31
  32 The Docker project maintains its own build and release toolchain. It is pretty
  33 neat and entirely based on Docker (surprise!). This toolchain is the canonical
  34 way to build Docker. We encourage you to give it a try, and if the circumstances
  35 allow you to use it, we recommend that you do.
  36
  37 You might not be able to use the official build toolchain - usually because your
  38 distribution has a toolchain and packaging policy of its own. We get it! Your
  39 house, your rules. The rest of this document should give you the information you
  40 need to package Docker your way, without denaturing it in the process.
  41
  42 ## Build Dependencies
  43
  44 To build Docker, you will need the following:
  45
  46 * A recent version of Git and Mercurial
  47 * Go version 1.6 or later
  48 * A clean checkout of the source added to a valid [Go
  49   workspace](https://golang.org/doc/code.html#Workspaces) under the path
  50   *src/github.com/docker/docker* (unless you plan to use `AUTO_GOPATH`,
  51   explained in more detail below)
  52
  53 To build the Docker daemon, you will additionally need:
  54
  55 * An amd64/x86_64 machine running Linux
  56 * SQLite version 3.7.9 or later
  57 * libdevmapper version 1.02.68-cvs (2012-01-26) or later from lvm2 version
  58   2.02.89 or later
  59 * btrfs-progs version 3.16.1 or later (unless using an older version is
  60   absolutely necessary, in which case 3.8 is the minimum)
  61 * libseccomp version 2.2.1 or later (for build tag seccomp)
  62
  63 Be sure to also check out Docker's Dockerfile for the most up-to-date list of
  64 these build-time dependencies.
  65
  66 ### Go Dependencies
  67
  68 All Go dependencies are vendored under "./vendor". They are used by the official
  69 build, so the source of truth for the current version of each dependency is
  70 whatever is in "./vendor".
  71
  72 To use the vendored dependencies, simply make sure the path to "./vendor" is
  73 included in `GOPATH` (or use `AUTO_GOPATH`, as explained below).
  74
  75 If you would rather (or must, due to distro policy) package these dependencies
  76 yourself, take a look at "vendor.conf" for an easy-to-parse list of the
  77 exact version for each.
  78
  79 NOTE: if you're not able to package the exact version (to the exact commit) of a
  80 given dependency, please get in touch so we can remediate! Who knows what
  81 discrepancies can be caused by even the slightest deviation. We promise to do
  82 our best to make everybody happy.
  83
  84 ## Stripping Binaries
  85
  86 Please, please, please do not strip any compiled binaries. This is really
  87 important.
  88
  89 In our own testing, stripping the resulting binaries sometimes results in a
  90 binary that appears to work, but more often causes random panics, segfaults, and
  91 other issues. Even if the binary appears to work, please don't strip.
  92
  93 See the following quotes from Dave Cheney, which explain this position better
  94 from the upstream Golang perspective.
  95
  96 ### [go issue #5855, comment #3](https://code.google.com/p/go/issues/detail?id=5855#c3)
  97
  98 > Super super important: Do not strip go binaries or archives. It isn't tested,
  99 > often breaks, and doesn't work.
 100
 101 ### [launchpad golang issue #1200255, comment #8](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/8)
 102
 103 > To quote myself: "Please do not strip Go binaries, it is not supported, not
 104 > tested, is often broken, and doesn't do what you want"
 105 >
 106 > To unpack that a bit
 107 >
 108 > * not supported, as in, we don't support it, and recommend against it when
 109 >   asked
 110 > * not tested, we don't test stripped binaries as part of the build CI process
 111 > * is often broken, stripping a go binary will produce anywhere from no, to
 112 >   subtle, to outright execution failure, see above
 113
 114 ### [launchpad golang issue #1200255, comment #13](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/13)
 115
 116 > To clarify my previous statements.
 117 >
 118 > * I do not disagree with the debian policy, it is there for a good reason
 119 > * Having said that, it stripping Go binaries doesn't work, and nobody is
 120 >   looking at making it work, so there is that.
 121 >
 122 > Thanks for patching the build formula.
 123
 124 ## Building Docker
 125
 126 Please use our build script ("./hack/make.sh") for all your compilation of
 127 Docker. If there's something you need that it isn't doing, or something it could
 128 be doing to make your life as a packager easier, please get in touch with Tianon
 129 and help us rectify the situation. Chances are good that other packagers have
 130 probably run into the same problems and a fix might already be in the works, but
 131 none of us will know for sure unless you harass Tianon about it. :)
 132
 133 All the commands listed within this section should be run with the Docker source
 134 checkout as the current working directory.
 135
 136 ### `AUTO_GOPATH`
 137
 138 If you'd rather not be bothered with the hassles that setting up `GOPATH`
 139 appropriately can be, and prefer to just get a "build that works", you should
 140 add something similar to this to whatever script or process you're using to
 141 build Docker:
 142
 143 ```bash
 144 export AUTO_GOPATH=1
 145 ```
 146
 147 This will cause the build scripts to set up a reasonable `GOPATH` that
 148 automatically and properly includes both docker/docker from the local
 149 directory, and the local "./vendor" directory as necessary.
 150
 151 ### `DOCKER_BUILDTAGS`
 152
 153 If you're building a binary that may need to be used on platforms that include
 154 AppArmor, you will need to set `DOCKER_BUILDTAGS` as follows:
 155 ```bash
 156 export DOCKER_BUILDTAGS='apparmor'
 157 ```
 158
 159 If you're building a binary that may need to be used on platforms that include
 160 SELinux, you will need to use the `selinux` build tag:
 161 ```bash
 162 export DOCKER_BUILDTAGS='selinux'
 163 ```
 164
 165 If you're building a binary that may need to be used on platforms that include
 166 seccomp, you will need to use the `seccomp` build tag:
 167 ```bash
 168 export DOCKER_BUILDTAGS='seccomp'
 169 ```
 170
 171 There are build tags for disabling graphdrivers as well. By default, support
 172 for all graphdrivers are built in.
 173
 174 To disable btrfs:
 175 ```bash
 176 export DOCKER_BUILDTAGS='exclude_graphdriver_btrfs'
 177 ```
 178
 179 To disable devicemapper:
 180 ```bash
 181 export DOCKER_BUILDTAGS='exclude_graphdriver_devicemapper'
 182 ```
 183
 184 To disable aufs:
 185 ```bash
 186 export DOCKER_BUILDTAGS='exclude_graphdriver_aufs'
 187 ```
 188
 189 NOTE: if you need to set more than one build tag, space separate them:
 190 ```bash
 191 export DOCKER_BUILDTAGS='apparmor selinux exclude_graphdriver_aufs'
 192 ```
 193
 194 ### Static Daemon
 195
 196 If it is feasible within the constraints of your distribution, you should
 197 seriously consider packaging Docker as a single static binary. A good comparison
 198 is Busybox, which is often packaged statically as a feature to enable mass
 199 portability. Because of the unique way Docker operates, being similarly static
 200 is a "feature".
 201
 202 To build a static Docker daemon binary, run the following command (first
 203 ensuring that all the necessary libraries are available in static form for
 204 linking - see the "Build Dependencies" section above, and the relevant lines
 205 within Docker's own Dockerfile that set up our official build environment):
 206
 207 ```bash
 208 ./hack/make.sh binary
 209 ```
 210
 211 This will create a static binary under
 212 "./bundles/$VERSION/binary/docker-$VERSION", where "$VERSION" is the contents of
 213 the file "./VERSION". This binary is usually installed somewhere like
 214 "/usr/bin/docker".
 215
 216 ### Dynamic Daemon / Client-only Binary
 217
 218 If you are only interested in a Docker client binary, you can build using:
 219
 220 ```bash
 221 ./hack/make.sh binary-client
 222 ```
 223
 224 If you need to (due to distro policy, distro library availability, or for other
 225 reasons) create a dynamically compiled daemon binary, or if you are only
 226 interested in creating a client binary for Docker, use something similar to the
 227 following:
 228
 229 ```bash
 230 ./hack/make.sh dynbinary-client
 231 ```
 232
 233 This will create "./bundles/$VERSION/dynbinary-client/docker-$VERSION", which for
 234 client-only builds is the important file to grab and install as appropriate.
 235
 236 ## System Dependencies
 237
 238 ### Runtime Dependencies
 239
 240 To function properly, the Docker daemon needs the following software to be
 241 installed and available at runtime:
 242
 243 * iptables version 1.4 or later
 244 * procps (or similar provider of a "ps" executable)
 245 * e2fsprogs version 1.4.12 or later (in use: mkfs.ext4, tune2fs)
 246 * xfsprogs (in use: mkfs.xfs)
 247 * XZ Utils version 4.9 or later
 248 * a [properly
 249   mounted](https://github.com/tianon/cgroupfs-mount/blob/master/cgroupfs-mount)
 250   cgroupfs hierarchy (having a single, all-encompassing "cgroup" mount point
 251   [is](https://github.com/docker/docker/issues/2683)
 252   [not](https://github.com/docker/docker/issues/3485)
 253   [sufficient](https://github.com/docker/docker/issues/4568))
 254
 255 Additionally, the Docker client needs the following software to be installed and
 256 available at runtime:
 257
 258 * Git version 1.7 or later
 259
 260 ### Kernel Requirements
 261
 262 The Docker daemon has very specific kernel requirements. Most pre-packaged
 263 kernels already include the necessary options enabled. If you are building your
 264 own kernel, you will either need to discover the options necessary via trial and
 265 error, or check out the [Gentoo
 266 ebuild](https://github.com/tianon/docker-overlay/blob/master/app-emulation/docker/docker-9999.ebuild),
 267 in which a list is maintained (and if there are any issues or discrepancies in
 268 that list, please contact Tianon so they can be rectified).
 269
 270 Note that in client mode, there are no specific kernel requirements, and that
 271 the client will even run on alternative platforms such as Mac OS X / Darwin.
 272
 273 ### Optional Dependencies
 274
 275 Some of Docker's features are activated by using optional command-line flags or
 276 by having support for them in the kernel or userspace. A few examples include:
 277
 278 * AUFS graph driver (requires AUFS patches/support enabled in the kernel, and at
 279   least the "auplink" utility from aufs-tools)
 280 * BTRFS graph driver (requires BTRFS support enabled in the kernel)
 281 * ZFS graph driver (requires userspace zfs-utils and a corresponding kernel module)
 282 * Libseccomp to allow running seccomp profiles with containers
 283
 284 ## Daemon Init Script
 285
 286 Docker expects to run as a daemon at machine startup. Your package will need to
 287 include a script for your distro's process supervisor of choice. Be sure to
 288 check out the "contrib/init" folder in case a suitable init script already
 289 exists (and if one does not, contact Tianon about whether it might be
 290 appropriate for your distro's init script to live there too!).
 291
 292 In general, Docker should be run as root, similar to the following:
 293
 294 ```bash
 295 dockerd
 296 ```
 297
 298 Generally, a `DOCKER_OPTS` variable of some kind is available for adding more
 299 flags (such as changing the graph driver to use BTRFS, switching the location of
 300 "/var/lib/docker", etc).
 301
 302 ## Communicate
 303
 304 As a final note, please do feel free to reach out to Tianon at any time for
 305 pretty much anything. He really does love hearing from our packagers and wants
 306 to make sure we're not being a "hostile upstream". As should be a given, we
 307 appreciate the work our packagers do to make sure we have broad distribution!