PACKAGERS.md: a guide to packaging Docker for your favorite distro

hack/PACKAGERS.md

@@ -0,0 +1,125 @@
+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
+docker.
+
+## Getting started
+
+We really want to help you package Docker successfully. Before anything, 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!
+
+You can also join the IRC channel - #docker and #docker-dev on Freenode are both active and friendly.
+
+## Package name
+
+If possible, your package should be called "docker". If that name is already taken, a second
+choice is "lxc-docker".
+
+## System build dependencies
+
+To build docker, you will need the following system dependencies
+
+* An amd64 machine
+* A recent version of git and mercurial
+* Go version 1.1.2
+* 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*. See 
+
+
+## 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 is whatever is in ./vendor.
+
+To use the vendored dependencies, simply make sure the path to ./vendor is included in $GOPATH.
+
+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.
+
+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.
+
+
+## Disabling CGO
+
+Make sure to disable CGO on your system, and then recompile the standard library on the build
+machine:
+
+```bash
+export CGO_ENABLED=0
+cd /tmp && echo 'package main' > t.go && go test -a -i -v
+```
+
+## Building Docker
+
+To build the docker binary, run the following command with the source checkout as the
+working directory:
+
+```
+./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*.
+
+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:
+
+* In *./hack/make.sh*: $LDFLAGS, $VERSION and $GITCOMMIT
+* In *./hack/make/binary*: the exact build command to run
+
+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 *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.
+
+A good comparison is Busybox: all distros package it as a statically linked binary, because it just
+makes sense. Docker is the same way.
+
+## Testing Docker
+
+Before releasing your binary, make sure to run the tests! Run the following command with the source
+checkout as the working directory:
+
+```bash
+./hack/make.sh test
+```
+
+The test suite includes both live integration tests and unit tests, so you will need all runtime
+dependencies to be installed (see below).
+
+The test suite will also download a small test container, so you will need internet connectivity.
+
+
+## Runtime dependencies
+
+To run properly, docker needs the following software to be installed at runtime:
+
+* GNU Tar version 1.26 or later
+* A recent build of iproute2 (2012-05-21 or later), and specifically the "ip" utility.
+* iptables version 1.4 or later
+* The lxc utility scripts (http://lxc.sourceforge.net) version 0.8 or later.
+* Git version 1.7 or later 
+
+## Kernel dependencies
+
+Docker in daemon mode has specific kernel requirements. For details, see
+http://docs.docker.io/en/latest/installation/kernel/
+
+Note that Docker also has a client mode, which can run on virtually any linux kernel (it even builds
+on OSX!).
+
+## 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.
+
+Docker should be run as root, with the following arguments:
+
+```
+docker -d
+```