mirror of
https://github.com/genuinetools/reg.git
synced 2024-08-20 13:50:23 -04:00
308 lines
12 KiB
Markdown
308 lines
12 KiB
Markdown
![]() |
# 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!
|