github.com/akerouanton/docker@v1.11.0-rc3/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 (Go version 1.5 or later required for hardware signing 48 support in Docker Content Trust) 49 * A clean checkout of the source added to a valid [Go 50 workspace](https://golang.org/doc/code.html#Workspaces) under the path 51 *src/github.com/docker/docker* (unless you plan to use `AUTO_GOPATH`, 52 explained in more detail below) 53 54 To build the Docker daemon, you will additionally need: 55 56 * An amd64/x86_64 machine running Linux 57 * SQLite version 3.7.9 or later 58 * libdevmapper version 1.02.68-cvs (2012-01-26) or later from lvm2 version 59 2.02.89 or later 60 * btrfs-progs version 3.16.1 or later (unless using an older version is 61 absolutely necessary, in which case 3.8 is the minimum) 62 * libseccomp version 2.2.1 or later (for build tag seccomp) 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 If you're building a binary that may need to be used on platforms that include 167 seccomp, you will need to use the `seccomp` build tag: 168 ```bash 169 export DOCKER_BUILDTAGS='seccomp' 170 ``` 171 172 There are build tags for disabling graphdrivers as well. By default, support 173 for all graphdrivers are built in. 174 175 To disable btrfs: 176 ```bash 177 export DOCKER_BUILDTAGS='exclude_graphdriver_btrfs' 178 ``` 179 180 To disable devicemapper: 181 ```bash 182 export DOCKER_BUILDTAGS='exclude_graphdriver_devicemapper' 183 ``` 184 185 To disable aufs: 186 ```bash 187 export DOCKER_BUILDTAGS='exclude_graphdriver_aufs' 188 ``` 189 190 NOTE: if you need to set more than one build tag, space separate them: 191 ```bash 192 export DOCKER_BUILDTAGS='apparmor selinux exclude_graphdriver_aufs' 193 ``` 194 195 ### Static Daemon 196 197 If it is feasible within the constraints of your distribution, you should 198 seriously consider packaging Docker as a single static binary. A good comparison 199 is Busybox, which is often packaged statically as a feature to enable mass 200 portability. Because of the unique way Docker operates, being similarly static 201 is a "feature". 202 203 To build a static Docker daemon binary, run the following command (first 204 ensuring that all the necessary libraries are available in static form for 205 linking - see the "Build Dependencies" section above, and the relevant lines 206 within Docker's own Dockerfile that set up our official build environment): 207 208 ```bash 209 ./hack/make.sh binary 210 ``` 211 212 This will create a static binary under 213 "./bundles/$VERSION/binary/docker-$VERSION", where "$VERSION" is the contents of 214 the file "./VERSION". This binary is usually installed somewhere like 215 "/usr/bin/docker". 216 217 ### Dynamic Daemon / Client-only Binary 218 219 If you are only interested in a Docker client binary, set `DOCKER_CLIENTONLY` to a non-empty value using something similar to the following: 220 221 ```bash 222 export DOCKER_CLIENTONLY=1 223 ``` 224 225 If you need to (due to distro policy, distro library availability, or for other 226 reasons) create a dynamically compiled daemon binary, or if you are only 227 interested in creating a client binary for Docker, use something similar to the 228 following: 229 230 ```bash 231 ./hack/make.sh dynbinary 232 ``` 233 234 This will create "./bundles/$VERSION/dynbinary/docker-$VERSION", which for 235 client-only builds is the important file to grab and install as appropriate. 236 237 ## System Dependencies 238 239 ### Runtime Dependencies 240 241 To function properly, the Docker daemon needs the following software to be 242 installed and available at runtime: 243 244 * iptables version 1.4 or later 245 * procps (or similar provider of a "ps" executable) 246 * e2fsprogs version 1.4.12 or later (in use: mkfs.ext4, tune2fs) 247 * xfsprogs (in use: mkfs.xfs) 248 * XZ Utils version 4.9 or later 249 * a [properly 250 mounted](https://github.com/tianon/cgroupfs-mount/blob/master/cgroupfs-mount) 251 cgroupfs hierarchy (having a single, all-encompassing "cgroup" mount point 252 [is](https://github.com/docker/docker/issues/2683) 253 [not](https://github.com/docker/docker/issues/3485) 254 [sufficient](https://github.com/docker/docker/issues/4568)) 255 256 Additionally, the Docker client needs the following software to be installed and 257 available at runtime: 258 259 * Git version 1.7 or later 260 261 ### Kernel Requirements 262 263 The Docker daemon has very specific kernel requirements. Most pre-packaged 264 kernels already include the necessary options enabled. If you are building your 265 own kernel, you will either need to discover the options necessary via trial and 266 error, or check out the [Gentoo 267 ebuild](https://github.com/tianon/docker-overlay/blob/master/app-emulation/docker/docker-9999.ebuild), 268 in which a list is maintained (and if there are any issues or discrepancies in 269 that list, please contact Tianon so they can be rectified). 270 271 Note that in client mode, there are no specific kernel requirements, and that 272 the client will even run on alternative platforms such as Mac OS X / Darwin. 273 274 ### Optional Dependencies 275 276 Some of Docker's features are activated by using optional command-line flags or 277 by having support for them in the kernel or userspace. A few examples include: 278 279 * AUFS graph driver (requires AUFS patches/support enabled in the kernel, and at 280 least the "auplink" utility from aufs-tools) 281 * BTRFS graph driver (requires BTRFS support enabled in the kernel) 282 * ZFS graph driver (requires userspace zfs-utils and a corresponding kernel module) 283 * Libseccomp to allow running seccomp profiles with containers 284 285 ## Daemon Init Script 286 287 Docker expects to run as a daemon at machine startup. Your package will need to 288 include a script for your distro's process supervisor of choice. Be sure to 289 check out the "contrib/init" folder in case a suitable init script already 290 exists (and if one does not, contact Tianon about whether it might be 291 appropriate for your distro's init script to live there too!). 292 293 In general, Docker should be run as root, similar to the following: 294 295 ```bash 296 docker daemon 297 ``` 298 299 Generally, a `DOCKER_OPTS` variable of some kind is available for adding more 300 flags (such as changing the graph driver to use BTRFS, switching the location of 301 "/var/lib/docker", etc). 302 303 ## Communicate 304 305 As a final note, please do feel free to reach out to Tianon at any time for 306 pretty much anything. He really does love hearing from our packagers and wants 307 to make sure we're not being a "hostile upstream". As should be a given, we 308 appreciate the work our packagers do to make sure we have broad distribution!