github.com/demonoid81/moby@v0.0.0-20200517203328-62dd8e17c460/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.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/demonoid81/moby* (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 ### LCOW (Linux Containers On Windows) 195 196 LCOW is an experimental feature on Windows, and requires the daemon to run with 197 experimental features enabled. Use the `no_lcow` build tag to disable the LCOW 198 feature at compile time, 199 200 ### Static Daemon 201 202 If it is feasible within the constraints of your distribution, you should 203 seriously consider packaging Docker as a single static binary. A good comparison 204 is Busybox, which is often packaged statically as a feature to enable mass 205 portability. Because of the unique way Docker operates, being similarly static 206 is a "feature". 207 208 To build a static Docker daemon binary, run the following command (first 209 ensuring that all the necessary libraries are available in static form for 210 linking - see the "Build Dependencies" section above, and the relevant lines 211 within Docker's own Dockerfile that set up our official build environment): 212 213 ```bash 214 ./hack/make.sh binary 215 ``` 216 217 This will create a static binary under 218 "./bundles/$VERSION/binary/docker-$VERSION", where "$VERSION" is the contents of 219 the file "./VERSION". This binary is usually installed somewhere like 220 "/usr/bin/docker". 221 222 ### Dynamic Daemon / Client-only Binary 223 224 If you are only interested in a Docker client binary, you can build using: 225 226 ```bash 227 ./hack/make.sh binary-client 228 ``` 229 230 If you need to (due to distro policy, distro library availability, or for other 231 reasons) create a dynamically compiled daemon binary, or if you are only 232 interested in creating a client binary for Docker, use something similar to the 233 following: 234 235 ```bash 236 ./hack/make.sh dynbinary-client 237 ``` 238 239 This will create "./bundles/$VERSION/dynbinary-client/docker-$VERSION", which for 240 client-only builds is the important file to grab and install as appropriate. 241 242 ### Cross Compilation 243 244 Limited cross compilation is supported due to requiring cgo for critical 245 functionality (such as seccomp support). 246 247 To cross compile run `make cross`. You can specify the platforms to target by 248 setting the `DOCKER_CROSSPLATFORMS` environment variable to a list of platforms 249 in the format `<GOOS>/<GOARCH>`. Specify multiple platforms by using a space 250 in between each desired platform. 251 252 For setting arm variants, you can specify the `GOARM` value by append `/v<GOARM>` 253 to your `<GOOS>/arm`. Example: 254 255 ``` 256 make DOCKER_CROSSPLATFORMS=linux/arm/v7 cross 257 ``` 258 259 This will create a linux binary targeting arm 7. 260 261 See `hack/make/.binary` for supported cross compliation platforms. 262 263 ## System Dependencies 264 265 ### Runtime Dependencies 266 267 To function properly, the Docker daemon needs the following software to be 268 installed and available at runtime: 269 270 * iptables version 1.4 or later 271 * procps (or similar provider of a "ps" executable) 272 * e2fsprogs version 1.4.12 or later (in use: mkfs.ext4, tune2fs) 273 * xfsprogs (in use: mkfs.xfs) 274 * XZ Utils version 4.9 or later 275 * a [properly 276 mounted](https://github.com/tianon/cgroupfs-mount/blob/master/cgroupfs-mount) 277 cgroupfs hierarchy (having a single, all-encompassing "cgroup" mount point 278 [is](https://github.com/demonoid81/moby/issues/2683) 279 [not](https://github.com/demonoid81/moby/issues/3485) 280 [sufficient](https://github.com/demonoid81/moby/issues/4568)) 281 282 Additionally, the Docker client needs the following software to be installed and 283 available at runtime: 284 285 * Git version 1.7 or later 286 287 ### Kernel Requirements 288 289 The Docker daemon has very specific kernel requirements. Most pre-packaged 290 kernels already include the necessary options enabled. If you are building your 291 own kernel, you will either need to discover the options necessary via trial and 292 error, or check out the [Gentoo 293 ebuild](https://github.com/tianon/docker-overlay/blob/master/app-emulation/docker/docker-9999.ebuild), 294 in which a list is maintained (and if there are any issues or discrepancies in 295 that list, please contact Tianon so they can be rectified). 296 297 Note that in client mode, there are no specific kernel requirements, and that 298 the client will even run on alternative platforms such as Mac OS X / Darwin. 299 300 ### Optional Dependencies 301 302 Some of Docker's features are activated by using optional command-line flags or 303 by having support for them in the kernel or userspace. A few examples include: 304 305 * AUFS graph driver (requires AUFS patches/support enabled in the kernel, and at 306 least the "auplink" utility from aufs-tools) 307 * BTRFS graph driver (requires BTRFS support enabled in the kernel) 308 * ZFS graph driver (requires userspace zfs-utils and a corresponding kernel module) 309 * Libseccomp to allow running seccomp profiles with containers 310 311 ## Daemon Init Script 312 313 Docker expects to run as a daemon at machine startup. Your package will need to 314 include a script for your distro's process supervisor of choice. Be sure to 315 check out the "contrib/init" folder in case a suitable init script already 316 exists (and if one does not, contact Tianon about whether it might be 317 appropriate for your distro's init script to live there too!). 318 319 In general, Docker should be run as root, similar to the following: 320 321 ```bash 322 dockerd 323 ``` 324 325 Generally, a `DOCKER_OPTS` variable of some kind is available for adding more 326 flags (such as changing the graph driver to use BTRFS, switching the location of 327 "/var/lib/docker", etc). 328 329 ## Communicate 330 331 As a final note, please do feel free to reach out to Tianon at any time for 332 pretty much anything. He really does love hearing from our packagers and wants 333 to make sure we're not being a "hostile upstream". As should be a given, we 334 appreciate the work our packagers do to make sure we have broad distribution!