github.com/vincentwoo/docker@v0.7.3-0.20160116130405-82401a4b13c0/project/PACKAGERS.md (about) 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.4 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 * yubico-piv-tool version 1.1.0 or later (for experimental) 63 64 Be sure to also check out Docker's Dockerfile for the most up-to-date list of 65 these build-time dependencies. 66 67 ### Go Dependencies 68 69 All Go dependencies are vendored under "./vendor". They are used by the official 70 build, so the source of truth for the current version of each dependency is 71 whatever is in "./vendor". 72 73 To use the vendored dependencies, simply make sure the path to "./vendor" is 74 included in `GOPATH` (or use `AUTO_GOPATH`, as explained below). 75 76 If you would rather (or must, due to distro policy) package these dependencies 77 yourself, take a look at "./hack/vendor.sh" for an easy-to-parse list of the 78 exact version for each. 79 80 NOTE: if you're not able to package the exact version (to the exact commit) of a 81 given dependency, please get in touch so we can remediate! Who knows what 82 discrepancies can be caused by even the slightest deviation. We promise to do 83 our best to make everybody happy. 84 85 ## Stripping Binaries 86 87 Please, please, please do not strip any compiled binaries. This is really 88 important. 89 90 In our own testing, stripping the resulting binaries sometimes results in a 91 binary that appears to work, but more often causes random panics, segfaults, and 92 other issues. Even if the binary appears to work, please don't strip. 93 94 See the following quotes from Dave Cheney, which explain this position better 95 from the upstream Golang perspective. 96 97 ### [go issue #5855, comment #3](https://code.google.com/p/go/issues/detail?id=5855#c3) 98 99 > Super super important: Do not strip go binaries or archives. It isn't tested, 100 > often breaks, and doesn't work. 101 102 ### [launchpad golang issue #1200255, comment #8](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/8) 103 104 > To quote myself: "Please do not strip Go binaries, it is not supported, not 105 > tested, is often broken, and doesn't do what you want" 106 > 107 > To unpack that a bit 108 > 109 > * not supported, as in, we don't support it, and recommend against it when 110 > asked 111 > * not tested, we don't test stripped binaries as part of the build CI process 112 > * is often broken, stripping a go binary will produce anywhere from no, to 113 > subtle, to outright execution failure, see above 114 115 ### [launchpad golang issue #1200255, comment #13](https://bugs.launchpad.net/ubuntu/+source/golang/+bug/1200255/comments/13) 116 117 > To clarify my previous statements. 118 > 119 > * I do not disagree with the debian policy, it is there for a good reason 120 > * Having said that, it stripping Go binaries doesn't work, and nobody is 121 > looking at making it work, so there is that. 122 > 123 > Thanks for patching the build formula. 124 125 ## Building Docker 126 127 Please use our build script ("./hack/make.sh") for all your compilation of 128 Docker. If there's something you need that it isn't doing, or something it could 129 be doing to make your life as a packager easier, please get in touch with Tianon 130 and help us rectify the situation. Chances are good that other packagers have 131 probably run into the same problems and a fix might already be in the works, but 132 none of us will know for sure unless you harass Tianon about it. :) 133 134 All the commands listed within this section should be run with the Docker source 135 checkout as the current working directory. 136 137 ### `AUTO_GOPATH` 138 139 If you'd rather not be bothered with the hassles that setting up `GOPATH` 140 appropriately can be, and prefer to just get a "build that works", you should 141 add something similar to this to whatever script or process you're using to 142 build Docker: 143 144 ```bash 145 export AUTO_GOPATH=1 146 ``` 147 148 This will cause the build scripts to set up a reasonable `GOPATH` that 149 automatically and properly includes both docker/docker from the local 150 directory, and the local "./vendor" directory as necessary. 151 152 ### `DOCKER_BUILDTAGS` 153 154 If you're building a binary that may need to be used on platforms that include 155 AppArmor, you will need to set `DOCKER_BUILDTAGS` as follows: 156 ```bash 157 export DOCKER_BUILDTAGS='apparmor' 158 ``` 159 160 If you're building a binary that may need to be used on platforms that include 161 SELinux, you will need to use the `selinux` build tag: 162 ```bash 163 export DOCKER_BUILDTAGS='selinux' 164 ``` 165 166 There are build tags for disabling graphdrivers as well. By default, support 167 for all graphdrivers are built in. 168 169 To disable btrfs: 170 ```bash 171 export DOCKER_BUILDTAGS='exclude_graphdriver_btrfs' 172 ``` 173 174 To disable devicemapper: 175 ```bash 176 export DOCKER_BUILDTAGS='exclude_graphdriver_devicemapper' 177 ``` 178 179 To disable aufs: 180 ```bash 181 export DOCKER_BUILDTAGS='exclude_graphdriver_aufs' 182 ``` 183 184 NOTE: if you need to set more than one build tag, space separate them: 185 ```bash 186 export DOCKER_BUILDTAGS='apparmor selinux exclude_graphdriver_aufs' 187 ``` 188 189 ### Static Daemon 190 191 If it is feasible within the constraints of your distribution, you should 192 seriously consider packaging Docker as a single static binary. A good comparison 193 is Busybox, which is often packaged statically as a feature to enable mass 194 portability. Because of the unique way Docker operates, being similarly static 195 is a "feature". 196 197 To build a static Docker daemon binary, run the following command (first 198 ensuring that all the necessary libraries are available in static form for 199 linking - see the "Build Dependencies" section above, and the relevant lines 200 within Docker's own Dockerfile that set up our official build environment): 201 202 ```bash 203 ./hack/make.sh binary 204 ``` 205 206 This will create a static binary under 207 "./bundles/$VERSION/binary/docker-$VERSION", where "$VERSION" is the contents of 208 the file "./VERSION". This binary is usually installed somewhere like 209 "/usr/bin/docker". 210 211 ### Dynamic Daemon / Client-only Binary 212 213 If you are only interested in a Docker client binary, set `DOCKER_CLIENTONLY` to a non-empty value using something similar to the following: (which will prevent the extra step of compiling dockerinit) 214 215 ```bash 216 export DOCKER_CLIENTONLY=1 217 ``` 218 219 If you need to (due to distro policy, distro library availability, or for other 220 reasons) create a dynamically compiled daemon binary, or if you are only 221 interested in creating a client binary for Docker, use something similar to the 222 following: 223 224 ```bash 225 ./hack/make.sh dynbinary 226 ``` 227 228 This will create "./bundles/$VERSION/dynbinary/docker-$VERSION", which for 229 client-only builds is the important file to grab and install as appropriate. 230 231 For daemon builds, you will also need to grab and install 232 "./bundles/$VERSION/dynbinary/dockerinit-$VERSION", which is created from the 233 minimal set of Docker's codebase that _must_ be compiled statically (and is thus 234 a pure static binary). The acceptable locations Docker will search for this file 235 are as follows (in order): 236 237 * as "dockerinit" in the same directory as the daemon binary (ie, if docker is 238 installed at "/usr/bin/docker", then "/usr/bin/dockerinit" will be the first 239 place this file is searched for) 240 * "/usr/libexec/docker/dockerinit" or "/usr/local/libexec/docker/dockerinit" 241 ([FHS 3.0 Draft](https://www.linuxbase.org/betaspecs/fhs/fhs.html#usrlibexec)) 242 * "/usr/lib/docker/dockerinit" or "/usr/local/lib/docker/dockerinit" ([FHS 243 2.3](https://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html#USRLIBLIBRARIESFORPROGRAMMINGANDPA)) 244 245 If (and please, only if) one of the paths above is insufficient due to distro 246 policy or similar issues, you may use the `DOCKER_INITPATH` environment variable 247 at compile-time as follows to set a different path for Docker to search: 248 249 ```bash 250 export DOCKER_INITPATH=/usr/lib/docker.io/dockerinit 251 ``` 252 253 If you find yourself needing this, please don't hesitate to reach out to Tianon 254 to see if it would be reasonable or helpful to add more paths to Docker's list, 255 especially if there's a relevant standard worth referencing (such as the FHS). 256 257 Also, it goes without saying, but for the purposes of the daemon please consider 258 these two binaries ("docker" and "dockerinit") as if they were a single unit. 259 Mixing and matching can cause undesired consequences, and will fail to run 260 properly. 261 262 ## System Dependencies 263 264 ### Runtime Dependencies 265 266 To function properly, the Docker daemon needs the following software to be 267 installed and available at runtime: 268 269 * iptables version 1.4 or later 270 * procps (or similar provider of a "ps" executable) 271 * e2fsprogs version 1.4.12 or later (in use: mkfs.ext4, tune2fs) 272 * xfsprogs (in use: mkfs.xfs) 273 * XZ Utils version 4.9 or later 274 * a [properly 275 mounted](https://github.com/tianon/cgroupfs-mount/blob/master/cgroupfs-mount) 276 cgroupfs hierarchy (having a single, all-encompassing "cgroup" mount point 277 [is](https://github.com/docker/docker/issues/2683) 278 [not](https://github.com/docker/docker/issues/3485) 279 [sufficient](https://github.com/docker/docker/issues/4568)) 280 281 Additionally, the Docker client needs the following software to be installed and 282 available at runtime: 283 284 * Git version 1.7 or later 285 286 ### Kernel Requirements 287 288 The Docker daemon has very specific kernel requirements. Most pre-packaged 289 kernels already include the necessary options enabled. If you are building your 290 own kernel, you will either need to discover the options necessary via trial and 291 error, or check out the [Gentoo 292 ebuild](https://github.com/tianon/docker-overlay/blob/master/app-emulation/docker/docker-9999.ebuild), 293 in which a list is maintained (and if there are any issues or discrepancies in 294 that list, please contact Tianon so they can be rectified). 295 296 Note that in client mode, there are no specific kernel requirements, and that 297 the client will even run on alternative platforms such as Mac OS X / Darwin. 298 299 ### Optional Dependencies 300 301 Some of Docker's features are activated by using optional command-line flags or 302 by having support for them in the kernel or userspace. A few examples include: 303 304 * AUFS graph driver (requires AUFS patches/support enabled in the kernel, and at 305 least the "auplink" utility from aufs-tools) 306 * BTRFS graph driver (requires BTRFS support enabled in the kernel) 307 * ZFS graph driver (requires userspace zfs-utils and a corresponding kernel module) 308 * Libseccomp to allow running seccomp profiles with containers 309 310 ## Daemon Init Script 311 312 Docker expects to run as a daemon at machine startup. Your package will need to 313 include a script for your distro's process supervisor of choice. Be sure to 314 check out the "contrib/init" folder in case a suitable init script already 315 exists (and if one does not, contact Tianon about whether it might be 316 appropriate for your distro's init script to live there too!). 317 318 In general, Docker should be run as root, similar to the following: 319 320 ```bash 321 docker daemon 322 ``` 323 324 Generally, a `DOCKER_OPTS` variable of some kind is available for adding more 325 flags (such as changing the graph driver to use BTRFS, switching the location of 326 "/var/lib/docker", etc). 327 328 ## Communicate 329 330 As a final note, please do feel free to reach out to Tianon at any time for 331 pretty much anything. He really does love hearing from our packagers and wants 332 to make sure we're not being a "hostile upstream". As should be a given, we 333 appreciate the work our packagers do to make sure we have broad distribution!