From a7f265223aec54a53c938f119275cb5fcebca4b6 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Tue, 4 Mar 2014 21:25:00 -0700 Subject: [PATCH 1/8] Update PACKAGERS.md with some text changes, including and especially moving "LXC" to a new "Optional Dependencies" section Docker-DCO-1.1-Signed-off-by: Andrew Page (github: tianon) --- hack/PACKAGERS.md | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/hack/PACKAGERS.md b/hack/PACKAGERS.md index b50306430b..2d2f434dc0 100644 --- a/hack/PACKAGERS.md +++ b/hack/PACKAGERS.md @@ -142,30 +142,46 @@ dependencies to be installed (see below). The test suite will also download a small test container, so you will need internet connectivity. -## Runtime dependencies +## Dependencies + +### Runtime To run properly, docker needs the following software to be installed at runtime: * iproute2 version 3.5 or later (build after 2012-05-21), 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 * XZ Utils 4.9 or later -## Kernel dependencies +### Kernel -Docker in daemon mode has specific kernel requirements. For details, see -http://docs.docker.io/en/latest/installation/kernel/ +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. Note that Docker also has a client mode, which can run on virtually any linux kernel (it even builds on OSX!). +### 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) + ## 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. +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! -Docker should be run as root, with the following arguments: +In general, Docker should be run as root, with the following arguments: ```bash docker -d From 9a677e6a68c9a07df8591d87ba82d77934600426 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Tue, 4 Mar 2014 21:40:12 -0700 Subject: [PATCH 2/8] Reflow PACKAGERS.md to 80 columns (where possible) and update some minor formatting Docker-DCO-1.1-Signed-off-by: Andrew Page (github: tianon) --- hack/PACKAGERS.md | 151 ++++++++++++++++++++++++++-------------------- 1 file changed, 86 insertions(+), 65 deletions(-) diff --git a/hack/PACKAGERS.md b/hack/PACKAGERS.md index 2d2f434dc0..b7ca557ae5 100644 --- a/hack/PACKAGERS.md +++ b/hack/PACKAGERS.md @@ -1,36 +1,42 @@ -Dear packager. +# 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. +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 +## 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! +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! -You can also join the IRC channel - #docker and #docker-dev on Freenode are both active and friendly. +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". +## Package Name -## Official build vs distro build +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). -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. +## Official Build vs Distro Build -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. +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. -## System build dependencies +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 To build docker, you will need the following system dependencies @@ -38,28 +44,35 @@ To build docker, you will need the following system dependencies * A recent version of git and mercurial * Go version 1.2 or later * 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.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*. +* 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*. -## Go 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 is whatever is in ./vendor. +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. +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. +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. +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. +Please, please, please do not strip any compiled binaries. This is really +important. See the following quotes from Dave Cheney, which explain this position better from the upstream Golang perspective. @@ -94,29 +107,33 @@ from the upstream Golang perspective. ## Building Docker -To build the docker binary, run the following command with the source checkout as the -working directory: +To build the docker binary, run the following command with the source checkout +as the working directory. ```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 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: +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, $BUILDFLAGS, $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. +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. -A good comparison is Busybox: all distros package it as a statically linked binary, because it just -makes sense. Docker is the same way. +A good comparison is Busybox: all distros package it as a statically linked +binary, because it just makes sense. Docker is the same way. If you *must* have a non-static Docker binary, please use: @@ -124,31 +141,34 @@ If you *must* have a non-static Docker binary, please use: ./hack/make.sh dynbinary ``` -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*. +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*. ## Testing Docker -Before releasing your binary, make sure to run the tests! Run the following command with the source -checkout as the working directory: +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 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. +The test suite will also download a small test container, so you will need +internet connectivity. -## Dependencies +## System Dependencies ### Runtime To run properly, docker needs the following software to be installed at runtime: -* iproute2 version 3.5 or later (build after 2012-05-21), and specifically the "ip" utility +* iproute2 version 3.5 or later (build after 2012-05-21), and specifically the + "ip" utility * iptables version 1.4 or later * Git version 1.7 or later * XZ Utils 4.9 or later @@ -162,8 +182,8 @@ 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. -Note that Docker also has a client mode, which can run on virtually any linux kernel (it even builds -on OSX!). +Note that Docker also has a client mode, which can run on virtually any Linux +kernel (it even builds on OSX!). ### Optional @@ -175,11 +195,12 @@ by having support for them in the kernel or userspace. A few examples include: least the "auplink" utility from aufs-tools) * BTRFS graph driver (requires BTRFS support enabled in the kernel) -## Init script +## 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! +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. In general, Docker should be run as root, with the following arguments: From d9ec3a034719ac933a791bdf064afe8afb63b1f9 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Tue, 4 Mar 2014 21:41:59 -0700 Subject: [PATCH 3/8] Mention in PACKAGERS.md that Tianon is available for packager needs Docker-DCO-1.1-Signed-off-by: Andrew Page (github: tianon) --- hack/PACKAGERS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/hack/PACKAGERS.md b/hack/PACKAGERS.md index b7ca557ae5..0228deb9e1 100644 --- a/hack/PACKAGERS.md +++ b/hack/PACKAGERS.md @@ -16,6 +16,11 @@ 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. ## Package Name From 615667b8831e49474ad7d255d62343c2427514ec Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Tue, 4 Mar 2014 22:51:34 -0700 Subject: [PATCH 4/8] Rewrite more loads of PACKAGERS.md to hopefully remove some outdated information, add some updated information and pointers, and generally make the tone of this document less condescending :) Docker-DCO-1.1-Signed-off-by: Andrew Page (github: tianon) --- hack/PACKAGERS.md | 205 +++++++++++++++++++++++++++++----------------- 1 file changed, 132 insertions(+), 73 deletions(-) diff --git a/hack/PACKAGERS.md b/hack/PACKAGERS.md index 0228deb9e1..46b32cd805 100644 --- a/hack/PACKAGERS.md +++ b/hack/PACKAGERS.md @@ -1,6 +1,6 @@ # Dear Packager, -If you are looking to make docker available on your favorite software +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. @@ -8,10 +8,9 @@ building and running the Docker client and the Docker daemon. 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! +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. @@ -20,30 +19,30 @@ 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. +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 "lxc-docker", but with the caveat that "LXC" is now an -optional dependency (as noted below). +optional dependency (as noted below). 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, 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. +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. -## System Build Dependencies +## Build Dependencies -To build docker, you will need the following system dependencies +To build Docker, you will need the following: * An amd64 machine * A recent version of git and mercurial @@ -53,21 +52,23 @@ To build docker, you will need the following system dependencies 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*. +* A clean checkout of the source added to a valid [Go + workspace](http://golang.org/doc/code.html#Workspaces) under the path + *src/github.com/dotcloud/docker* (unless you plan to use `AUTO_GOPATH`, + explained in more detail below). -## Go 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 is whatever is in -./vendor. +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. +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 package these dependencies yourself, take a look at -./hack/vendor.sh for an easy-to-parse list of the exact version for each. +If you would rather (or must, due to distro policy) 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 @@ -79,6 +80,10 @@ our best to make everybody happy. 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. @@ -112,85 +117,127 @@ from the upstream Golang perspective. ## Building Docker -To build the docker binary, run the following command with the source checkout -as the working directory. +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 dotcloud/docker from the local +directory, and the local "./vendor" directory as necessary. + +### 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*. +"./bundles/$VERSION/binary/docker-$VERSION", where "$VERSION" is the contents of +the file "./VERSION". This binary is usually installed somewhere like +"/usr/bin/docker". -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 +### Dynamic Daemon / Client-only Binary + +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: -* In *./hack/make.sh*: $LDFLAGS, $BUILDFLAGS, $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'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. - -A good comparison is Busybox: all distros package it as a statically linked -binary, because it just makes sense. Docker is the same way. - -If you *must* have a non-static Docker binary, please use: - ```bash ./hack/make.sh dynbinary ``` -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*. +This will create "./bundles/$VERSION/dynbinary/docker-$VERSION", which for +client-only builds is the important file to grab and install as appropriate. -## Testing Docker +For daemon builds, you will also need to grab and install +"./bundles/$VERSION/dynbinary/dockerinit-$VERSION", which is created from the +minimal set of Docker's codebase that _must_ be compiled statically (and is thus +a pure static binary). The acceptable locations Docker will search for this file +are as follows (in order): -Before releasing your binary, make sure to run the tests! Run the following -command with the source checkout as the working directory: +* as "dockerinit" in the same directory as the daemon binary (ie, if docker is + installed at "/usr/bin/docker", then "/usr/bin/dockerinit" will be the first + place this file is searched for) +* "/usr/libexec/docker/dockerinit" or "/usr/local/libexec/docker/dockerinit" + ([FHS 3.0 Draft](http://www.linuxbase.org/betaspecs/fhs/fhs.html#usrlibexec)) +* "/usr/lib/docker/dockerinit" or "/usr/local/lib/docker/dockerinit" ([FHS + 2.3](http://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html#USRLIBLIBRARIESFORPROGRAMMINGANDPA)) + +If (and please, only if) one of the paths above is insufficient due to distro +policy or similar issues, you may use the `DOCKER_INITPATH` environment variable +at compile-time as follows to set a different path for Docker to search: ```bash -./hack/make.sh test +export DOCKER_INITPATH=/usr/lib/docker.io/dockerinit ``` -The test suite includes both live integration tests and unit tests, so you will -need all runtime dependencies to be installed (see below). +If you find yourself needing this, please don't hesitate to reach out to Tianon +to see if it would be reasonable or helpful to add more paths to Docker's list, +especially if there's a relevant standard worth referencing (such as the FHS). -The test suite will also download a small test container, so you will need -internet connectivity. +Also, it goes without saying, but for the purposes of the daemon please consider +these two binaries ("docker" and "dockerinit") as if they were a single unit. +Mixing and matching can cause undesired consequences, and will fail to run +properly. ## System Dependencies -### Runtime +### Runtime Dependencies -To run properly, docker needs the following software to be installed at runtime: +To function properly, the Docker daemon needs the following software to be +installed and available at runtime: -* iproute2 version 3.5 or later (build after 2012-05-21), and specifically the - "ip" utility * iptables version 1.4 or later +* XZ Utils version 4.9 or later + +Additionally, the Docker client needs the following software to be installed and +available at runtime: + * Git version 1.7 or later -* XZ Utils 4.9 or later -### Kernel +### Kernel Requirements -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 +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. +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 Docker also has a client mode, which can run on virtually any Linux -kernel (it even builds on OSX!). +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 +### 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: @@ -198,17 +245,29 @@ 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) +* experimental BTRFS graph driver (requires BTRFS support enabled in the kernel) -## Init Script +## 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. +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, with the following arguments: +In general, Docker should be run as root, similar to the following: ```bash docker -d ``` + +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! From b69f63283088e1ac744aafeb08189cb593b30787 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Tue, 4 Mar 2014 22:52:39 -0700 Subject: [PATCH 5/8] Update package deps to remove LXC and move aufs-tools to be in "Recommends" instead of strict Depends Docker-DCO-1.1-Signed-off-by: Andrew Page (github: tianon) --- hack/make/ubuntu | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/hack/make/ubuntu b/hack/make/ubuntu index 23af0ff7e0..65f6b7e273 100644 --- a/hack/make/ubuntu +++ b/hack/make/ubuntu @@ -112,9 +112,8 @@ EOF --after-remove /tmp/postrm \ --architecture "$PACKAGE_ARCHITECTURE" \ --prefix / \ - --depends lxc \ - --depends aufs-tools \ --depends iptables \ + --deb-recommends aufs-tools \ --deb-recommends ca-certificates \ --deb-recommends xz-utils \ --description "$PACKAGE_DESCRIPTION" \ From 4293a1ceb476ce4a8621ac1500a3623328fb5b97 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Tue, 4 Mar 2014 22:54:58 -0700 Subject: [PATCH 6/8] Update the relevant docs section to match PACKAGERS.md Docker-DCO-1.1-Signed-off-by: Andrew Page (github: tianon) --- docs/sources/installation/binaries.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/sources/installation/binaries.rst b/docs/sources/installation/binaries.rst index 976e94e344..bfdfbe211f 100644 --- a/docs/sources/installation/binaries.rst +++ b/docs/sources/installation/binaries.rst @@ -26,10 +26,7 @@ Check runtime dependencies To run properly, docker needs the following software to be installed at runtime: -- iproute2 version 3.5 or later (build after 2012-05-21), 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 - XZ Utils 4.9 or later @@ -41,7 +38,7 @@ Docker in daemon mode has specific kernel requirements. For details, check your distribution in :ref:`installation_list`. Note that Docker also has a client mode, which can run on virtually -any linux kernel (it even builds on OSX!). +any Linux kernel (it even builds on OSX!). Get the docker binary: From 5317ad476d9e2c39cf6379fef4ec7f8ba0bcc23a Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Tue, 4 Mar 2014 22:59:46 -0700 Subject: [PATCH 7/8] Add "git" to our Ubuntu package "Recommends" (whoops, this should've been in here for a while now) Docker-DCO-1.1-Signed-off-by: Andrew Page (github: tianon) --- hack/make/ubuntu | 1 + 1 file changed, 1 insertion(+) diff --git a/hack/make/ubuntu b/hack/make/ubuntu index 65f6b7e273..602d4ac1ad 100644 --- a/hack/make/ubuntu +++ b/hack/make/ubuntu @@ -115,6 +115,7 @@ EOF --depends iptables \ --deb-recommends aufs-tools \ --deb-recommends ca-certificates \ + --deb-recommends git \ --deb-recommends xz-utils \ --description "$PACKAGE_DESCRIPTION" \ --maintainer "$PACKAGE_MAINTAINER" \ From c41e51ce3df05553b7a4ce6960df68973a4e17ee Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Wed, 5 Mar 2014 08:20:42 -0700 Subject: [PATCH 8/8] Add further clarification of where/when the build-time deps are applicable Docker-DCO-1.1-Signed-off-by: Andrew Page (github: tianon) --- hack/PACKAGERS.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/hack/PACKAGERS.md b/hack/PACKAGERS.md index 46b32cd805..8d9749b4f8 100644 --- a/hack/PACKAGERS.md +++ b/hack/PACKAGERS.md @@ -44,18 +44,24 @@ need to package Docker your way, without denaturing it in the process. To build Docker, you will need the following: -* An amd64 machine * A recent version of git and mercurial * Go version 1.2 or later +* A clean checkout of the source added to a valid [Go + workspace](http://golang.org/doc/code.html#Workspaces) under the path + *src/github.com/dotcloud/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.8 or later (including commit e5cb128 from 2013-01-07) for the necessary btrfs headers -* A clean checkout of the source added to a valid [Go - workspace](http://golang.org/doc/code.html#Workspaces) under the path - *src/github.com/dotcloud/docker* (unless you plan to use `AUTO_GOPATH`, - explained in more detail below). + +Be sure to also check out Docker's Dockerfile for the most up-to-date list of +these build-time dependencies. ### Go Dependencies