2014-03-05 04:40:12 +00:00
|
|
|
# Dear Packager,
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
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.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
## Getting Started
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
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/forum/?fromgroups#!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!
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
You can also join the IRC channel - #docker and #docker-dev on Freenode are both
|
|
|
|
active and friendly.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
## Package Name
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
If possible, your package should be called "docker". If that name is already
|
|
|
|
taken, a second choice is "lxc-docker", but with the caveat that "LXC" is now an
|
|
|
|
optional dependency (as noted below).
|
2013-09-10 18:30:14 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
## Official Build vs Distro Build
|
2013-09-10 18:30:14 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
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, and the only method supported by the development team. We
|
|
|
|
encourage you to give it a try, and if the circumstances allow you to use it, we
|
|
|
|
recommend that you do.
|
2013-09-10 18:30:14 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
## System Build Dependencies
|
2013-09-10 06:39:55 +00:00
|
|
|
|
|
|
|
To build docker, you will need the following system dependencies
|
|
|
|
|
|
|
|
* An amd64 machine
|
|
|
|
* A recent version of git and mercurial
|
2013-12-17 06:57:54 +00:00
|
|
|
* Go version 1.2 or later
|
2013-10-29 03:57:20 +00:00
|
|
|
* SQLite version 3.7.9 or later
|
2014-03-05 04:40:12 +00:00
|
|
|
* libdevmapper version 1.02.68-cvs (2012-01-26) or later from lvm2 version
|
|
|
|
2.02.89 or later
|
|
|
|
* btrfs-progs version 3.8 or later (including commit e5cb128 from 2013-01-07)
|
|
|
|
for the necessary btrfs headers
|
|
|
|
* A clean checkout of the source must be added to a valid Go
|
|
|
|
[workspace](http://golang.org/doc/code.html#Workspaces) under the path
|
|
|
|
*src/github.com/dotcloud/docker*.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
## Go Dependencies
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
All Go dependencies are vendored under ./vendor. They are used by the official
|
|
|
|
build, so the source of truth for the current version is whatever is in
|
|
|
|
./vendor.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
To use the vendored dependencies, simply make sure the path to ./vendor is
|
|
|
|
included in $GOPATH.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
If you would rather package these dependencies yourself, take a look at
|
|
|
|
./hack/vendor.sh for an easy-to-parse list of the exact version for each.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
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.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-02-03 05:40:58 +00:00
|
|
|
## Stripping Binaries
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
Please, please, please do not strip any compiled binaries. This is really
|
|
|
|
important.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-02-03 05:40:58 +00:00
|
|
|
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.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
|
|
|
## Building Docker
|
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
To build the docker binary, run the following command with the source checkout
|
|
|
|
as the working directory.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2013-10-18 05:36:28 +00:00
|
|
|
```bash
|
2013-09-10 06:39:55 +00:00
|
|
|
./hack/make.sh binary
|
|
|
|
```
|
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
This will create a static binary under
|
|
|
|
*./bundles/$VERSION/binary/docker-$VERSION*, where *$VERSION* is the contents of
|
|
|
|
the file *./VERSION*.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
You are encouraged to use ./hack/make.sh without modification. If you must
|
|
|
|
absolutely write your own script (are you really, really sure you need to?
|
|
|
|
make.sh is really not that complicated), then please take care the respect the
|
|
|
|
following:
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2013-10-18 05:36:28 +00:00
|
|
|
* In *./hack/make.sh*: $LDFLAGS, $BUILDFLAGS, $VERSION and $GITCOMMIT
|
2013-09-10 06:39:55 +00:00
|
|
|
* In *./hack/make/binary*: the exact build command to run
|
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
You may be tempted to tweak these settings. In particular, being a rigorous
|
|
|
|
maintainer, you may want to disable static linking. Please don't! Docker's
|
|
|
|
daemon *needs* to be statically linked to function properly. You would do the
|
|
|
|
users of your distro a disservice and "void the docker warranty" by changing the
|
|
|
|
flags.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
A good comparison is Busybox: all distros package it as a statically linked
|
|
|
|
binary, because it just makes sense. Docker is the same way.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2013-12-17 06:57:54 +00:00
|
|
|
If you *must* have a non-static Docker binary, please use:
|
2013-10-18 05:40:41 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
./hack/make.sh dynbinary
|
|
|
|
```
|
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
This will create *./bundles/$VERSION/dynbinary/docker-$VERSION* and
|
|
|
|
*./bundles/$VERSION/binary/dockerinit-$VERSION*. The first of these would
|
|
|
|
usually be installed at */usr/bin/docker*, while the second must be installed at
|
|
|
|
*/usr/libexec/docker/dockerinit*.
|
2013-10-18 05:40:41 +00:00
|
|
|
|
2013-09-10 06:39:55 +00:00
|
|
|
## Testing Docker
|
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
Before releasing your binary, make sure to run the tests! Run the following
|
|
|
|
command with the source checkout as the working directory:
|
2013-09-10 06:39:55 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
./hack/make.sh test
|
|
|
|
```
|
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
The test suite includes both live integration tests and unit tests, so you will
|
|
|
|
need all runtime dependencies to be installed (see below).
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
The test suite will also download a small test container, so you will need
|
|
|
|
internet connectivity.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
## System Dependencies
|
2014-03-05 04:25:00 +00:00
|
|
|
|
|
|
|
### Runtime
|
2013-09-10 06:39:55 +00:00
|
|
|
|
|
|
|
To run properly, docker needs the following software to be installed at runtime:
|
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
* iproute2 version 3.5 or later (build after 2012-05-21), and specifically the
|
|
|
|
"ip" utility
|
2013-09-10 06:39:55 +00:00
|
|
|
* iptables version 1.4 or later
|
2013-10-29 03:57:20 +00:00
|
|
|
* Git version 1.7 or later
|
2013-10-02 19:06:19 +00:00
|
|
|
* XZ Utils 4.9 or later
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:25:00 +00:00
|
|
|
### Kernel
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:25:00 +00:00
|
|
|
Docker in daemon mode has specific kernel requirements. Most pre-packaged
|
|
|
|
kernels 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.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
Note that Docker also has a client mode, which can run on virtually any Linux
|
|
|
|
kernel (it even builds on OSX!).
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:25:00 +00:00
|
|
|
### Optional
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
* LXC execution driver (requires version 0.8 or later of the LXC utility scripts)
|
|
|
|
* 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)
|
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
## Init Script
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:40:12 +00:00
|
|
|
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.
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2014-03-05 04:25:00 +00:00
|
|
|
In general, Docker should be run as root, with the following arguments:
|
2013-09-10 06:39:55 +00:00
|
|
|
|
2013-10-18 05:36:28 +00:00
|
|
|
```bash
|
2013-09-10 06:39:55 +00:00
|
|
|
docker -d
|
|
|
|
```
|