Merge pull request #387 from dpw/build_in_container

Containerized weave build

site/building.md

@@ -3,35 +3,105 @@ title: Building Weave
 layout: default
 ---
 
-**NB** This is only necessary if you want to work on the weave code.
+You only need to build weave if you want to work on the weave codebase
+(or you just enjoy building software).
 
-## Building directly on Linux
+Apart from the `weave` shell script, weave is delivered as a set of
+container images.  There is no distribution-specific packaging, so in
+principle it shouldn't matter which Linux distribution you build
+under.  But naturally, Docker is a prerequisite (version 1.3.0 or
+later).  And it is difficult to build under Fedora because [Fedora
+does not include static
+libraries](http://fedoraproject.org/wiki/Packaging:Guidelines#Packaging_Static_Libraries).
+So we recommend building under Ubuntu.
 
-You can work on weave without using a VM if you are running the docker
-daemon outside a VM. (These instructions have only been tested on
-Ubuntu.)
+You can also build in a container under any system that supports
+Docker.  And you can run Ubuntu in a VM and build there.  These
+options are described below.
 
-To build weave you need `libpcap-dev` and `docker` (version 1.3.0 or
-later) installed. And `go` (and `git` and `hg` to fetch dependencies).
+## Building directly on Ubuntu
 
-The package name is `github.com/zettio/weave`, so assuming `$GOPATH`
-is set:
+The weave git repository should be cloned into
+`$GOPATH/src/github.com/zettio/weave`, in accordance with [the go
+workspace conventions](https://golang.org/doc/code.html#Workspaces):
 
 ```bash
-$ cd $GOPATH
 $ WEAVE=github.com/zettio/weave
-$ git clone https://$WEAVE src/$WEAVE
-$ cd src/$WEAVE
+$ git clone https://$WEAVE $GOPATH/src/$WEAVE
+$ cd $GOPATH/src/$WEAVE
 ```
 
-Then simply run
+Some prerequisites are needed to build weave.  First, install Docker
+if you haven't already, by following the instructions [on the Docker
+site](https://docs.docker.com/installation/ubuntulinux/).  Note that
+we recommend using the Docker-maintained `lxc-docker` package, rather
+than the `docker.io` package which contains a very old version.  Then
+install the other prerequisites for building with:
+
+```bash
+$ sudo apt-get install build-essential git golang mercurial libpcap-dev
+```
+
+Then to actually build, simply do:
 
 ```bash
 $ make
 ```
 
-This will build the weave router, produce a docker image
-`zettio/weave` and export that image to `/var/tmp/weave.tar`.
+This will build the weave components and package them into three
+Docker images (`zettio/weave`, `zettio/weavedns`, and
+`zettio/weavetools`).  These are then exported (as
+`weave.tar`, `weavends.tar` and `weavetools.tar`).
+
+## Building in a Docker container
+
+As a preliminary step, we create a container image based on Ubuntu
+that has all the prerequisites.  This avoids the need to download and
+install them for each build.  In the `weave` directory, do:
+
+```bash
+$ sudo docker build -t zettio/weave-build build
+```
+
+Next we run a container based on that image. That container requires
+access to the Docker daemon on the host, via
+`/var/run/docker.sock`. If you are building under a Fedora or RHEL
+Docker host (or another distribution that uses SELinux), and you have
+SELinux set to enforcing mode, it will block attempts to access
+`/var/run/docker.sock` inside the container.  See
+[dpw/selinux-dockersock](https://github.com/dpw/selinux-dockersock)
+for a way to work around this problem.
+
+To perform a build, run:
+
+```bash
+$ sudo docker run -v /var/run/docker.sock:/var/run/docker.sock zettio/weave-build https://github.com/zettio/weave.git
+```
+
+This will clone the weave git repository, then do the build.
+
+When the build completes, the resulting images are stored in docker on
+the host, as when building directly under Ubuntu.
+
+The container arguments are passed to `git clone`, so for example, you
+can build from a forked repository and a specific branch with:
+
+```bash
+$ sudo docker run -v /var/run/docker.sock:/var/run/docker.sock zettio/weave-build -b <branch name> <repo URI>
+```
+
+Alternatively, you might want to build from a weave source tree
+already present on the host.  You can do this by using the `-v` option
+to bind the bind your go workspace containing the weave repository to
+`/home/go` inside the container.  No container arguments should be
+passed in this case:
+
+```bash
+$ sudo docker run -v /var/run/docker.sock:/var/run/docker.sock -v <host gopath>:/home/go zettio/weave-build
+```
+
+This will leave the intermediate build artifacts on the host, so that
+you can modify the weave source code and rebuild quickly.
 
 ## Building using Vagrant
 
@@ -82,7 +152,7 @@ The docker daemon is also running in this VM, so you can then do
 
 ```bash
 vm$ sudo ./weave launch
-vm$ docker ps
+vm$ sudo docker ps
 ```
 
 and so on.