Bump version to v0.6.7

Refactor State to be 100% thread safe

.gitignore

@@ -18,3 +18,4 @@ bundles/
 .hg/
 .git/
 vendor/pkg/
+pyenv

AUTHORS

@@ -44,6 +44,7 @@ Daniel Nordberg <dnordberg@gmail.com>
 Daniel Robinson <gottagetmac@gmail.com>
 Daniel Von Fange <daniel@leancoder.com>
 Daniel YC Lin <dlin.tw@gmail.com>
+Darren Coxall <darren@darrencoxall.com>
 David Calavera <david.calavera@gmail.com>
 David Sissitka <me@dsissitka.com>
 Deni Bertovic <deni@kset.org>
@@ -69,12 +70,14 @@ Gabriel Monroy <gabriel@opdemand.com>
 Gareth Rushgrove <gareth@morethanseven.net>
 Greg Thornton <xdissent@me.com>
 Guillaume J. Charmes <guillaume.charmes@dotcloud.com>
+Gurjeet Singh <gurjeet@singh.im>
 Guruprasad <lgp171188@gmail.com>
 Harley Laue <losinggeneration@gmail.com>
 Hector Castro <hectcastro@gmail.com>
 Hunter Blanks <hunter@twilio.com>
 Isao Jonas <isao.jonas@gmail.com>
 James Carr <james.r.carr@gmail.com>
+James Turnbull <james@lovedthanlost.net>
 Jason McVetta <jason.mcvetta@gmail.com>
 Jean-Baptiste Barth <jeanbaptiste.barth@gmail.com>
 Jeff Lindsay <progrium@gmail.com>
@@ -92,6 +95,7 @@ Jonathan Rudenberg <jonathan@titanous.com>
 Joost Cassee <joost@cassee.net>
 Jordan Arentsen <blissdev@gmail.com>
 Joseph Anthony Pasquale Holsten <joseph@josephholsten.com>
+Josh Poimboeuf <jpoimboe@redhat.com>
 Julien Barbier <write0@gmail.com>
 Jérôme Petazzoni <jerome.petazzoni@dotcloud.com>
 Karan Lyons <karan@karanlyons.com>
@@ -117,6 +121,7 @@ Marko Mikulicic <mmikulicic@gmail.com>
 Markus Fix <lispmeister@gmail.com>
 Martin Redmond <martin@tinychat.com>
 Matt Apperson <me@mattapperson.com>
+Mathieu Le Marec - Pasquet <kiorky@cryptelium.net>
 Matt Bachmann <bachmann.matt@gmail.com>
 Matthew Mueller <mattmuelle@gmail.com>
 Maxim Treskin <zerthurd@gmail.com>
@@ -140,6 +145,7 @@ odk- <github@odkurzacz.org>
 Pascal Borreli <pascal@borreli.com>
 Paul Bowsher <pbowsher@globalpersonals.co.uk>
 Paul Hammond <paul@paulhammond.org>
+Paul Nasrat <pnasrat@gmail.com>
 Phil Spitler <pspitler@gmail.com>
 Piotr Bogdan <ppbogdan@gmail.com>
 pysqz <randomq@126.com>
@@ -162,6 +168,7 @@ Sridatta Thatipamala <sthatipamala@gmail.com>
 Sridhar Ratnakumar <sridharr@activestate.com>
 Steeve Morin <steeve.morin@gmail.com>
 Stefan Praszalowicz <stefan@greplin.com>
+Sven Dowideit <SvenDowideit@home.org.au>
 Thatcher Peskens <thatcher@dotcloud.com>
 Thermionix <bond711@gmail.com>
 Thijs Terlouw <thijsterlouw@gmail.com>

CONTRIBUTING.md

@@ -1,11 +1,14 @@
 # Contributing to Docker
 
-Want to hack on Docker? Awesome! Here are instructions to get you started. They are probably not perfect, please let us know if anything feels
-wrong or incomplete.
+Want to hack on Docker? Awesome! Here are instructions to get you
+started. They are probably not perfect, please let us know if anything
+feels wrong or incomplete.
 
 ## Build Environment
 
-For instructions on setting up your development environment, please see our dedicated [dev environment setup docs](http://docs.docker.io/en/latest/contributing/devenvironment/).
+For instructions on setting up your development environment, please
+see our dedicated [dev environment setup
+docs](http://docs.docker.io/en/latest/contributing/devenvironment/).
 
 ## Contribution guidelines
 

Dockerfile

@@ -4,24 +4,24 @@
 #
 # # Assemble the full dev environment. This is slow the first time.
 # docker build -t docker .
-# # Apparmor messes with privileged mode: disable it
-# /etc/init.d/apparmor stop ; /etc/init.d/apparmor teardown
 #
 # # Mount your source in an interactive container for quick testing:
-# docker run -v `pwd`:/go/src/github.com/dotcloud/docker -privileged -lxc-conf=lxc.aa_profile=unconfined -i -t docker bash
-#
+# docker run -v `pwd`:/go/src/github.com/dotcloud/docker -privileged -i -t docker bash
 #
 # # Run the test suite:
-# docker run -privileged -lxc-conf=lxc.aa_profile=unconfined docker hack/make.sh test
+# docker run -privileged docker hack/make.sh test
 #
 # # Publish a release:
-# docker run -privileged -lxc-conf=lxc.aa_profile=unconfined \
+# docker run -privileged \
 #  -e AWS_S3_BUCKET=baz \
 #  -e AWS_ACCESS_KEY=foo \
 #  -e AWS_SECRET_KEY=bar \
 #  -e GPG_PASSPHRASE=gloubiboulga \
 #  docker hack/release.sh
 #
+# Note: Apparmor used to mess with privileged mode, but this is no longer
+# the case. Therefore, you don't have to disable it anymore.
+#
 
 docker-version 0.6.1
 from	ubuntu:12.04
@@ -36,7 +36,7 @@ run	apt-get install -y -q mercurial
 run apt-get install -y -q build-essential libsqlite3-dev
 
 # Install Go
-run	curl -s https://go.googlecode.com/files/go1.2rc2.src.tar.gz | tar -v -C /usr/local -xz
+run	curl -s https://go.googlecode.com/files/go1.2rc5.src.tar.gz | tar -v -C /usr/local -xz
 env	PATH	/usr/local/go/bin:/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin
 env	GOPATH	/go:/go/src/github.com/dotcloud/docker/vendor
 run cd /usr/local/go/src && ./make.bash && go install -ldflags '-w -linkmode external -extldflags "-static -Wl,--unresolved-symbols=ignore-in-shared-libs"' -tags netgo -a std
@@ -46,10 +46,9 @@ run	apt-get install -y -q ruby1.9.3 rubygems libffi-dev
 run	gem install --no-rdoc --no-ri fpm
 run	apt-get install -y -q reprepro dpkg-sig
 
-# Install s3cmd 1.0.1 (earlier versions don't support env variables in the config)
 run	apt-get install -y -q python-pip
-run	pip install s3cmd
-run	pip install python-magic
+run	pip install s3cmd==1.1.0-beta3
+run	pip install python-magic==0.4.6
 run	/bin/echo -e '[default]\naccess_key=$AWS_ACCESS_KEY\nsecret_key=$AWS_SECRET_KEY\n' > /.s3cfg
 
 # Runtime dependencies

NOTICE

@@ -8,35 +8,12 @@ by Keith Rarick, licensed under the MIT License.
 
 The following is courtesy of our legal counsel:
 
-Transfers of Docker shall be in accordance with applicable export
-controls of any country and all other applicable legal requirements.
-Docker shall not be distributed or downloaded to or in Cuba, Iran,
-North Korea, Sudan or Syria and shall not be distributed or downloaded
-to any person on the Denied Persons List administered by the U.S.
-Department of Commerce.
 
-What does that mean? 
-Here is a further explanation from our legal counsel:
+Use and transfer of Docker may be subject to certain restrictions by the
+United States and other governments.  
+It is your responsibility to ensure that your use and/or transfer does not
+violate applicable laws. 
 
-Like all software products that utilize cryptography, the export and
-use of Docker is subject to the U.S. Commerce Department's Export
-Administration Regulations (EAR) because it uses or contains
-cryptography (see
-http://www.bis.doc.gov/index.php/policy-guidance/encryption).  Certain
-free and open source software projects have a lightweight set of
-requirements, which can generally be met by providing email notice to
-the appropriate U.S. government agencies that their source code is
-available on a publicly available repository and making the
-appropriate statements in the README.
+For more information, please see http://www.bis.doc.gov
 
-The restrictions of the EAR apply to certain denied locations
-(currently Iran, Sudan, Syria, North Korea, or Cuba) and those
-individuals on the Denied Persons List, which is available here:
-http://www.bis.doc.gov/index.php/policy-guidance/lists-of-parties-of-concern/denied-persons-list.
-If you are incorporating Docker into a new open source project, the
-EAR restrictions apply to your incorporation of Docker into your
-project in the same manner as other cryptography-enabled projects,
-such as OpenSSL, almost all Linux distributions, etc.
-
-For more information, see http://www.apache.org/dev/crypto.html and/or
-seek legal counsel.
+See also http://www.apache.org/dev/crypto.html and/or seek legal counsel.

README.md

@@ -193,10 +193,9 @@ wrong or incomplete.
 *Brought to you courtesy of our legal counsel. For more context,
 please see the Notice document.*
 
-Transfers of Docker shall be in accordance with applicable export controls 
-of any country and all other applicable legal requirements. Without limiting the 
-foregoing, Docker shall not be distributed or downloaded to any individual or 
-location if such distribution or download would violate the applicable US 
-government export regulations. 
+Use and transfer of Docker may be subject to certain restrictions by the
+United States and other governments.  
+It is your responsibility to ensure that your use and/or transfer does not
+violate applicable laws. 
 
 For more information, please see http://www.bis.doc.gov

VERSION

@@ -1 +1 @@
-0.6.5
+0.6.7

Vagrantfile

@@ -4,65 +4,135 @@
 BOX_NAME = ENV['BOX_NAME'] || "ubuntu"
 BOX_URI = ENV['BOX_URI'] || "http://files.vagrantup.com/precise64.box"
 VF_BOX_URI = ENV['BOX_URI'] || "http://files.vagrantup.com/precise64_vmware_fusion.box"
+AWS_BOX_URI = ENV['BOX_URI'] || "https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box"
 AWS_REGION = ENV['AWS_REGION'] || "us-east-1"
-AWS_AMI    = ENV['AWS_AMI']    || "ami-d0f89fb9"
+AWS_AMI = ENV['AWS_AMI'] || "ami-69f5a900"
+AWS_INSTANCE_TYPE = ENV['AWS_INSTANCE_TYPE'] || 't1.micro'
+
 FORWARD_DOCKER_PORTS = ENV['FORWARD_DOCKER_PORTS']
 
+SSH_PRIVKEY_PATH = ENV["SSH_PRIVKEY_PATH"]
+
+# A script to upgrade from the 12.04 kernel to the raring backport kernel (3.8)
+# and install docker.
+$script = <<SCRIPT
+# The username to add to the docker group will be passed as the first argument
+# to the script.  If nothing is passed, default to "vagrant".
+user="$1"
+if [ -z "$user" ]; then
+    user=vagrant
+fi
+
+# Adding an apt gpg key is idempotent.
+wget -q -O - https://get.docker.io/gpg | apt-key add -
+
+# Creating the docker.list file is idempotent, but it may overrite desired
+# settings if it already exists.  This could be solved with md5sum but it
+# doesn't seem worth it.
+echo 'deb http://get.docker.io/ubuntu docker main' > \
+    /etc/apt/sources.list.d/docker.list
+
+# Update remote package metadata.  'apt-get update' is idempotent.
+apt-get update -q
+
+# Install docker.  'apt-get install' is idempotent.
+apt-get install -q -y lxc-docker
+
+usermod -a -G docker "$user"
+
+tmp=`mktemp -q` && {
+    # Only install the backport kernel, don't bother upgrade if the backport is
+    # already installed.  We want parse the output of apt so we need to save it
+    # with 'tee'.  NOTE: The installation of the kernel will trigger dkms to
+    # install vboxguest if needed.
+    apt-get install -q -y --no-upgrade linux-image-generic-lts-raring | \
+        tee "$tmp"
+
+    # Parse the number of installed packages from the output
+    NUM_INST=`awk '$2 == "upgraded," && $4 == "newly" { print $3 }' "$tmp"`
+    rm "$tmp"
+}
+
+# If the number of installed packages is greater than 0, we want to reboot (the
+# backport kernel was installed but is not running).
+if [ "$NUM_INST" -gt 0 ];
+then
+    echo "Rebooting down to activate new kernel."
+    echo "/vagrant will not be mounted.  Use 'vagrant halt' followed by"
+    echo "'vagrant up' to ensure /vagrant is mounted."
+    shutdown -r now
+fi
+SCRIPT
+
+# We need to install the virtualbox guest additions *before* we do the normal
+# docker installation.  As such this script is prepended to the common docker
+# install script above.  This allows the install of the backport kernel to
+# trigger dkms to build the virtualbox guest module install.
+$vbox_script = <<VBOX_SCRIPT + $script
+# Install the VirtualBox guest additions if they aren't already installed.
+if [ ! -d /opt/VBoxGuestAdditions-4.3.2/ ]; then
+    # Update remote package metadata.  'apt-get update' is idempotent.
+    apt-get update -q
+
+    # Kernel Headers and dkms are required to build the vbox guest kernel
+    # modules.
+    apt-get install -q -y linux-headers-generic-lts-raring dkms
+
+    echo 'Downloading VBox Guest Additions...'
+    wget -cq http://dlc.sun.com.edgesuite.net/virtualbox/4.3.2/VBoxGuestAdditions_4.3.2.iso
+
+    mount -o loop,ro /home/vagrant/VBoxGuestAdditions_4.3.2.iso /mnt
+    /mnt/VBoxLinuxAdditions.run --nox11
+    umount /mnt
+fi
+VBOX_SCRIPT
+
 Vagrant::Config.run do |config|
   # Setup virtual machine box. This VM configuration code is always executed.
   config.vm.box = BOX_NAME
   config.vm.box_url = BOX_URI
 
-  config.ssh.forward_agent = true
-
-  # Provision docker and new kernel if deployment was not done.
-  # It is assumed Vagrant can successfully launch the provider instance.
-  if Dir.glob("#{File.dirname(__FILE__)}/.vagrant/machines/default/*/id").empty?
-    # Add lxc-docker package
-    pkg_cmd = "wget -q -O - https://get.docker.io/gpg | apt-key add -;" \
-      "echo deb http://get.docker.io/ubuntu docker main > /etc/apt/sources.list.d/docker.list;" \
-      "apt-get update -qq; apt-get install -q -y --force-yes lxc-docker; "
-    # Add Ubuntu raring backported kernel
-    pkg_cmd << "apt-get update -qq; apt-get install -q -y linux-image-generic-lts-raring; "
-    # Add guest additions if local vbox VM. As virtualbox is the default provider,
-    # it is assumed it won't be explicitly stated.
-    if ENV["VAGRANT_DEFAULT_PROVIDER"].nil? && ARGV.none? { |arg| arg.downcase.start_with?("--provider") }
-      pkg_cmd << "apt-get install -q -y linux-headers-generic-lts-raring dkms; " \
-        "echo 'Downloading VBox Guest Additions...'; " \
-        "wget -q http://dlc.sun.com.edgesuite.net/virtualbox/4.2.12/VBoxGuestAdditions_4.2.12.iso; "
-      # Prepare the VM to add guest additions after reboot
-      pkg_cmd << "echo -e 'mount -o loop,ro /home/vagrant/VBoxGuestAdditions_4.2.12.iso /mnt\n" \
-        "echo yes | /mnt/VBoxLinuxAdditions.run\numount /mnt\n" \
-          "rm /root/guest_additions.sh; ' > /root/guest_additions.sh; " \
-        "chmod 700 /root/guest_additions.sh; " \
-        "sed -i -E 's#^exit 0#[ -x /root/guest_additions.sh ] \\&\\& /root/guest_additions.sh#' /etc/rc.local; " \
-        "echo 'Installation of VBox Guest Additions is proceeding in the background.'; " \
-        "echo '\"vagrant reload\" can be used in about 2 minutes to activate the new guest additions.'; "
-    end
-    # Add vagrant user to the docker group
-    pkg_cmd << "usermod -a -G docker vagrant; "
-    # Activate new kernel
-    pkg_cmd << "shutdown -r +1; "
-    config.vm.provision :shell, :inline => pkg_cmd
+  # Use the specified private key path if it is specified and not empty.
+  if SSH_PRIVKEY_PATH
+      config.ssh.private_key_path = SSH_PRIVKEY_PATH
   end
+
+  config.ssh.forward_agent = true
 end
 
-
 # Providers were added on Vagrant >= 1.1.0
+#
+# NOTE: The vagrant "vm.provision" appends its arguments to a list and executes
+# them in order.  If you invoke "vm.provision :shell, :inline => $script"
+# twice then vagrant will run the script two times.  Unfortunately when you use
+# providers and the override argument to set up provisioners (like the vbox
+# guest extensions) they 1) don't replace the other provisioners (they append
+# to the end of the list) and 2) you can't control the order the provisioners
+# are executed (you can only append to the list).  If you want the virtualbox
+# only script to run before the other script, you have to jump through a lot of
+# hoops.
+#
+# Here is my only repeatable solution: make one script that is common ($script)
+# and another script that is the virtual box guest *prepended* to the common
+# script.  Only ever use "vm.provision" *one time* per provider.  That means
+# every single provider has an override, and every single one configures
+# "vm.provision".  Much saddness, but such is life.
 Vagrant::VERSION >= "1.1.0" and Vagrant.configure("2") do |config|
   config.vm.provider :aws do |aws, override|
-    aws.access_key_id = ENV["AWS_ACCESS_KEY_ID"]
-    aws.secret_access_key = ENV["AWS_SECRET_ACCESS_KEY"]
+    username = "ubuntu"
+    override.vm.box_url = AWS_BOX_URI
+    override.vm.provision :shell, :inline => $script, :args => username
+    aws.access_key_id = ENV["AWS_ACCESS_KEY"]
+    aws.secret_access_key = ENV["AWS_SECRET_KEY"]
     aws.keypair_name = ENV["AWS_KEYPAIR_NAME"]
-    override.ssh.private_key_path = ENV["AWS_SSH_PRIVKEY"]
-    override.ssh.username = "ubuntu"
+    override.ssh.username = username
     aws.region = AWS_REGION
     aws.ami    = AWS_AMI
-    aws.instance_type = "t1.micro"
+    aws.instance_type = AWS_INSTANCE_TYPE
   end
 
-  config.vm.provider :rackspace do |rs|
-    config.ssh.private_key_path = ENV["RS_PRIVATE_KEY"]
+  config.vm.provider :rackspace do |rs, override|
+    override.vm.provision :shell, :inline => $script
     rs.username = ENV["RS_USERNAME"]
     rs.api_key  = ENV["RS_API_KEY"]
     rs.public_key_path = ENV["RS_PUBLIC_KEY"]
@@ -71,20 +141,25 @@ Vagrant::VERSION >= "1.1.0" and Vagrant.configure("2") do |config|
   end
 
   config.vm.provider :vmware_fusion do |f, override|
-    override.vm.box = BOX_NAME
     override.vm.box_url = VF_BOX_URI
     override.vm.synced_folder ".", "/vagrant", disabled: true
+    override.vm.provision :shell, :inline => $script
     f.vmx["displayName"] = "docker"
   end
 
-  config.vm.provider :virtualbox do |vb|
-    config.vm.box = BOX_NAME
-    config.vm.box_url = BOX_URI
+  config.vm.provider :virtualbox do |vb, override|
+    override.vm.provision :shell, :inline => $vbox_script
     vb.customize ["modifyvm", :id, "--natdnshostresolver1", "on"]
     vb.customize ["modifyvm", :id, "--natdnsproxy1", "on"]
   end
 end
 
+# If this is a version 1 config, virtualbox is the only option.  A version 2
+# config would have already been set in the above provider section.
+Vagrant::VERSION < "1.1.0" and Vagrant::Config.run do |config|
+  config.vm.provision :shell, :inline => $vbox_script
+end
+
 if !FORWARD_DOCKER_PORTS.nil?
   Vagrant::VERSION < "1.1.0" and Vagrant::Config.run do |config|
     (49000..49900).each do |port|

api.go

@@ -5,6 +5,7 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"fmt"
+	"github.com/dotcloud/docker/archive"
 	"github.com/dotcloud/docker/auth"
 	"github.com/dotcloud/docker/utils"
 	"github.com/gorilla/mux"
@@ -22,7 +23,7 @@ import (
 )
 
 const (
-	APIVERSION        = 1.6
+	APIVERSION        = 1.7
 	DEFAULTHTTPHOST   = "127.0.0.1"
 	DEFAULTHTTPPORT   = 4243
 	DEFAULTUNIXSOCKET = "/var/run/docker.sock"
@@ -60,7 +61,10 @@ func parseMultipartForm(r *http.Request) error {
 
 func httpError(w http.ResponseWriter, err error) {
 	statusCode := http.StatusInternalServerError
-	if strings.HasPrefix(err.Error(), "No such") {
+	// FIXME: this is brittle and should not be necessary.
+	// If we need to differentiate between different possible error types, we should
+	// create appropriate error types with clearly defined meaning.
+	if strings.Contains(err.Error(), "No such") {
 		statusCode = http.StatusNotFound
 	} else if strings.HasPrefix(err.Error(), "Bad parameter") {
 		statusCode = http.StatusBadRequest
@@ -145,13 +149,12 @@ func postContainersKill(srv *Server, version float64, w http.ResponseWriter, r *
 
 	signal := 0
 	if r != nil {
-		s := r.Form.Get("signal")
-		if s != "" {
-			if s, err := strconv.Atoi(s); err != nil {
+		if s := r.Form.Get("signal"); s != "" {
+			s, err := strconv.Atoi(s)
+			if err != nil {
 				return err
-			} else {
-				signal = s
 			}
+			signal = s
 		}
 	}
 	if err := srv.ContainerKill(name, signal); err != nil {
@@ -190,10 +193,23 @@ func getImagesJSON(srv *Server, version float64, w http.ResponseWriter, r *http.
 		return err
 	}
 
+	if version < 1.7 {
+		outs2 := []APIImagesOld{}
+		for _, ctnr := range outs {
+			outs2 = append(outs2, ctnr.ToLegacy()...)
+		}
+
+		return writeJSON(w, http.StatusOK, outs2)
+	}
 	return writeJSON(w, http.StatusOK, outs)
 }
 
 func getImagesViz(srv *Server, version float64, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
+	if version > 1.6 {
+		w.WriteHeader(http.StatusNotFound)
+		return fmt.Errorf("This is now implemented in the client.")
+	}
+
 	if err := srv.ImagesViz(w); err != nil {
 		return err
 	}
@@ -235,6 +251,7 @@ func getEvents(srv *Server, version float64, w http.ResponseWriter, r *http.Requ
 	}
 	w.Header().Set("Content-Type", "application/json")
 	wf := utils.NewWriteFlusher(w)
+	wf.Flush()
 	if since != 0 {
 		// If since, send previous events that happened after the timestamp
 		for _, event := range srv.events {
@@ -297,13 +314,10 @@ func getContainersTop(srv *Server, version float64, w http.ResponseWriter, r *ht
 	if err := parseForm(r); err != nil {
 		return err
 	}
-	name := vars["name"]
-	ps_args := r.Form.Get("ps_args")
-	procsStr, err := srv.ContainerTop(name, ps_args)
+	procsStr, err := srv.ContainerTop(vars["name"], r.Form.Get("ps_args"))
 	if err != nil {
 		return err
 	}
-
 	return writeJSON(w, http.StatusOK, procsStr)
 }
 
@@ -331,13 +345,12 @@ func getContainersJSON(srv *Server, version float64, w http.ResponseWriter, r *h
 	if version < 1.5 {
 		outs2 := []APIContainersOld{}
 		for _, ctnr := range outs {
-			outs2 = append(outs2, ctnr.ToLegacy())
+			outs2 = append(outs2, *ctnr.ToLegacy())
 		}
 
 		return writeJSON(w, http.StatusOK, outs2)
-	} else {
-		return writeJSON(w, http.StatusOK, outs)
 	}
+	return writeJSON(w, http.StatusOK, outs)
 }
 
 func postImagesTag(srv *Server, version float64, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
@@ -463,15 +476,16 @@ func postImagesInsert(srv *Server, version float64, w http.ResponseWriter, r *ht
 		w.Header().Set("Content-Type", "application/json")
 	}
 	sf := utils.NewStreamFormatter(version > 1.0)
-	imgID, err := srv.ImageInsert(name, url, path, w, sf)
+	err := srv.ImageInsert(name, url, path, w, sf)
 	if err != nil {
 		if sf.Used() {
 			w.Write(sf.FormatError(err))
 			return nil
 		}
+		return err
 	}
 
-	return writeJSON(w, http.StatusOK, &APIID{ID: imgID})
+	return nil
 }
 
 func postImagesPush(srv *Server, version float64, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
@@ -520,47 +534,52 @@ func postImagesPush(srv *Server, version float64, w http.ResponseWriter, r *http
 	return nil
 }
 
+func getImagesGet(srv *Server, version float64, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
+	name := vars["name"]
+	if version > 1.0 {
+		w.Header().Set("Content-Type", "application/x-tar")
+	}
+	return srv.ImageExport(name, w)
+}
+
+func postImagesLoad(srv *Server, version float64, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
+	return srv.ImageLoad(r.Body)
+}
+
 func postContainersCreate(srv *Server, version float64, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
 	if err := parseForm(r); err != nil {
 		return nil
 	}
-	config := &Config{}
 	out := &APIRun{}
-	name := r.Form.Get("name")
-
-	if err := json.NewDecoder(r.Body).Decode(config); err != nil {
+	job := srv.Eng.Job("create", r.Form.Get("name"))
+	if err := job.DecodeEnv(r.Body); err != nil {
 		return err
 	}
-
 	resolvConf, err := utils.GetResolvConf()
 	if err != nil {
 		return err
 	}
-
-	if !config.NetworkDisabled && len(config.Dns) == 0 && len(srv.runtime.config.Dns) == 0 && utils.CheckLocalDns(resolvConf) {
+	if !job.GetenvBool("NetworkDisabled") && len(job.Getenv("Dns")) == 0 && len(srv.runtime.config.Dns) == 0 && utils.CheckLocalDns(resolvConf) {
 		out.Warnings = append(out.Warnings, fmt.Sprintf("Docker detected local DNS server on resolv.conf. Using default external servers: %v", defaultDns))
-		config.Dns = defaultDns
+		job.SetenvList("Dns", defaultDns)
 	}
-
-	id, warnings, err := srv.ContainerCreate(config, name)
-	if err != nil {
+	// Read container ID from the first line of stdout
+	job.StdoutParseString(&out.ID)
+	// Read warnings from stderr
+	job.StderrParseLines(&out.Warnings, 0)
+	if err := job.Run(); err != nil {
 		return err
 	}
-	out.ID = id
-	for _, warning := range warnings {
-		out.Warnings = append(out.Warnings, warning)
-	}
-
-	if config.Memory > 0 && !srv.runtime.capabilities.MemoryLimit {
+	if job.GetenvInt("Memory") > 0 && !srv.runtime.capabilities.MemoryLimit {
 		log.Println("WARNING: Your kernel does not support memory limit capabilities. Limitation discarded.")
 		out.Warnings = append(out.Warnings, "Your kernel does not support memory limit capabilities. Limitation discarded.")
 	}
-	if config.Memory > 0 && !srv.runtime.capabilities.SwapLimit {
+	if job.GetenvInt("Memory") > 0 && !srv.runtime.capabilities.SwapLimit {
 		log.Println("WARNING: Your kernel does not support swap limit capabilities. Limitation discarded.")
 		out.Warnings = append(out.Warnings, "Your kernel does not support memory swap capabilities. Limitation discarded.")
 	}
 
-	if !config.NetworkDisabled && srv.runtime.capabilities.IPv4ForwardingDisabled {
+	if !job.GetenvBool("NetworkDisabled") && srv.runtime.capabilities.IPv4ForwardingDisabled {
 		log.Println("Warning: IPv4 forwarding is disabled.")
 		out.Warnings = append(out.Warnings, "IPv4 forwarding is disabled.")
 	}
@@ -627,36 +646,28 @@ func deleteImages(srv *Server, version float64, w http.ResponseWriter, r *http.R
 	if imgs != nil {
 		if len(imgs) != 0 {
 			return writeJSON(w, http.StatusOK, imgs)
-		} else {
-			return fmt.Errorf("Conflict, %s wasn't deleted", name)
 		}
-	} else {
-		w.WriteHeader(http.StatusNoContent)
+		return fmt.Errorf("Conflict, %s wasn't deleted", name)
 	}
+	w.WriteHeader(http.StatusNoContent)
 	return nil
 }
 
 func postContainersStart(srv *Server, version float64, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
-	var hostConfig *HostConfig
-	// allow a nil body for backwards compatibility
-	if r.Body != nil {
-		if matchesContentType(r.Header.Get("Content-Type"), "application/json") {
-			hostConfig = &HostConfig{}
-			if err := json.NewDecoder(r.Body).Decode(hostConfig); err != nil {
-				return err
-			}
-		}
-	}
-
 	if vars == nil {
 		return fmt.Errorf("Missing parameter")
 	}
 	name := vars["name"]
-	// Register any links from the host config before starting the container
-	if err := srv.RegisterLinks(name, hostConfig); err != nil {
-		return err
+	job := srv.Eng.Job("start", name)
+	// allow a nil body for backwards compatibility
+	if r.Body != nil {
+		if matchesContentType(r.Header.Get("Content-Type"), "application/json") {
+			if err := job.DecodeEnv(r.Body); err != nil {
+				return err
+			}
+		}
 	}
-	if err := srv.ContainerStart(name, hostConfig); err != nil {
+	if err := job.Run(); err != nil {
 		return err
 	}
 	w.WriteHeader(http.StatusNoContent)
@@ -905,7 +916,7 @@ func postBuild(srv *Server, version float64, w http.ResponseWriter, r *http.Requ
 			return fmt.Errorf("Error trying to use git: %s (%s)", err, output)
 		}
 
-		c, err := Tar(root, Bzip2)
+		c, err := archive.Tar(root, archive.Bzip2)
 		if err != nil {
 			return err
 		}
@@ -920,7 +931,7 @@ func postBuild(srv *Server, version float64, w http.ResponseWriter, r *http.Requ
 		if err != nil {
 			return err
 		}
-		c, err := mkBuildContext(string(dockerFile), nil)
+		c, err := MkBuildContext(string(dockerFile), nil)
 		if err != nil {
 			return err
 		}
@@ -968,7 +979,7 @@ func postContainersCopy(srv *Server, version float64, w http.ResponseWriter, r *
 	}
 
 	if copyData.Resource == "" {
-		return fmt.Errorf("Resource cannot be empty")
+		return fmt.Errorf("Path cannot be empty")
 	}
 	if copyData.Resource[0] == '/' {
 		copyData.Resource = copyData.Resource[1:]
@@ -1037,6 +1048,7 @@ func createRouter(srv *Server, logging bool) (*mux.Router, error) {
 			"/images/json":                    getImagesJSON,
 			"/images/viz":                     getImagesViz,
 			"/images/search":                  getImagesSearch,
+			"/images/{name:.*}/get":           getImagesGet,
 			"/images/{name:.*}/history":       getImagesHistory,
 			"/images/{name:.*}/json":          getImagesByName,
 			"/containers/ps":                  getContainersJSON,
@@ -1053,6 +1065,7 @@ func createRouter(srv *Server, logging bool) (*mux.Router, error) {
 			"/build":                        postBuild,
 			"/images/create":                postImagesCreate,
 			"/images/{name:.*}/insert":      postImagesInsert,
+			"/images/load":                  postImagesLoad,
 			"/images/{name:.*}/push":        postImagesPush,
 			"/images/{name:.*}/tag":         postImagesTag,
 			"/containers/create":            postContainersCreate,
@@ -1098,6 +1111,20 @@ func createRouter(srv *Server, logging bool) (*mux.Router, error) {
 	return r, nil
 }
 
+// ServeRequest processes a single http request to the docker remote api.
+// FIXME: refactor this to be part of Server and not require re-creating a new
+// router each time. This requires first moving ListenAndServe into Server.
+func ServeRequest(srv *Server, apiversion float64, w http.ResponseWriter, req *http.Request) error {
+	router, err := createRouter(srv, false)
+	if err != nil {
+		return err
+	}
+	// Insert APIVERSION into the request as a convenience
+	req.URL.Path = fmt.Sprintf("/v%g%s", apiversion, req.URL.Path)
+	router.ServeHTTP(w, req)
+	return nil
+}
+
 func ListenAndServe(proto, addr string, srv *Server, logging bool) error {
 	log.Printf("Listening for HTTP on %s (%s)\n", addr, proto)
 

api_params.go

@@ -1,123 +1,148 @@
 package docker
 
-type APIHistory struct {
-	ID        string   `json:"Id"`
-	Tags      []string `json:",omitempty"`
-	Created   int64
-	CreatedBy string `json:",omitempty"`
+import "strings"
+
+type (
+	APIHistory struct {
+		ID        string   `json:"Id"`
+		Tags      []string `json:",omitempty"`
+		Created   int64
+		CreatedBy string `json:",omitempty"`
+		Size      int64
+	}
+
+	APIImages struct {
+		ID          string   `json:"Id"`
+		RepoTags    []string `json:",omitempty"`
+		Created     int64
+		Size        int64
+		VirtualSize int64
+		ParentId    string `json:",omitempty"`
+	}
+
+	APIImagesOld struct {
+		Repository  string `json:",omitempty"`
+		Tag         string `json:",omitempty"`
+		ID          string `json:"Id"`
+		Created     int64
+		Size        int64
+		VirtualSize int64
+	}
+
+	APIInfo struct {
+		Debug              bool
+		Containers         int
+		Images             int
+		NFd                int    `json:",omitempty"`
+		NGoroutines        int    `json:",omitempty"`
+		MemoryLimit        bool   `json:",omitempty"`
+		SwapLimit          bool   `json:",omitempty"`
+		IPv4Forwarding     bool   `json:",omitempty"`
+		LXCVersion         string `json:",omitempty"`
+		NEventsListener    int    `json:",omitempty"`
+		KernelVersion      string `json:",omitempty"`
+		IndexServerAddress string `json:",omitempty"`
+	}
+
+	APITop struct {
+		Titles    []string
+		Processes [][]string
+	}
+
+	APIRmi struct {
+		Deleted  string `json:",omitempty"`
+		Untagged string `json:",omitempty"`
+	}
+
+	APIContainers struct {
+		ID         string `json:"Id"`
+		Image      string
+		Command    string
+		Created    int64
+		Status     string
+		Ports      []APIPort
+		SizeRw     int64
+		SizeRootFs int64
+		Names      []string
+	}
+
+	APIContainersOld struct {
+		ID         string `json:"Id"`
+		Image      string
+		Command    string
+		Created    int64
+		Status     string
+		Ports      string
+		SizeRw     int64
+		SizeRootFs int64
+	}
+
+	APIID struct {
+		ID string `json:"Id"`
+	}
+
+	APIRun struct {
+		ID       string   `json:"Id"`
+		Warnings []string `json:",omitempty"`
+	}
+
+	APIPort struct {
+		PrivatePort int64
+		PublicPort  int64
+		Type        string
+		IP          string
+	}
+
+	APIVersion struct {
+		Version   string
+		GitCommit string `json:",omitempty"`
+		GoVersion string `json:",omitempty"`
+	}
+
+	APIWait struct {
+		StatusCode int
+	}
+
+	APIAuth struct {
+		Status string
+	}
+
+	APIImageConfig struct {
+		ID string `json:"Id"`
+		*Config
+	}
+
+	APICopy struct {
+		Resource string
+		HostPath string
+	}
+)
+
+func (api APIImages) ToLegacy() []APIImagesOld {
+	outs := []APIImagesOld{}
+	for _, repotag := range api.RepoTags {
+		components := strings.SplitN(repotag, ":", 2)
+		outs = append(outs, APIImagesOld{
+			ID:          api.ID,
+			Repository:  components[0],
+			Tag:         components[1],
+			Created:     api.Created,
+			Size:        api.Size,
+			VirtualSize: api.VirtualSize,
+		})
+	}
+	return outs
 }
 
-type APIImages struct {
-	Repository  string `json:",omitempty"`
-	Tag         string `json:",omitempty"`
-	ID          string `json:"Id"`
-	Created     int64
-	Size        int64
-	VirtualSize int64
-}
-
-type APIInfo struct {
-	Debug              bool
-	Containers         int
-	Images             int
-	NFd                int    `json:",omitempty"`
-	NGoroutines        int    `json:",omitempty"`
-	MemoryLimit        bool   `json:",omitempty"`
-	SwapLimit          bool   `json:",omitempty"`
-	IPv4Forwarding     bool   `json:",omitempty"`
-	LXCVersion         string `json:",omitempty"`
-	NEventsListener    int    `json:",omitempty"`
-	KernelVersion      string `json:",omitempty"`
-	IndexServerAddress string `json:",omitempty"`
-}
-
-type APITop struct {
-	Titles    []string
-	Processes [][]string
-}
-
-type APIRmi struct {
-	Deleted  string `json:",omitempty"`
-	Untagged string `json:",omitempty"`
-}
-
-type APIContainers struct {
-	ID         string `json:"Id"`
-	Image      string
-	Command    string
-	Created    int64
-	Status     string
-	Ports      []APIPort
-	SizeRw     int64
-	SizeRootFs int64
-	Names      []string
-}
-
-func (self *APIContainers) ToLegacy() APIContainersOld {
-	return APIContainersOld{
-		ID:         self.ID,
-		Image:      self.Image,
-		Command:    self.Command,
-		Created:    self.Created,
-		Status:     self.Status,
-		Ports:      displayablePorts(self.Ports),
-		SizeRw:     self.SizeRw,
-		SizeRootFs: self.SizeRootFs,
+func (api APIContainers) ToLegacy() *APIContainersOld {
+	return &APIContainersOld{
+		ID:         api.ID,
+		Image:      api.Image,
+		Command:    api.Command,
+		Created:    api.Created,
+		Status:     api.Status,
+		Ports:      displayablePorts(api.Ports),
+		SizeRw:     api.SizeRw,
+		SizeRootFs: api.SizeRootFs,
 	}
 }
-
-type APIContainersOld struct {
-	ID         string `json:"Id"`
-	Image      string
-	Command    string
-	Created    int64
-	Status     string
-	Ports      string
-	SizeRw     int64
-	SizeRootFs int64
-}
-
-type APISearch struct {
-	Name        string
-	Description string
-}
-
-type APIID struct {
-	ID string `json:"Id"`
-}
-
-type APIRun struct {
-	ID       string   `json:"Id"`
-	Warnings []string `json:",omitempty"`
-}
-
-type APIPort struct {
-	PrivatePort int64
-	PublicPort  int64
-	Type        string
-	IP          string
-}
-
-type APIVersion struct {
-	Version   string
-	GitCommit string `json:",omitempty"`
-	GoVersion string `json:",omitempty"`
-}
-
-type APIWait struct {
-	StatusCode int
-}
-
-type APIAuth struct {
-	Status string
-}
-
-type APIImageConfig struct {
-	ID string `json:"Id"`
-	*Config
-}
-
-type APICopy struct {
-	Resource string
-	HostPath string
-}

api_unit_test.go

@@ -0,0 +1,19 @@
+package docker
+
+import (
+	"testing"
+)
+
+func TestJsonContentType(t *testing.T) {
+	if !matchesContentType("application/json", "application/json") {
+		t.Fail()
+	}
+
+	if !matchesContentType("application/json; charset=utf-8", "application/json") {
+		t.Fail()
+	}
+
+	if matchesContentType("dockerapplication/json", "application/json") {
+		t.Fail()
+	}
+}

archive/MAINTAINERS

@@ -0,0 +1 @@
+Michael Crosby <michael@crosbymichael.com> (@crosbymichael)

archive/archive.go

@@ -1,4 +1,4 @@
-package docker
+package archive
 
 import (
 	"archive/tar"
@@ -109,16 +109,17 @@ func Untar(archive io.Reader, path string) error {
 	buf := make([]byte, 10)
 	totalN := 0
 	for totalN < 10 {
-		if n, err := archive.Read(buf[totalN:]); err != nil {
+		n, err := archive.Read(buf[totalN:])
+		if err != nil {
 			if err == io.EOF {
 				return fmt.Errorf("Tarball too short")
 			}
 			return err
-		} else {
-			totalN += n
-			utils.Debugf("[tar autodetect] n: %d", n)
 		}
+		totalN += n
+		utils.Debugf("[tar autodetect] n: %d", n)
 	}
+
 	compression := DetectCompression(buf)
 
 	utils.Debugf("Archive compression detected: %s", compression.Extension())

archive/archive_test.go

@@ -1,4 +1,4 @@
-package docker
+package archive
 
 import (
 	"bytes"

auth/auth.go

@@ -196,10 +196,9 @@ func Login(authConfig *AuthConfig, factory *utils.HTTPRequestFactory) (string, e
 		if loginAgainstOfficialIndex {
 			return "", fmt.Errorf("Login: Your account hasn't been activated. " +
 				"Please check your e-mail for a confirmation link.")
-		} else {
-			return "", fmt.Errorf("Login: Your account hasn't been activated. " +
-				"Please see the documentation of the registry " + serverAddress + " for instructions how to activate it.")
 		}
+		return "", fmt.Errorf("Login: Your account hasn't been activated. " +
+			"Please see the documentation of the registry " + serverAddress + " for instructions how to activate it.")
 	} else if reqStatusCode == 400 {
 		if string(reqBody) == "\"Username or email already exists\"" {
 			req, err := factory.NewRequest("GET", serverAddress+"users/", nil)

auth/auth_test.go

@@ -1,11 +1,8 @@
 package auth
 
 import (
-	"crypto/rand"
-	"encoding/hex"
 	"io/ioutil"
 	"os"
-	"strings"
 	"testing"
 )
 
@@ -29,52 +26,6 @@ func TestEncodeAuth(t *testing.T) {
 	}
 }
 
-func TestLogin(t *testing.T) {
-	os.Setenv("DOCKER_INDEX_URL", "https://indexstaging-docker.dotcloud.com")
-	defer os.Setenv("DOCKER_INDEX_URL", "")
-	authConfig := &AuthConfig{Username: "unittester", Password: "surlautrerivejetattendrai", Email: "noise+unittester@dotcloud.com"}
-	status, err := Login(authConfig, nil)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if status != "Login Succeeded" {
-		t.Fatalf("Expected status \"Login Succeeded\", found \"%s\" instead", status)
-	}
-}
-
-func TestCreateAccount(t *testing.T) {
-	os.Setenv("DOCKER_INDEX_URL", "https://indexstaging-docker.dotcloud.com")
-	defer os.Setenv("DOCKER_INDEX_URL", "")
-	tokenBuffer := make([]byte, 16)
-	_, err := rand.Read(tokenBuffer)
-	if err != nil {
-		t.Fatal(err)
-	}
-	token := hex.EncodeToString(tokenBuffer)[:12]
-	username := "ut" + token
-	authConfig := &AuthConfig{Username: username, Password: "test42", Email: "docker-ut+" + token + "@example.com"}
-	status, err := Login(authConfig, nil)
-	if err != nil {
-		t.Fatal(err)
-	}
-	expectedStatus := "Account created. Please use the confirmation link we sent" +
-		" to your e-mail to activate it."
-	if status != expectedStatus {
-		t.Fatalf("Expected status: \"%s\", found \"%s\" instead.", expectedStatus, status)
-	}
-
-	status, err = Login(authConfig, nil)
-	if err == nil {
-		t.Fatalf("Expected error but found nil instead")
-	}
-
-	expectedError := "Login: Account is not Active"
-
-	if !strings.Contains(err.Error(), expectedError) {
-		t.Fatalf("Expected message \"%s\" but found \"%s\" instead", expectedError, err)
-	}
-}
-
 func setupTempConfigFile() (*ConfigFile, error) {
 	root, err := ioutil.TempDir("", "docker-test-auth")
 	if err != nil {

buildfile.go

@@ -3,6 +3,7 @@ package docker
 import (
 	"encoding/json"
 	"fmt"
+	"github.com/dotcloud/docker/archive"
 	"github.com/dotcloud/docker/utils"
 	"io"
 	"io/ioutil"
@@ -64,6 +65,9 @@ func (b *buildFile) CmdFrom(name string) error {
 	}
 	b.image = image.ID
 	b.config = &Config{}
+	if image.Config != nil {
+		b.config = image.Config
+	}
 	if b.config.Env == nil || len(b.config.Env) == 0 {
 		b.config.Env = append(b.config.Env, "HOME=/", "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin")
 	}
@@ -291,17 +295,17 @@ func (b *buildFile) addContext(container *Container, orig, dest string) error {
 		return fmt.Errorf("%s: no such file or directory", orig)
 	}
 	if fi.IsDir() {
-		if err := CopyWithTar(origPath, destPath); err != nil {
+		if err := archive.CopyWithTar(origPath, destPath); err != nil {
 			return err
 		}
 		// First try to unpack the source as an archive
-	} else if err := UntarPath(origPath, destPath); err != nil {
+	} else if err := archive.UntarPath(origPath, destPath); err != nil {
 		utils.Debugf("Couldn't untar %s to %s: %s", origPath, destPath, err)
 		// If that fails, just copy it as a regular file
 		if err := os.MkdirAll(path.Dir(destPath), 0755); err != nil {
 			return err
 		}
-		if err := CopyWithTar(origPath, destPath); err != nil {
+		if err := archive.CopyWithTar(origPath, destPath); err != nil {
 			return err
 		}
 	}
@@ -387,8 +391,7 @@ func (b *buildFile) run() (string, error) {
 	}
 
 	//start the container
-	hostConfig := &HostConfig{}
-	if err := c.Start(hostConfig); err != nil {
+	if err := c.Start(); err != nil {
 		return "", err
 	}
 
@@ -473,7 +476,7 @@ func (b *buildFile) Build(context io.Reader) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	if err := Untar(context, name); err != nil {
+	if err := archive.Untar(context, name); err != nil {
 		return "", err
 	}
 	defer os.RemoveAll(name)

config.go

@@ -1,13 +1,14 @@
 package docker
 
 import (
+	"github.com/dotcloud/docker/engine"
 	"net"
 )
 
+// FIXME: separate runtime configuration from http api configuration
 type DaemonConfig struct {
 	Pidfile                     string
-	GraphPath                   string
-	ProtoAddresses              []string
+	Root                        string
 	AutoRestart                 bool
 	EnableCors                  bool
 	Dns                         []string
@@ -16,3 +17,25 @@ type DaemonConfig struct {
 	DefaultIp                   net.IP
 	InterContainerCommunication bool
 }
+
+// ConfigFromJob creates and returns a new DaemonConfig object
+// by parsing the contents of a job's environment.
+func ConfigFromJob(job *engine.Job) *DaemonConfig {
+	var config DaemonConfig
+	config.Pidfile = job.Getenv("Pidfile")
+	config.Root = job.Getenv("Root")
+	config.AutoRestart = job.GetenvBool("AutoRestart")
+	config.EnableCors = job.GetenvBool("EnableCors")
+	if dns := job.Getenv("Dns"); dns != "" {
+		config.Dns = []string{dns}
+	}
+	config.EnableIptables = job.GetenvBool("EnableIptables")
+	if br := job.Getenv("BridgeIface"); br != "" {
+		config.BridgeIface = br
+	} else {
+		config.BridgeIface = DefaultNetworkBridge
+	}
+	config.DefaultIp = net.ParseIP(job.Getenv("DefaultIp"))
+	config.InterContainerCommunication = job.GetenvBool("InterContainerCommunication")
+	return &config
+}

config_test.go

@@ -0,0 +1,149 @@
+package docker
+
+import (
+	"testing"
+)
+
+func TestCompareConfig(t *testing.T) {
+	volumes1 := make(map[string]struct{})
+	volumes1["/test1"] = struct{}{}
+	config1 := Config{
+		Dns:         []string{"1.1.1.1", "2.2.2.2"},
+		PortSpecs:   []string{"1111:1111", "2222:2222"},
+		Env:         []string{"VAR1=1", "VAR2=2"},
+		VolumesFrom: "11111111",
+		Volumes:     volumes1,
+	}
+	config2 := Config{
+		Dns:         []string{"0.0.0.0", "2.2.2.2"},
+		PortSpecs:   []string{"1111:1111", "2222:2222"},
+		Env:         []string{"VAR1=1", "VAR2=2"},
+		VolumesFrom: "11111111",
+		Volumes:     volumes1,
+	}
+	config3 := Config{
+		Dns:         []string{"1.1.1.1", "2.2.2.2"},
+		PortSpecs:   []string{"0000:0000", "2222:2222"},
+		Env:         []string{"VAR1=1", "VAR2=2"},
+		VolumesFrom: "11111111",
+		Volumes:     volumes1,
+	}
+	config4 := Config{
+		Dns:         []string{"1.1.1.1", "2.2.2.2"},
+		PortSpecs:   []string{"0000:0000", "2222:2222"},
+		Env:         []string{"VAR1=1", "VAR2=2"},
+		VolumesFrom: "22222222",
+		Volumes:     volumes1,
+	}
+	volumes2 := make(map[string]struct{})
+	volumes2["/test2"] = struct{}{}
+	config5 := Config{
+		Dns:         []string{"1.1.1.1", "2.2.2.2"},
+		PortSpecs:   []string{"0000:0000", "2222:2222"},
+		Env:         []string{"VAR1=1", "VAR2=2"},
+		VolumesFrom: "11111111",
+		Volumes:     volumes2,
+	}
+	if CompareConfig(&config1, &config2) {
+		t.Fatalf("CompareConfig should return false, Dns are different")
+	}
+	if CompareConfig(&config1, &config3) {
+		t.Fatalf("CompareConfig should return false, PortSpecs are different")
+	}
+	if CompareConfig(&config1, &config4) {
+		t.Fatalf("CompareConfig should return false, VolumesFrom are different")
+	}
+	if CompareConfig(&config1, &config5) {
+		t.Fatalf("CompareConfig should return false, Volumes are different")
+	}
+	if !CompareConfig(&config1, &config1) {
+		t.Fatalf("CompareConfig should return true")
+	}
+}
+
+func TestMergeConfig(t *testing.T) {
+	volumesImage := make(map[string]struct{})
+	volumesImage["/test1"] = struct{}{}
+	volumesImage["/test2"] = struct{}{}
+	configImage := &Config{
+		Dns:         []string{"1.1.1.1", "2.2.2.2"},
+		PortSpecs:   []string{"1111:1111", "2222:2222"},
+		Env:         []string{"VAR1=1", "VAR2=2"},
+		VolumesFrom: "1111",
+		Volumes:     volumesImage,
+	}
+
+	volumesUser := make(map[string]struct{})
+	volumesUser["/test3"] = struct{}{}
+	configUser := &Config{
+		Dns:       []string{"3.3.3.3"},
+		PortSpecs: []string{"3333:2222", "3333:3333"},
+		Env:       []string{"VAR2=3", "VAR3=3"},
+		Volumes:   volumesUser,
+	}
+
+	if err := MergeConfig(configUser, configImage); err != nil {
+		t.Error(err)
+	}
+
+	if len(configUser.Dns) != 3 {
+		t.Fatalf("Expected 3 dns, 1.1.1.1, 2.2.2.2 and 3.3.3.3, found %d", len(configUser.Dns))
+	}
+	for _, dns := range configUser.Dns {
+		if dns != "1.1.1.1" && dns != "2.2.2.2" && dns != "3.3.3.3" {
+			t.Fatalf("Expected 1.1.1.1 or 2.2.2.2 or 3.3.3.3, found %s", dns)
+		}
+	}
+
+	if len(configUser.ExposedPorts) != 3 {
+		t.Fatalf("Expected 3 ExposedPorts, 1111, 2222 and 3333, found %d", len(configUser.ExposedPorts))
+	}
+	for portSpecs := range configUser.ExposedPorts {
+		if portSpecs.Port() != "1111" && portSpecs.Port() != "2222" && portSpecs.Port() != "3333" {
+			t.Fatalf("Expected 1111 or 2222 or 3333, found %s", portSpecs)
+		}
+	}
+	if len(configUser.Env) != 3 {
+		t.Fatalf("Expected 3 env var, VAR1=1, VAR2=3 and VAR3=3, found %d", len(configUser.Env))
+	}
+	for _, env := range configUser.Env {
+		if env != "VAR1=1" && env != "VAR2=3" && env != "VAR3=3" {
+			t.Fatalf("Expected VAR1=1 or VAR2=3 or VAR3=3, found %s", env)
+		}
+	}
+
+	if len(configUser.Volumes) != 3 {
+		t.Fatalf("Expected 3 volumes, /test1, /test2 and /test3, found %d", len(configUser.Volumes))
+	}
+	for v := range configUser.Volumes {
+		if v != "/test1" && v != "/test2" && v != "/test3" {
+			t.Fatalf("Expected /test1 or /test2 or /test3, found %s", v)
+		}
+	}
+
+	if configUser.VolumesFrom != "1111" {
+		t.Fatalf("Expected VolumesFrom to be 1111, found %s", configUser.VolumesFrom)
+	}
+
+	ports, _, err := parsePortSpecs([]string{"0000"})
+	if err != nil {
+		t.Error(err)
+	}
+	configImage2 := &Config{
+		ExposedPorts: ports,
+	}
+
+	if err := MergeConfig(configUser, configImage2); err != nil {
+		t.Error(err)
+	}
+
+	if len(configUser.ExposedPorts) != 4 {
+		t.Fatalf("Expected 4 ExposedPorts, 0000, 1111, 2222 and 3333, found %d", len(configUser.ExposedPorts))
+	}
+	for portSpecs := range configUser.ExposedPorts {
+		if portSpecs.Port() != "0000" && portSpecs.Port() != "1111" && portSpecs.Port() != "2222" && portSpecs.Port() != "3333" {
+			t.Fatalf("Expected 0000 or 1111 or 2222 or 3333, found %s", portSpecs)
+		}
+	}
+
+}

container.go

@@ -4,8 +4,8 @@ import (
 	"bytes"
 	"encoding/json"
 	"errors"
-	"flag"
 	"fmt"
+	"github.com/dotcloud/docker/archive"
 	"github.com/dotcloud/docker/term"
 	"github.com/dotcloud/docker/utils"
 	"github.com/kr/pty"
@@ -19,11 +19,14 @@ import (
 	"path/filepath"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 )
 
 type Container struct {
+	sync.Mutex
+
 	root string
 
 	ID string
@@ -59,11 +62,15 @@ type Container struct {
 	Volumes  map[string]string
 	// Store rw/ro in a separate structure to preserve reverse-compatibility on-disk.
 	// Easier than migrating older container configs :)
-	VolumesRW map[string]bool
+	VolumesRW  map[string]bool
+	hostConfig *HostConfig
 
 	activeLinks map[string]*Link
 }
 
+// Note: the Config structure should hold only portable information about the container.
+// Here, "portable" means "independent from the host we are running on".
+// Non-portable information *should* appear in HostConfig.
 type Config struct {
 	Hostname        string
 	Domainname      string
@@ -88,15 +95,16 @@ type Config struct {
 	WorkingDir      string
 	Entrypoint      []string
 	NetworkDisabled bool
-	Privileged      bool
 }
 
 type HostConfig struct {
 	Binds           []string
 	ContainerIDFile string
 	LxcConf         []KeyValuePair
+	Privileged      bool
 	PortBindings    map[Port][]PortBinding
 	Links           []string
+	PublishAllPorts bool
 }
 
 type BindMap struct {
@@ -127,7 +135,11 @@ type PortBinding struct {
 type Port string
 
 func (p Port) Proto() string {
-	return strings.Split(string(p), "/")[1]
+	parts := strings.Split(string(p), "/")
+	if len(parts) == 1 {
+		return "tcp"
+	}
+	return parts[1]
 }
 
 func (p Port) Port() string {
@@ -146,189 +158,6 @@ func NewPort(proto, port string) Port {
 	return Port(fmt.Sprintf("%s/%s", port, proto))
 }
 
-func ParseRun(args []string, capabilities *Capabilities) (*Config, *HostConfig, *flag.FlagSet, error) {
-	cmd := Subcmd("run", "[OPTIONS] IMAGE [COMMAND] [ARG...]", "Run a command in a new container")
-	if os.Getenv("TEST") != "" {
-		cmd.SetOutput(ioutil.Discard)
-		cmd.Usage = nil
-	}
-
-	flHostname := cmd.String("h", "", "Container host name")
-	flWorkingDir := cmd.String("w", "", "Working directory inside the container")
-	flUser := cmd.String("u", "", "Username or UID")
-	flDetach := cmd.Bool("d", false, "Detached mode: Run container in the background, print new container id")
-	flAttach := NewAttachOpts()
-	cmd.Var(flAttach, "a", "Attach to stdin, stdout or stderr.")
-	flStdin := cmd.Bool("i", false, "Keep stdin open even if not attached")
-	flTty := cmd.Bool("t", false, "Allocate a pseudo-tty")
-	flMemory := cmd.Int64("m", 0, "Memory limit (in bytes)")
-	flContainerIDFile := cmd.String("cidfile", "", "Write the container ID to the file")
-	flNetwork := cmd.Bool("n", true, "Enable networking for this container")
-	flPrivileged := cmd.Bool("privileged", false, "Give extended privileges to this container")
-	flAutoRemove := cmd.Bool("rm", false, "Automatically remove the container when it exits (incompatible with -d)")
-	cmd.Bool("sig-proxy", true, "Proxify all received signal to the process (even in non-tty mode)")
-	cmd.String("name", "", "Assign a name to the container")
-
-	if capabilities != nil && *flMemory > 0 && !capabilities.MemoryLimit {
-		//fmt.Fprintf(stdout, "WARNING: Your kernel does not support memory limit capabilities. Limitation discarded.\n")
-		*flMemory = 0
-	}
-
-	flCpuShares := cmd.Int64("c", 0, "CPU shares (relative weight)")
-
-	var flPublish utils.ListOpts
-	cmd.Var(&flPublish, "p", "Publish a container's port to the host (use 'docker port' to see the actual mapping)")
-
-	var flExpose utils.ListOpts
-	cmd.Var(&flExpose, "expose", "Expose a port from the container without publishing it to your host")
-
-	var flEnv utils.ListOpts
-	cmd.Var(&flEnv, "e", "Set environment variables")
-
-	var flDns utils.ListOpts
-	cmd.Var(&flDns, "dns", "Set custom dns servers")
-
-	flVolumes := NewPathOpts()
-	cmd.Var(flVolumes, "v", "Bind mount a volume (e.g. from the host: -v /host:/container, from docker: -v /container)")
-
-	var flVolumesFrom utils.ListOpts
-	cmd.Var(&flVolumesFrom, "volumes-from", "Mount volumes from the specified container")
-
-	flEntrypoint := cmd.String("entrypoint", "", "Overwrite the default entrypoint of the image")
-
-	var flLxcOpts utils.ListOpts
-	cmd.Var(&flLxcOpts, "lxc-conf", "Add custom lxc options -lxc-conf=\"lxc.cgroup.cpuset.cpus = 0,1\"")
-
-	var flLinks utils.ListOpts
-	cmd.Var(&flLinks, "link", "Add link to another container (name:alias)")
-
-	if err := cmd.Parse(args); err != nil {
-		return nil, nil, cmd, err
-	}
-	if *flDetach && len(flAttach) > 0 {
-		return nil, nil, cmd, ErrConflictAttachDetach
-	}
-	if *flWorkingDir != "" && !path.IsAbs(*flWorkingDir) {
-		return nil, nil, cmd, ErrInvalidWorikingDirectory
-	}
-	if *flDetach && *flAutoRemove {
-		return nil, nil, cmd, ErrConflictDetachAutoRemove
-	}
-
-	// If neither -d or -a are set, attach to everything by default
-	if len(flAttach) == 0 && !*flDetach {
-		if !*flDetach {
-			flAttach.Set("stdout")
-			flAttach.Set("stderr")
-			if *flStdin {
-				flAttach.Set("stdin")
-			}
-		}
-	}
-
-	var binds []string
-
-	// add any bind targets to the list of container volumes
-	for bind := range flVolumes {
-		arr := strings.Split(bind, ":")
-		if len(arr) > 1 {
-			dstDir := arr[1]
-			flVolumes[dstDir] = struct{}{}
-			binds = append(binds, bind)
-			delete(flVolumes, bind)
-		}
-	}
-
-	parsedArgs := cmd.Args()
-	runCmd := []string{}
-	entrypoint := []string{}
-	image := ""
-	if len(parsedArgs) >= 1 {
-		image = cmd.Arg(0)
-	}
-	if len(parsedArgs) > 1 {
-		runCmd = parsedArgs[1:]
-	}
-	if *flEntrypoint != "" {
-		entrypoint = []string{*flEntrypoint}
-	}
-
-	var lxcConf []KeyValuePair
-	lxcConf, err := parseLxcConfOpts(flLxcOpts)
-	if err != nil {
-		return nil, nil, cmd, err
-	}
-
-	hostname := *flHostname
-	domainname := ""
-
-	parts := strings.SplitN(hostname, ".", 2)
-	if len(parts) > 1 {
-		hostname = parts[0]
-		domainname = parts[1]
-	}
-
-	ports, portBindings, err := parsePortSpecs(flPublish)
-	if err != nil {
-		return nil, nil, cmd, err
-	}
-
-	// Merge in exposed ports to the map of published ports
-	for _, e := range flExpose {
-		if strings.Contains(e, ":") {
-			return nil, nil, cmd, fmt.Errorf("Invalid port format for -expose: %s", e)
-		}
-		p := NewPort(splitProtoPort(e))
-		if _, exists := ports[p]; !exists {
-			ports[p] = struct{}{}
-		}
-	}
-
-	config := &Config{
-		Hostname:        *flHostname,
-		Domainname:      domainname,
-		PortSpecs:       nil, // Deprecated
-		ExposedPorts:    ports,
-		User:            *flUser,
-		Tty:             *flTty,
-		NetworkDisabled: !*flNetwork,
-		OpenStdin:       *flStdin,
-		Memory:          *flMemory,
-		CpuShares:       *flCpuShares,
-		AttachStdin:     flAttach.Get("stdin"),
-		AttachStdout:    flAttach.Get("stdout"),
-		AttachStderr:    flAttach.Get("stderr"),
-		Env:             flEnv,
-		Cmd:             runCmd,
-		Dns:             flDns,
-		Image:           image,
-		Volumes:         flVolumes,
-		VolumesFrom:     strings.Join(flVolumesFrom, ","),
-		Entrypoint:      entrypoint,
-		Privileged:      *flPrivileged,
-		WorkingDir:      *flWorkingDir,
-	}
-
-	hostConfig := &HostConfig{
-		Binds:           binds,
-		ContainerIDFile: *flContainerIDFile,
-		LxcConf:         lxcConf,
-		PortBindings:    portBindings,
-		Links:           flLinks,
-	}
-
-	if capabilities != nil && *flMemory > 0 && !capabilities.SwapLimit {
-		//fmt.Fprintf(stdout, "WARNING: Your kernel does not support swap limit capabilities. Limitation discarded.\n")
-		config.MemorySwap = -1
-	}
-
-	// When allocating stdin in attached mode, close stdin at client disconnect
-	if config.OpenStdin && config.AttachStdin {
-		config.StdinOnce = true
-	}
-	return config, hostConfig, cmd, nil
-}
-
 type PortMapping map[string]string // Deprecated
 
 type NetworkSettings struct {
@@ -367,11 +196,22 @@ func (settings *NetworkSettings) PortMappingAPI() []APIPort {
 
 // Inject the io.Reader at the given path. Note: do not close the reader
 func (container *Container) Inject(file io.Reader, pth string) error {
+	// Return error if path exists
+	if _, err := os.Stat(path.Join(container.rwPath(), pth)); err == nil {
+		// Since err is nil, the path could be stat'd and it exists
+		return fmt.Errorf("%s exists", pth)
+	} else if !os.IsNotExist(err) {
+		// Expect err might be that the file doesn't exist, so
+		// if it's some other error, return that.
+
+		return err
+	}
+
 	// Make sure the directory exists
 	if err := os.MkdirAll(path.Join(container.rwPath(), path.Dir(pth)), 0755); err != nil {
 		return err
 	}
-	// FIXME: Handle permissions/already existing dest
+
 	dest, err := os.Create(path.Join(container.rwPath(), pth))
 	if err != nil {
 		return err
@@ -400,7 +240,7 @@ func (container *Container) FromDisk() error {
 	if err := json.Unmarshal(data, container); err != nil && !strings.Contains(err.Error(), "docker.PortMapping") {
 		return err
 	}
-	return nil
+	return container.readHostConfig()
 }
 
 func (container *Container) ToDisk() (err error) {
@@ -408,44 +248,53 @@ func (container *Container) ToDisk() (err error) {
 	if err != nil {
 		return
 	}
-	return ioutil.WriteFile(container.jsonPath(), data, 0666)
+	err = ioutil.WriteFile(container.jsonPath(), data, 0666)
+	if err != nil {
+		return
+	}
+	return container.writeHostConfig()
 }
 
-func (container *Container) ReadHostConfig() (*HostConfig, error) {
+func (container *Container) readHostConfig() error {
+	container.hostConfig = &HostConfig{}
+	// If the hostconfig file does not exist, do not read it.
+	// (We still have to initialize container.hostConfig,
+	// but that's OK, since we just did that above.)
+	_, err := os.Stat(container.hostConfigPath())
+	if os.IsNotExist(err) {
+		return nil
+	}
 	data, err := ioutil.ReadFile(container.hostConfigPath())
 	if err != nil {
-		return &HostConfig{}, err
+		return err
 	}
-	hostConfig := &HostConfig{}
-	if err := json.Unmarshal(data, hostConfig); err != nil {
-		return &HostConfig{}, err
-	}
-	return hostConfig, nil
+	return json.Unmarshal(data, container.hostConfig)
 }
 
-func (container *Container) SaveHostConfig(hostConfig *HostConfig) (err error) {
-	data, err := json.Marshal(hostConfig)
+func (container *Container) writeHostConfig() (err error) {
+	data, err := json.Marshal(container.hostConfig)
 	if err != nil {
 		return
 	}
 	return ioutil.WriteFile(container.hostConfigPath(), data, 0666)
 }
 
-func (container *Container) generateLXCConfig(hostConfig *HostConfig) error {
+func (container *Container) generateEnvConfig(env []string) error {
+	data, err := json.Marshal(env)
+	if err != nil {
+		return err
+	}
+	ioutil.WriteFile(container.EnvConfigPath(), data, 0600)
+	return nil
+}
+
+func (container *Container) generateLXCConfig() error {
 	fo, err := os.Create(container.lxcConfigPath())
 	if err != nil {
 		return err
 	}
 	defer fo.Close()
-	if err := LxcTemplateCompiled.Execute(fo, container); err != nil {
-		return err
-	}
-	if hostConfig != nil {
-		if err := LxcHostConfigTemplateCompiled.Execute(fo, hostConfig); err != nil {
-			return err
-		}
-	}
-	return nil
+	return LxcTemplateCompiled.Execute(fo, container)
 }
 
 func (container *Container) startPty() error {
@@ -640,31 +489,29 @@ func (container *Container) Attach(stdin io.ReadCloser, stdinCloser io.Closer, s
 	})
 }
 
-func (container *Container) Start(hostConfig *HostConfig) (err error) {
-	container.State.Lock()
-	defer container.State.Unlock()
+func (container *Container) Start() (err error) {
+	container.Lock()
+	defer container.Unlock()
+
+	if container.State.IsRunning() {
+		return fmt.Errorf("The container %s is already running.", container.ID)
+	}
 	defer func() {
 		if err != nil {
 			container.cleanup()
 		}
 	}()
-
-	if hostConfig == nil { // in docker start of docker restart we want to reuse previous HostConfigFile
-		hostConfig, _ = container.ReadHostConfig()
-	}
-
-	if container.State.Running {
-		return fmt.Errorf("The container %s is already running.", container.ID)
-	}
 	if err := container.EnsureMounted(); err != nil {
 		return err
 	}
 	if container.runtime.networkManager.disabled {
 		container.Config.NetworkDisabled = true
+		container.buildHostnameAndHostsFiles("127.0.1.1")
 	} else {
-		if err := container.allocateNetwork(hostConfig); err != nil {
+		if err := container.allocateNetwork(); err != nil {
 			return err
 		}
+		container.buildHostnameAndHostsFiles(container.NetworkSettings.IPAddress)
 	}
 
 	// Make sure the config is compatible with the current kernel
@@ -686,7 +533,7 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 	// Define illegal container destinations
 	illegalDsts := []string{"/", "."}
 
-	for _, bind := range hostConfig.Binds {
+	for _, bind := range container.hostConfig.Binds {
 		// FIXME: factorize bind parsing in parseBind
 		var src, dst, mode string
 		arr := strings.Split(bind, ":")
@@ -724,9 +571,23 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 
 	// Apply volumes from another container if requested
 	if container.Config.VolumesFrom != "" {
-		volumes := strings.Split(container.Config.VolumesFrom, ",")
-		for _, v := range volumes {
-			c := container.runtime.Get(v)
+		containerSpecs := strings.Split(container.Config.VolumesFrom, ",")
+		for _, containerSpec := range containerSpecs {
+			mountRW := true
+			specParts := strings.SplitN(containerSpec, ":", 2)
+			switch len(specParts) {
+			case 0:
+				return fmt.Errorf("Malformed volumes-from specification: %s", container.Config.VolumesFrom)
+			case 2:
+				switch specParts[1] {
+				case "ro":
+					mountRW = false
+				case "rw": // mountRW is already true
+				default:
+					return fmt.Errorf("Malformed volumes-from speficication: %s", containerSpec)
+				}
+			}
+			c := container.runtime.Get(specParts[0])
 			if c == nil {
 				return fmt.Errorf("Container %s not found. Impossible to mount its volumes", container.ID)
 			}
@@ -739,7 +600,7 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 				}
 				container.Volumes[volPath] = id
 				if isRW, exists := c.VolumesRW[volPath]; exists {
-					container.VolumesRW[volPath] = isRW
+					container.VolumesRW[volPath] = isRW && mountRW
 				}
 			}
 
@@ -780,7 +641,7 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 		// Create the mountpoint
 		rootVolPath := path.Join(container.RootfsPath(), volPath)
 		if err := os.MkdirAll(rootVolPath, 0755); err != nil {
-			return nil
+			return err
 		}
 
 		// Do not copy or change permissions if we are mounting from the host
@@ -796,7 +657,7 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 				}
 				if len(srcList) == 0 {
 					// If the source volume is empty copy files from the root into the volume
-					if err := CopyWithTar(rootVolPath, srcPath); err != nil {
+					if err := archive.CopyWithTar(rootVolPath, srcPath); err != nil {
 						return err
 					}
 
@@ -820,11 +681,17 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 		}
 	}
 
-	if err := container.generateLXCConfig(hostConfig); err != nil {
+	if err := container.generateLXCConfig(); err != nil {
 		return err
 	}
 
+	var lxcStart string = "lxc-start"
+	if container.hostConfig.Privileged && container.runtime.capabilities.AppArmor {
+		lxcStart = path.Join(container.runtime.config.Root, "lxc-start-unconfined")
+	}
+
 	params := []string{
+		lxcStart,
 		"-n", container.ID,
 		"-f", container.lxcConfigPath(),
 		"--",
@@ -841,17 +708,17 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 		params = append(params, "-u", container.Config.User)
 	}
 
-	if container.Config.Tty {
-		params = append(params, "-e", "TERM=xterm")
+	// Setup environment
+	env := []string{
+		"HOME=/",
+		"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+		"container=lxc",
+		"HOSTNAME=" + container.Config.Hostname,
 	}
 
-	// Setup environment
-	params = append(params,
-		"-e", "HOME=/",
-		"-e", "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
-		"-e", "container=lxc",
-		"-e", "HOSTNAME="+container.Config.Hostname,
-	)
+	if container.Config.Tty {
+		env = append(env, "TERM=xterm")
+	}
 
 	// Init any links between the parent and children
 	runtime := container.runtime
@@ -887,11 +754,19 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 			}
 
 			for _, envVar := range link.ToEnv() {
-				params = append(params, "-e", envVar)
+				env = append(env, envVar)
 			}
 		}
 	}
 
+	for _, elem := range container.Config.Env {
+		env = append(env, elem)
+	}
+
+	if err := container.generateEnvConfig(env); err != nil {
+		return err
+	}
+
 	if container.Config.WorkingDir != "" {
 		workingDir := path.Clean(container.Config.WorkingDir)
 		utils.Debugf("[working dir] working dir is %s", workingDir)
@@ -905,15 +780,27 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 		)
 	}
 
-	for _, elem := range container.Config.Env {
-		params = append(params, "-e", elem)
-	}
-
 	// Program
 	params = append(params, "--", container.Path)
 	params = append(params, container.Args...)
 
-	container.cmd = exec.Command("lxc-start", params...)
+	if RootIsShared() {
+		// lxc-start really needs / to be non-shared, or all kinds of stuff break
+		// when lxc-start unmount things and those unmounts propagate to the main
+		// mount namespace.
+		// What we really want is to clone into a new namespace and then
+		// mount / MS_REC|MS_SLAVE, but since we can't really clone or fork
+		// without exec in go we have to do this horrible shell hack...
+		shellString :=
+			"mount --make-rslave /; exec " +
+				utils.ShellQuoteArguments(params)
+
+		params = []string{
+			"unshare", "-m", "--", "/bin/sh", "-c", shellString,
+		}
+	}
+
+	container.cmd = exec.Command(params[0], params[1:]...)
 
 	// Setup logging of stdout and stderr to disk
 	if err := container.runtime.LogToDisk(container.stdout, container.logPath("json"), "stdout"); err != nil {
@@ -935,23 +822,22 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 	}
 	// FIXME: save state on disk *first*, then converge
 	// this way disk state is used as a journal, eg. we can restore after crash etc.
-	container.State.setRunning(container.cmd.Process.Pid)
+	container.State.SetRunning(container.cmd.Process.Pid)
 
 	// Init the lock
 	container.waitLock = make(chan struct{})
 
 	container.ToDisk()
-	container.SaveHostConfig(hostConfig)
-	go container.monitor(hostConfig)
+	go container.monitor()
 
-	defer utils.Debugf("Container running: %v", container.State.Running)
+	defer utils.Debugf("Container running: %v", container.State.IsRunning())
 	// We wait for the container to be fully running.
 	// Timeout after 5 seconds. In case of broken pipe, just retry.
 	// Note: The container can run and finish correctly before
 	//       the end of this loop
 	for now := time.Now(); time.Since(now) < 5*time.Second; {
 		// If the container dies while waiting for it, just return
-		if !container.State.Running {
+		if !container.State.IsRunning() {
 			return nil
 		}
 		output, err := exec.Command("lxc-info", "-s", "-n", container.ID).CombinedOutput()
@@ -968,18 +854,18 @@ func (container *Container) Start(hostConfig *HostConfig) (err error) {
 		if strings.Contains(string(output), "RUNNING") {
 			return nil
 		}
-		utils.Debugf("Waiting for the container to start (running: %v): %s", container.State.Running, bytes.TrimSpace(output))
+		utils.Debugf("Waiting for the container to start (running: %v): %s", container.State.IsRunning(), bytes.TrimSpace(output))
 		time.Sleep(50 * time.Millisecond)
 	}
 
-	if container.State.Running {
+	if container.State.IsRunning() {
 		return ErrContainerStartTimeout
 	}
 	return ErrContainerStart
 }
 
 func (container *Container) Run() error {
-	if err := container.Start(&HostConfig{}); err != nil {
+	if err := container.Start(); err != nil {
 		return err
 	}
 	container.Wait()
@@ -992,8 +878,7 @@ func (container *Container) Output() (output []byte, err error) {
 		return nil, err
 	}
 	defer pipe.Close()
-	hostConfig := &HostConfig{}
-	if err := container.Start(hostConfig); err != nil {
+	if err := container.Start(); err != nil {
 		return nil, err
 	}
 	output, err = ioutil.ReadAll(pipe)
@@ -1025,21 +910,41 @@ func (container *Container) StderrPipe() (io.ReadCloser, error) {
 	return utils.NewBufReader(reader), nil
 }
 
-func (container *Container) allocateNetwork(hostConfig *HostConfig) error {
+func (container *Container) buildHostnameAndHostsFiles(IP string) {
+	container.HostnamePath = path.Join(container.root, "hostname")
+	ioutil.WriteFile(container.HostnamePath, []byte(container.Config.Hostname+"\n"), 0644)
+
+	hostsContent := []byte(`
+127.0.0.1	localhost
+::1		localhost ip6-localhost ip6-loopback
+fe00::0		ip6-localnet
+ff00::0		ip6-mcastprefix
+ff02::1		ip6-allnodes
+ff02::2		ip6-allrouters
+`)
+
+	container.HostsPath = path.Join(container.root, "hosts")
+
+	if container.Config.Domainname != "" {
+		hostsContent = append([]byte(fmt.Sprintf("%s\t%s.%s %s\n", IP, container.Config.Hostname, container.Config.Domainname, container.Config.Hostname)), hostsContent...)
+	} else {
+		hostsContent = append([]byte(fmt.Sprintf("%s\t%s\n", IP, container.Config.Hostname)), hostsContent...)
+	}
+
+	ioutil.WriteFile(container.HostsPath, hostsContent, 0644)
+}
+
+func (container *Container) allocateNetwork() error {
 	if container.Config.NetworkDisabled {
 		return nil
 	}
 
-	var iface *NetworkInterface
-	var err error
-	if !container.State.Ghost {
-		iface, err = container.runtime.networkManager.Allocate()
-		if err != nil {
-			return err
-		}
-	} else {
-		manager := container.runtime.networkManager
-		if manager.disabled {
+	var (
+		iface *NetworkInterface
+		err   error
+	)
+	if container.State.IsGhost() {
+		if manager := container.runtime.networkManager; manager.disabled {
 			iface = &NetworkInterface{disabled: true}
 		} else {
 			iface = &NetworkInterface{
@@ -1047,31 +952,45 @@ func (container *Container) allocateNetwork(hostConfig *HostConfig) error {
 				Gateway: manager.bridgeNetwork.IP,
 				manager: manager,
 			}
-			ipNum := ipToInt(iface.IPNet.IP)
-			manager.ipAllocator.inUse[ipNum] = struct{}{}
+			if iface != nil && iface.IPNet.IP != nil {
+				ipNum := ipToInt(iface.IPNet.IP)
+				manager.ipAllocator.inUse[ipNum] = struct{}{}
+			} else {
+				iface, err = container.runtime.networkManager.Allocate()
+				if err != nil {
+					return err
+				}
+			}
+		}
+	} else {
+		iface, err = container.runtime.networkManager.Allocate()
+		if err != nil {
+			return err
 		}
 	}
 
 	if container.Config.PortSpecs != nil {
 		utils.Debugf("Migrating port mappings for container: %s", strings.Join(container.Config.PortSpecs, ", "))
-		if err := migratePortMappings(container.Config, hostConfig); err != nil {
+		if err := migratePortMappings(container.Config, container.hostConfig); err != nil {
 			return err
 		}
 		container.Config.PortSpecs = nil
-		if err := container.SaveHostConfig(hostConfig); err != nil {
+		if err := container.writeHostConfig(); err != nil {
 			return err
 		}
 	}
 
-	portSpecs := make(map[Port]struct{})
-	bindings := make(map[Port][]PortBinding)
+	var (
+		portSpecs = make(map[Port]struct{})
+		bindings  = make(map[Port][]PortBinding)
+	)
 
-	if !container.State.Ghost {
+	if !container.State.IsGhost() {
 		if container.Config.ExposedPorts != nil {
 			portSpecs = container.Config.ExposedPorts
 		}
-		if hostConfig.PortBindings != nil {
-			bindings = hostConfig.PortBindings
+		if container.hostConfig.PortBindings != nil {
+			bindings = container.hostConfig.PortBindings
 		}
 	} else {
 		if container.NetworkSettings.Ports != nil {
@@ -1086,6 +1005,9 @@ func (container *Container) allocateNetwork(hostConfig *HostConfig) error {
 
 	for port := range portSpecs {
 		binding := bindings[port]
+		if container.hostConfig.PublishAllPorts && len(binding) == 0 {
+			binding = append(binding, PortBinding{})
+		}
 		for i := 0; i < len(binding); i++ {
 			b := binding[i]
 			nat, err := iface.AllocatePort(port, b)
@@ -1098,7 +1020,7 @@ func (container *Container) allocateNetwork(hostConfig *HostConfig) error {
 		}
 		bindings[port] = binding
 	}
-	container.SaveHostConfig(hostConfig)
+	container.writeHostConfig()
 
 	container.NetworkSettings.Ports = bindings
 	container.network = iface
@@ -1134,7 +1056,7 @@ func (container *Container) waitLxc() error {
 	}
 }
 
-func (container *Container) monitor(hostConfig *HostConfig) {
+func (container *Container) monitor() {
 	// Wait for the program to exit
 
 	// If the command does not exist, try to wait via lxc
@@ -1159,11 +1081,8 @@ func (container *Container) monitor(hostConfig *HostConfig) {
 		exitCode = container.cmd.ProcessState.Sys().(syscall.WaitStatus).ExitStatus()
 	}
 
-	// Report status back
-	container.State.setStopped(exitCode)
-
 	if container.runtime != nil && container.runtime.srv != nil {
-		container.runtime.srv.LogEvent("die", container.ShortID(), container.runtime.repositories.ImageName(container.Image))
+		container.runtime.srv.LogEvent("die", container.ID, container.runtime.repositories.ImageName(container.Image))
 	}
 
 	// Cleanup
@@ -1174,6 +1093,9 @@ func (container *Container) monitor(hostConfig *HostConfig) {
 		container.stdin, container.stdinPipe = io.Pipe()
 	}
 
+	// Report status back
+	container.State.SetStopped(exitCode)
+
 	// Release the lock
 	close(container.waitLock)
 
@@ -1222,15 +1144,15 @@ func (container *Container) cleanup() {
 }
 
 func (container *Container) kill(sig int) error {
-	container.State.Lock()
-	defer container.State.Unlock()
+	container.Lock()
+	defer container.Unlock()
 
-	if !container.State.Running {
+	if !container.State.IsRunning() {
 		return nil
 	}
 
 	if output, err := exec.Command("lxc-kill", "-n", container.ID, strconv.Itoa(sig)).CombinedOutput(); err != nil {
-		log.Printf("error killing container %s (%s, %s)", container.ShortID(), output, err)
+		log.Printf("error killing container %s (%s, %s)", utils.TruncateID(container.ID), output, err)
 		return err
 	}
 
@@ -1238,7 +1160,7 @@ func (container *Container) kill(sig int) error {
 }
 
 func (container *Container) Kill() error {
-	if !container.State.Running {
+	if !container.State.IsRunning() {
 		return nil
 	}
 
@@ -1250,9 +1172,9 @@ func (container *Container) Kill() error {
 	// 2. Wait for the process to die, in last resort, try to kill the process directly
 	if err := container.WaitTimeout(10 * time.Second); err != nil {
 		if container.cmd == nil {
-			return fmt.Errorf("lxc-kill failed, impossible to kill the container %s", container.ShortID())
+			return fmt.Errorf("lxc-kill failed, impossible to kill the container %s", utils.TruncateID(container.ID))
 		}
-		log.Printf("Container %s failed to exit within 10 seconds of lxc-kill %s - trying direct SIGKILL", "SIGKILL", container.ShortID())
+		log.Printf("Container %s failed to exit within 10 seconds of lxc-kill %s - trying direct SIGKILL", "SIGKILL", utils.TruncateID(container.ID))
 		if err := container.cmd.Process.Kill(); err != nil {
 			return err
 		}
@@ -1263,7 +1185,7 @@ func (container *Container) Kill() error {
 }
 
 func (container *Container) Stop(seconds int) error {
-	if !container.State.Running {
+	if !container.State.IsRunning() {
 		return nil
 	}
 
@@ -1291,17 +1213,13 @@ func (container *Container) Restart(seconds int) error {
 	if err := container.Stop(seconds); err != nil {
 		return err
 	}
-	hostConfig := &HostConfig{}
-	if err := container.Start(hostConfig); err != nil {
-		return err
-	}
-	return nil
+	return container.Start()
 }
 
 // Wait blocks until the container stops running, then returns its exit code.
 func (container *Container) Wait() int {
 	<-container.waitLock
-	return container.State.ExitCode
+	return container.State.GetExitCode()
 }
 
 func (container *Container) Resize(h, w int) error {
@@ -1312,23 +1230,23 @@ func (container *Container) Resize(h, w int) error {
 	return term.SetWinsize(pty.Fd(), &term.Winsize{Height: uint16(h), Width: uint16(w)})
 }
 
-func (container *Container) ExportRw() (Archive, error) {
-	return Tar(container.rwPath(), Uncompressed)
+func (container *Container) ExportRw() (archive.Archive, error) {
+	return archive.Tar(container.rwPath(), archive.Uncompressed)
 }
 
 func (container *Container) RwChecksum() (string, error) {
-	rwData, err := Tar(container.rwPath(), Xz)
+	rwData, err := archive.Tar(container.rwPath(), archive.Xz)
 	if err != nil {
 		return "", err
 	}
 	return utils.HashData(rwData)
 }
 
-func (container *Container) Export() (Archive, error) {
+func (container *Container) Export() (archive.Archive, error) {
 	if err := container.EnsureMounted(); err != nil {
 		return nil, err
 	}
-	return Tar(container.RootfsPath(), Uncompressed)
+	return archive.Tar(container.RootfsPath(), archive.Uncompressed)
 }
 
 func (container *Container) WaitTimeout(timeout time.Duration) error {
@@ -1392,14 +1310,6 @@ func (container *Container) Unmount() error {
 	return Unmount(container.RootfsPath())
 }
 
-// ShortID returns a shorthand version of the container's id for convenience.
-// A collision with other container shorthands is very unlikely, but possible.
-// In case of a collision a lookup with Runtime.Get() will fail, and the caller
-// will need to use a langer prefix, or the full-length container Id.
-func (container *Container) ShortID() string {
-	return utils.TruncateID(container.ID)
-}
-
 func (container *Container) logPath(name string) string {
 	return path.Join(container.root, fmt.Sprintf("%s-%s.log", container.ID, name))
 }
@@ -1416,6 +1326,10 @@ func (container *Container) jsonPath() string {
 	return path.Join(container.root, "config.json")
 }
 
+func (container *Container) EnvConfigPath() string {
+	return path.Join(container.root, "config.env")
+}
+
 func (container *Container) lxcConfigPath() string {
 	return path.Join(container.root, "config.lxc")
 }
@@ -1439,27 +1353,53 @@ func validateID(id string) error {
 // GetSize, return real size, virtual size
 func (container *Container) GetSize() (int64, int64) {
 	var sizeRw, sizeRootfs int64
+	data := make(map[uint64]bool)
 
 	filepath.Walk(container.rwPath(), func(path string, fileInfo os.FileInfo, err error) error {
-		if fileInfo != nil {
-			sizeRw += fileInfo.Size()
+		if fileInfo == nil {
+			return nil
 		}
+		size := fileInfo.Size()
+		if size == 0 {
+			return nil
+		}
+
+		inode := fileInfo.Sys().(*syscall.Stat_t).Ino
+		if _, entryExists := data[inode]; entryExists {
+			return nil
+		}
+		data[inode] = false
+
+		sizeRw += size
 		return nil
 	})
 
+	data = make(map[uint64]bool)
 	_, err := os.Stat(container.RootfsPath())
 	if err == nil {
 		filepath.Walk(container.RootfsPath(), func(path string, fileInfo os.FileInfo, err error) error {
-			if fileInfo != nil {
-				sizeRootfs += fileInfo.Size()
+			if fileInfo == nil {
+				return nil
 			}
+			size := fileInfo.Size()
+			if size == 0 {
+				return nil
+			}
+
+			inode := fileInfo.Sys().(*syscall.Stat_t).Ino
+			if _, entryExists := data[inode]; entryExists {
+				return nil
+			}
+			data[inode] = false
+
+			sizeRootfs += size
 			return nil
 		})
 	}
 	return sizeRw, sizeRootfs
 }
 
-func (container *Container) Copy(resource string) (Archive, error) {
+func (container *Container) Copy(resource string) (archive.Archive, error) {
 	if err := container.EnsureMounted(); err != nil {
 		return nil, err
 	}
@@ -1477,7 +1417,7 @@ func (container *Container) Copy(resource string) (Archive, error) {
 		filter = []string{path.Base(basePath)}
 		basePath = path.Dir(basePath)
 	}
-	return TarFilter(basePath, Uncompressed, filter)
+	return archive.TarFilter(basePath, archive.Uncompressed, filter)
 }
 
 // Returns true if the container exposes a certain port

container_unit_test.go

@@ -0,0 +1,161 @@
+package docker
+
+import (
+	"testing"
+)
+
+func TestParseLxcConfOpt(t *testing.T) {
+	opts := []string{"lxc.utsname=docker", "lxc.utsname = docker "}
+
+	for _, o := range opts {
+		k, v, err := parseLxcOpt(o)
+		if err != nil {
+			t.FailNow()
+		}
+		if k != "lxc.utsname" {
+			t.Fail()
+		}
+		if v != "docker" {
+			t.Fail()
+		}
+	}
+}
+
+func TestParseNetworkOptsPrivateOnly(t *testing.T) {
+	ports, bindings, err := parsePortSpecs([]string{"192.168.1.100::80"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(ports) != 1 {
+		t.Logf("Expected 1 got %d", len(ports))
+		t.FailNow()
+	}
+	if len(bindings) != 1 {
+		t.Logf("Expected 1 got %d", len(bindings))
+		t.FailNow()
+	}
+	for k := range ports {
+		if k.Proto() != "tcp" {
+			t.Logf("Expected tcp got %s", k.Proto())
+			t.Fail()
+		}
+		if k.Port() != "80" {
+			t.Logf("Expected 80 got %s", k.Port())
+			t.Fail()
+		}
+		b, exists := bindings[k]
+		if !exists {
+			t.Log("Binding does not exist")
+			t.FailNow()
+		}
+		if len(b) != 1 {
+			t.Logf("Expected 1 got %d", len(b))
+			t.FailNow()
+		}
+		s := b[0]
+		if s.HostPort != "" {
+			t.Logf("Expected \"\" got %s", s.HostPort)
+			t.Fail()
+		}
+		if s.HostIp != "192.168.1.100" {
+			t.Fail()
+		}
+	}
+}
+
+func TestParseNetworkOptsPublic(t *testing.T) {
+	ports, bindings, err := parsePortSpecs([]string{"192.168.1.100:8080:80"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(ports) != 1 {
+		t.Logf("Expected 1 got %d", len(ports))
+		t.FailNow()
+	}
+	if len(bindings) != 1 {
+		t.Logf("Expected 1 got %d", len(bindings))
+		t.FailNow()
+	}
+	for k := range ports {
+		if k.Proto() != "tcp" {
+			t.Logf("Expected tcp got %s", k.Proto())
+			t.Fail()
+		}
+		if k.Port() != "80" {
+			t.Logf("Expected 80 got %s", k.Port())
+			t.Fail()
+		}
+		b, exists := bindings[k]
+		if !exists {
+			t.Log("Binding does not exist")
+			t.FailNow()
+		}
+		if len(b) != 1 {
+			t.Logf("Expected 1 got %d", len(b))
+			t.FailNow()
+		}
+		s := b[0]
+		if s.HostPort != "8080" {
+			t.Logf("Expected 8080 got %s", s.HostPort)
+			t.Fail()
+		}
+		if s.HostIp != "192.168.1.100" {
+			t.Fail()
+		}
+	}
+}
+
+func TestParseNetworkOptsUdp(t *testing.T) {
+	ports, bindings, err := parsePortSpecs([]string{"192.168.1.100::6000/udp"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(ports) != 1 {
+		t.Logf("Expected 1 got %d", len(ports))
+		t.FailNow()
+	}
+	if len(bindings) != 1 {
+		t.Logf("Expected 1 got %d", len(bindings))
+		t.FailNow()
+	}
+	for k := range ports {
+		if k.Proto() != "udp" {
+			t.Logf("Expected udp got %s", k.Proto())
+			t.Fail()
+		}
+		if k.Port() != "6000" {
+			t.Logf("Expected 6000 got %s", k.Port())
+			t.Fail()
+		}
+		b, exists := bindings[k]
+		if !exists {
+			t.Log("Binding does not exist")
+			t.FailNow()
+		}
+		if len(b) != 1 {
+			t.Logf("Expected 1 got %d", len(b))
+			t.FailNow()
+		}
+		s := b[0]
+		if s.HostPort != "" {
+			t.Logf("Expected \"\" got %s", s.HostPort)
+			t.Fail()
+		}
+		if s.HostIp != "192.168.1.100" {
+			t.Fail()
+		}
+	}
+}
+
+func TestGetFullName(t *testing.T) {
+	name, err := getFullName("testing")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if name != "/testing" {
+		t.Fatalf("Expected /testing got %s", name)
+	}
+	if _, err := getFullName(""); err == nil {
+		t.Fatal("Error should not be nil")
+	}
+}

contrib/completion/bash/docker

@@ -426,7 +426,7 @@ _docker_run()
 
 _docker_search()
 {
-	COMPREPLY=( $( compgen -W "-notrunc" -- "$cur" ) )
+	COMPREPLY=( $( compgen -W "-notrunc" "-stars" "-trusted" -- "$cur" ) )
 }
 
 _docker_start()

contrib/desktop-integration/README.txt

@@ -0,0 +1,11 @@
+Desktop Integration
+===================
+
+The ./contrib/desktop-integration contains examples of typical dockerized
+desktop applications.
+
+Examples
+========
+
+* Data container: ./data/Dockerfile creates a data image sharing /data volume
+* Firefox: ./firefox/Dockerfile shows a way to dockerize a common multimedia application

contrib/desktop-integration/data/Dockerfile

@@ -0,0 +1,38 @@
+# VERSION:        0.1
+# DESCRIPTION:    Create data image sharing /data volume
+# AUTHOR:         Daniel Mizyrycki <daniel@dotcloud.com>
+# COMMENTS:
+#   This image is used as base for all data containers.
+#   /data volume is owned by sysadmin.
+# USAGE:
+#   # Download data Dockerfile
+#   wget http://raw.github.com/dotcloud/docker/master/contrib/desktop-integration/data/Dockerfile
+#
+#   # Build data image
+#   docker build -t data -rm .
+#
+#   # Create a data container. (eg: firefox-data)
+#   docker run -name firefox-data data true
+#
+#   # List data from it
+#   docker run -volumes-from firefox-data busybox ls -al /data
+
+docker-version 0.6.5
+
+# Smallest base image, just to launch a container
+from busybox
+maintainer	Daniel Mizyrycki <daniel@docker.com>
+
+# Create a regular user
+run echo 'sysadmin:x:1000:1000::/data:/bin/sh' >> /etc/passwd
+run echo 'sysadmin:x:1000:' >> /etc/group
+
+# Create directory for that user
+run mkdir /data
+run chown sysadmin.sysadmin /data
+
+# Add content to /data. This will keep sysadmin ownership
+run touch /data/init_volume
+
+# Create /data volume
+VOLUME /data

contrib/desktop-integration/firefox/Dockerfile

@@ -0,0 +1,49 @@
+# VERSION:        0.7
+# DESCRIPTION:    Create firefox container with its dependencies
+# AUTHOR:         Daniel Mizyrycki <daniel@dotcloud.com>
+# COMMENTS:
+#   This file describes how to build a Firefox container with all
+#   dependencies installed. It uses native X11 unix socket and alsa
+#   sound devices. Tested on Debian 7.2
+# USAGE:
+#   # Download Firefox Dockerfile
+#   wget http://raw.github.com/dotcloud/docker/master/contrib/desktop-integration/firefox/Dockerfile
+#
+#   # Build firefox image
+#   docker build -t firefox -rm .
+#
+#   # Run stateful data-on-host firefox. For ephemeral, remove -v /data/firefox:/data
+#   docker run -v /data/firefox:/data -v /tmp/.X11-unix:/tmp/.X11-unix \
+#     -v /dev/snd:/dev/snd -lxc-conf='lxc.cgroup.devices.allow = c 116:* rwm' \
+#     -e DISPLAY=unix$DISPLAY firefox
+#
+#   # To run stateful dockerized data containers
+#   docker run -volumes-from firefox-data -v /tmp/.X11-unix:/tmp/.X11-unix \
+#     -v /dev/snd:/dev/snd -lxc-conf='lxc.cgroup.devices.allow = c 116:* rwm' \
+#     -e DISPLAY=unix$DISPLAY firefox
+
+docker-version 0.6.5
+
+# Base docker image
+from tianon/debian:wheezy
+maintainer	Daniel Mizyrycki <daniel@docker.com>
+
+# Install firefox dependencies
+run echo "deb http://ftp.debian.org/debian/ wheezy main contrib" > /etc/apt/sources.list
+run apt-get update
+run DEBIAN_FRONTEND=noninteractive apt-get install -y libXrender1 libasound2 \
+    libdbus-glib-1-2 libgtk2.0-0 libpango1.0-0 libxt6 wget bzip2 sudo
+
+# Install Firefox
+run mkdir /application
+run cd /application; wget -O - \
+    http://ftp.mozilla.org/pub/mozilla.org/firefox/releases/25.0/linux-x86_64/en-US/firefox-25.0.tar.bz2 | tar jx
+
+# create sysadmin account
+run useradd -m -d /data -p saIVpsc0EVTwA sysadmin
+run sed -Ei 's/sudo:x:27:/sudo:x:27:sysadmin/' /etc/group
+run sed -Ei 's/(\%sudo\s+ALL=\(ALL\:ALL\) )ALL/\1 NOPASSWD:ALL/' /etc/sudoers
+
+# Autorun firefox. -no-remote is necessary to create a new container, as firefox
+# appears to communicate with itself through X11.
+cmd ["/bin/sh", "-c", "/usr/bin/sudo -u sysadmin -H -E /application/firefox/firefox -no-remote"]

contrib/init/systemd/docker.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=Easily create lightweight, portable, self-sufficient containers from any application!
+Description=Docker Application Container Engine 
 Documentation=http://docs.docker.io
 Requires=network.target
 After=multi-user.target

contrib/init/sysvinit/docker

@@ -6,43 +6,54 @@
 # Required-Stop:      $syslog $remote_fs
 # Default-Start:      2 3 4 5
 # Default-Stop:       0 1 6
-# Short-Description:  Linux container runtime
-# Description:        Linux container runtime
+# Short-Description:  Create lightweight, portable, self-sufficient containers.
+# Description:
+#  Docker is an open-source project to easily create lightweight, portable,
+#  self-sufficient containers from any application. The same container that a
+#  developer builds and tests on a laptop can run at scale, in production, on
+#  VMs, bare metal, OpenStack clusters, public clouds and more.
 ### END INIT INFO
 
-DOCKER=/usr/bin/docker
-DOCKER_PIDFILE=/var/run/docker.pid
+BASE=$(basename $0)
+
+DOCKER=/usr/bin/$BASE
+DOCKER_PIDFILE=/var/run/$BASE.pid
 DOCKER_OPTS=
 
 PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin
 
-# Check lxc-docker is present
-[ -x $DOCKER ] || (log_failure_msg "docker not present"; exit 1)
-
 # Get lsb functions
 . /lib/lsb/init-functions
 
-if [ -f /etc/default/lxc ]; then
-	. /etc/default/lxc
+if [ -f /etc/default/$BASE ]; then
+	. /etc/default/$BASE
 fi
 
-if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart; then
+# see also init_is_upstart in /lib/lsb/init-functions (which isn't available in Ubuntu 12.04, or we'd use it)
+if [ -x /sbin/initctl ] && /sbin/initctl version 2>/dev/null | /bin/grep -q upstart; then
+	log_failure_msg "Docker is managed via upstart, try using service $BASE $1"
 	exit 1
 fi
 
-check_root_id ()
-{
-	if [ "$(id -u)" != "0" ]; then
-		log_failure_msg "Docker must be run as root"; exit 1
+# Check docker is present
+if [ ! -x $DOCKER ]; then
+	log_failure_msg "$DOCKER not present or not executable"
+	exit 1
+fi
+
+fail_unless_root() {
+	if [ "$(id -u)" != '0' ]; then
+		log_failure_msg "Docker must be run as root"
+		exit 1
 	fi
 }
 
 case "$1" in
 	start)
-		check_root_id || exit 1
-		log_begin_msg "Starting Docker"
+		fail_unless_root
+		log_begin_msg "Starting Docker: $BASE"
 		mount | grep cgroup >/dev/null || mount -t cgroup none /sys/fs/cgroup 2>/dev/null
-		start-stop-daemon --start --background $NO_CLOSE \
+		start-stop-daemon --start --background \
 			--exec "$DOCKER" \
 			--pidfile "$DOCKER_PIDFILE" \
 			-- -d -p "$DOCKER_PIDFILE" \
@@ -51,15 +62,15 @@ case "$1" in
 		;;
 
 	stop)
-		check_root_id || exit 1
-		log_begin_msg "Stopping Docker"
+		fail_unless_root
+		log_begin_msg "Stopping Docker: $BASE"
 		start-stop-daemon --stop \
 			--pidfile "$DOCKER_PIDFILE"
 		log_end_msg $?
 		;;
 
 	restart)
-		check_root_id || exit 1
+		fail_unless_root
 		docker_pid=`cat "$DOCKER_PIDFILE" 2>/dev/null`
 		[ -n "$docker_pid" ] \
 			&& ps -p $docker_pid > /dev/null 2>&1 \
@@ -68,7 +79,7 @@ case "$1" in
 		;;
 
 	force-reload)
-		check_root_id || exit 1
+		fail_unless_root
 		$0 restart
 		;;
 

contrib/init/upstart/docker.conf

@@ -6,5 +6,10 @@ stop on runlevel [!2345]
 respawn
 
 script
-	/usr/bin/docker -d
+	DOCKER=/usr/bin/$UPSTART_JOB
+	DOCKER_OPTS=
+	if [ -f /etc/default/$UPSTART_JOB ]; then
+		. /etc/default/$UPSTART_JOB
+	fi
+	"$DOCKER" -d $DOCKER_OPTS
 end script

contrib/mkimage-debootstrap.sh

@@ -192,7 +192,7 @@ if [ "$justTar" ]; then
 	sudo tar --numeric-owner -caf "$repo" .
 else
 	# create the image (and tag $repo:$suite)
-	sudo tar --numeric-owner -c . | $docker import - $repo $suite
+	sudo tar --numeric-owner -c . | $docker import - $repo:$suite
 	
 	# test the image
 	$docker run -i -t $repo:$suite echo success
@@ -202,25 +202,25 @@ else
 			Debian)
 				if [ "$suite" = "$debianStable" -o "$suite" = 'stable' ] && [ -r etc/debian_version ]; then
 					# tag latest
-					$docker tag $repo:$suite $repo latest
+					$docker tag $repo:$suite $repo:latest
 					
 					if [ -r etc/debian_version ]; then
 						# tag the specific debian release version (which is only reasonable to tag on debian stable)
 						ver=$(cat etc/debian_version)
-						$docker tag $repo:$suite $repo $ver
+						$docker tag $repo:$suite $repo:$ver
 					fi
 				fi
 				;;
 			Ubuntu)
 				if [ "$suite" = "$ubuntuLatestLTS" ]; then
 					# tag latest
-					$docker tag $repo:$suite $repo latest
+					$docker tag $repo:$suite $repo:latest
 				fi
 				if [ -r etc/lsb-release ]; then
 					lsbRelease="$(. etc/lsb-release && echo "$DISTRIB_RELEASE")"
 					if [ "$lsbRelease" ]; then
 						# tag specific Ubuntu version number, if available (12.04, etc.)
-						$docker tag $repo:$suite $repo $lsbRelease
+						$docker tag $repo:$suite $repo:$lsbRelease
 					fi
 				fi
 				;;

contrib/vagrant-docker/README.md

@@ -1,3 +1,19 @@
-# Vagrant-docker
+# Vagrant integration
 
-This is a placeholder for the official vagrant-docker, a plugin for Vagrant (http://vagrantup.com) which exposes Docker as a provider.
+Currently there are at least 4 different projects that we are aware of that deals
+with integration with [Vagrant](http://vagrantup.com/) at different levels. One
+approach is to use Docker as a [provisioner](http://docs.vagrantup.com/v2/provisioning/index.html)
+which means you can create containers and pull base images on VMs using Docker's
+CLI and the other is to use Docker as a [provider](http://docs.vagrantup.com/v2/providers/index.html),
+meaning you can use Vagrant to control Docker containers.
+
+
+### Provisioners
+
+* [Vocker](https://github.com/fgrehm/vocker)
+* [Ventriloquist](https://github.com/fgrehm/ventriloquist)
+
+### Providers
+
+* [docker-provider](https://github.com/fgrehm/docker-provider)
+* [vagrant-shell](https://github.com/destructuring/vagrant-shell)

docker/docker.go

@@ -4,16 +4,12 @@ import (
 	"flag"
 	"fmt"
 	"github.com/dotcloud/docker"
+	"github.com/dotcloud/docker/engine"
 	"github.com/dotcloud/docker/sysinit"
 	"github.com/dotcloud/docker/utils"
-	"io/ioutil"
 	"log"
-	"net"
 	"os"
-	"os/signal"
-	"strconv"
 	"strings"
-	"syscall"
 )
 
 var (
@@ -34,7 +30,7 @@ func main() {
 	flAutoRestart := flag.Bool("r", true, "Restart previously running containers")
 	bridgeName := flag.String("b", "", "Attach containers to a pre-existing network bridge. Use 'none' to disable container networking")
 	pidfile := flag.String("p", "/var/run/docker.pid", "File containing process PID")
-	flGraphPath := flag.String("g", "/var/lib/docker", "Path to graph storage base dir.")
+	flRoot := flag.String("g", "/var/lib/docker", "Path to use as the root of the docker runtime.")
 	flEnableCors := flag.Bool("api-enable-cors", false, "Enable CORS requests in the remote api.")
 	flDns := flag.String("dns", "", "Set custom dns servers")
 	flHosts := utils.ListOpts{fmt.Sprintf("unix://%s", docker.DEFAULTUNIXSOCKET)}
@@ -61,10 +57,6 @@ func main() {
 		}
 	}
 
-	bridge := docker.DefaultNetworkBridge
-	if *bridgeName != "" {
-		bridge = *bridgeName
-	}
 	if *flDebug {
 		os.Setenv("DEBUG", "1")
 	}
@@ -75,26 +67,28 @@ func main() {
 			flag.Usage()
 			return
 		}
-		var dns []string
-		if *flDns != "" {
-			dns = []string{*flDns}
+		eng, err := engine.New(*flRoot)
+		if err != nil {
+			log.Fatal(err)
 		}
-
-		ip := net.ParseIP(*flDefaultIp)
-
-		config := &docker.DaemonConfig{
-			Pidfile:                     *pidfile,
-			GraphPath:                   *flGraphPath,
-			AutoRestart:                 *flAutoRestart,
-			EnableCors:                  *flEnableCors,
-			Dns:                         dns,
-			EnableIptables:              *flEnableIptables,
-			BridgeIface:                 bridge,
-			ProtoAddresses:              flHosts,
-			DefaultIp:                   ip,
-			InterContainerCommunication: *flInterContainerComm,
+		// Load plugin: httpapi
+		job := eng.Job("initapi")
+		job.Setenv("Pidfile", *pidfile)
+		job.Setenv("Root", *flRoot)
+		job.SetenvBool("AutoRestart", *flAutoRestart)
+		job.SetenvBool("EnableCors", *flEnableCors)
+		job.Setenv("Dns", *flDns)
+		job.SetenvBool("EnableIptables", *flEnableIptables)
+		job.Setenv("BridgeIface", *bridgeName)
+		job.Setenv("DefaultIp", *flDefaultIp)
+		job.SetenvBool("InterContainerCommunication", *flInterContainerComm)
+		if err := job.Run(); err != nil {
+			log.Fatal(err)
 		}
-		if err := daemon(config); err != nil {
+		// Serve api
+		job = eng.Job("serveapi", flHosts...)
+		job.SetenvBool("Logging", true)
+		if err := job.Run(); err != nil {
 			log.Fatal(err)
 		}
 	} else {
@@ -114,79 +108,3 @@ func main() {
 func showVersion() {
 	fmt.Printf("Docker version %s, build %s\n", VERSION, GITCOMMIT)
 }
-
-func createPidFile(pidfile string) error {
-	if pidString, err := ioutil.ReadFile(pidfile); err == nil {
-		pid, err := strconv.Atoi(string(pidString))
-		if err == nil {
-			if _, err := os.Stat(fmt.Sprintf("/proc/%d/", pid)); err == nil {
-				return fmt.Errorf("pid file found, ensure docker is not running or delete %s", pidfile)
-			}
-		}
-	}
-
-	file, err := os.Create(pidfile)
-	if err != nil {
-		return err
-	}
-
-	defer file.Close()
-
-	_, err = fmt.Fprintf(file, "%d", os.Getpid())
-	return err
-}
-
-func removePidFile(pidfile string) {
-	if err := os.Remove(pidfile); err != nil {
-		log.Printf("Error removing %s: %s", pidfile, err)
-	}
-}
-
-func daemon(config *docker.DaemonConfig) error {
-	if err := createPidFile(config.Pidfile); err != nil {
-		log.Fatal(err)
-	}
-	defer removePidFile(config.Pidfile)
-
-	server, err := docker.NewServer(config)
-	if err != nil {
-		return err
-	}
-	defer server.Close()
-
-	c := make(chan os.Signal, 1)
-	signal.Notify(c, os.Interrupt, os.Kill, os.Signal(syscall.SIGTERM))
-	go func() {
-		sig := <-c
-		log.Printf("Received signal '%v', exiting\n", sig)
-		server.Close()
-		removePidFile(config.Pidfile)
-		os.Exit(0)
-	}()
-
-	chErrors := make(chan error, len(config.ProtoAddresses))
-	for _, protoAddr := range config.ProtoAddresses {
-		protoAddrParts := strings.SplitN(protoAddr, "://", 2)
-		if protoAddrParts[0] == "unix" {
-			syscall.Unlink(protoAddrParts[1])
-		} else if protoAddrParts[0] == "tcp" {
-			if !strings.HasPrefix(protoAddrParts[1], "127.0.0.1") {
-				log.Println("/!\\ DON'T BIND ON ANOTHER IP ADDRESS THAN 127.0.0.1 IF YOU DON'T KNOW WHAT YOU'RE DOING /!\\")
-			}
-		} else {
-			server.Close()
-			removePidFile(config.Pidfile)
-			log.Fatal("Invalid protocol format.")
-		}
-		go func() {
-			chErrors <- docker.ListenAndServe(protoAddrParts[0], protoAddrParts[1], server, true)
-		}()
-	}
-	for i := 0; i < len(config.ProtoAddresses); i += 1 {
-		err := <-chErrors
-		if err != nil {
-			return err
-		}
-	}
-	return nil
-}

docs/Makefile

@@ -31,7 +31,7 @@ help:
 #	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 #	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
 #	@echo "  text       to make text files"
-#	@echo "  man        to make manual pages"
+	@echo "  man        to make a manual page"
 #	@echo "  texinfo    to make Texinfo files"
 #	@echo "  info       to make Texinfo files and run them through makeinfo"
 #	@echo "  gettext    to make PO message catalogs"

docs/requirements.txt

@@ -1,2 +1,2 @@
 Sphinx==1.1.3
-sphinxcontrib-httpdomain==1.1.8
+sphinxcontrib-httpdomain==1.1.9

docs/sources/api/docker_remote_api.rst

@@ -26,14 +26,118 @@ Docker Remote API
 2. Versions
 ===========
 
-The current version of the API is 1.6
+The current version of the API is 1.7
 
 Calling /images/<name>/insert is the same as calling
-/v1.6/images/<name>/insert
+/v1.7/images/<name>/insert
 
 You can still call an old version of the api using
 /v1.0/images/<name>/insert
 
+v1.7
+****
+
+Full Documentation
+------------------
+
+:doc:`docker_remote_api_v1.7`
+
+What's new
+----------
+
+.. http:get:: /images/json
+
+   The format of the json returned from this uri changed.  Instead of an entry
+   for each repo/tag on an image, each image is only represented once, with a
+   nested attribute indicating the repo/tags that apply to that image.
+
+   Instead of:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      [
+        {
+          "VirtualSize": 131506275,
+          "Size": 131506275,
+          "Created": 1365714795,
+          "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
+          "Tag": "12.04",
+          "Repository": "ubuntu"
+        },
+        {
+          "VirtualSize": 131506275,
+          "Size": 131506275,
+          "Created": 1365714795,
+          "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
+          "Tag": "latest",
+          "Repository": "ubuntu"
+        },
+        {
+          "VirtualSize": 131506275,
+          "Size": 131506275,
+          "Created": 1365714795,
+          "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
+          "Tag": "precise",
+          "Repository": "ubuntu"
+        },
+        {
+          "VirtualSize": 180116135,
+          "Size": 24653,
+          "Created": 1364102658,
+          "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
+          "Tag": "12.10",
+          "Repository": "ubuntu"
+        },
+        {
+          "VirtualSize": 180116135,
+          "Size": 24653,
+          "Created": 1364102658,
+          "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
+          "Tag": "quantal",
+          "Repository": "ubuntu"
+        }
+      ]
+
+   The returned json looks like this:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+      
+      [
+        {
+           "RepoTag": [
+             "ubuntu:12.04",
+             "ubuntu:precise",
+             "ubuntu:latest"
+           ],
+           "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
+           "Created": 1365714795,
+           "Size": 131506275,
+           "VirtualSize": 131506275
+        },
+        {
+           "RepoTag": [
+             "ubuntu:12.10",
+             "ubuntu:quantal"
+           ],
+           "ParentId": "27cf784147099545",
+           "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
+           "Created": 1364102658,
+           "Size": 24653,
+           "VirtualSize": 180116135
+        }
+      ]
+
+.. http:get:: /images/viz
+
+   This URI no longer exists.  The ``images -viz`` output is now generated in
+   the client, using the ``/images/json`` data.
+
 v1.6
 ****
 

docs/sources/api/docker_remote_api_v1.4.rst

@@ -943,36 +943,36 @@ Build an image from Dockerfile via stdin
 
 .. http:post:: /build
 
-   Build an image from Dockerfile via stdin
+    Build an image from Dockerfile via stdin
 
-   **Example request**:
+    **Example request**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
-      POST /build HTTP/1.1
+        POST /build HTTP/1.1
 
-      {{ STREAM }}
+        {{ STREAM }}
 
-   **Example response**:
+    **Example response**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
-      HTTP/1.1 200 OK
+        HTTP/1.1 200 OK
 
-      {{ STREAM }}
+        {{ STREAM }}
 
 
-       The stream must be a tar archive compressed with one of the following algorithms:
-       identity (no compression), gzip, bzip2, xz. The archive must include a file called
-       `Dockerfile` at its root. It may include any number of other files, which will be
-       accessible in the build context (See the ADD build command).
+    The stream must be a tar archive compressed with one of the following algorithms:
+    identity (no compression), gzip, bzip2, xz. The archive must include a file called
+    `Dockerfile` at its root. It may include any number of other files, which will be
+    accessible in the build context (See the ADD build command).
 
-       The Content-type header should be set to "application/tar".
+    The Content-type header should be set to "application/tar".
 
-	:query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
-	:query q: suppress verbose build output
+    :query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
+    :query q: suppress verbose build output
     :query nocache: do not use the cache when building the image
-	:statuscode 200: no error
+    :statuscode 200: no error
     :statuscode 500: server error
 
 
@@ -1069,8 +1069,8 @@ Show the docker version information
 		"GoVersion":"go1.0.3"
 	   }
 
-        :statuscode 200: no error
-	:statuscode 500: server error
+    :statuscode 200: no error
+    :statuscode 500: server error
 
 
 Create a new image from a container's changes

docs/sources/api/docker_remote_api_v1.6.rst

@@ -121,8 +121,7 @@ Create a container
 		"AttachStdin":false,
 		"AttachStdout":true,
 		"AttachStderr":true,
-		"PortSpecs":null,
-		"Privileged": false,
+		"ExposedPorts":{},
 		"Tty":false,
 		"OpenStdin":false,
 		"StdinOnce":false,
@@ -135,7 +134,6 @@ Create a container
 		"Volumes":{},
 		"VolumesFrom":"",
 		"WorkingDir":""
-
 	   }
 	   
 	**Example response**:
@@ -157,6 +155,57 @@ Create a container
 	:statuscode 406: impossible to attach (container not running)
 	:statuscode 500: server error
 
+	**More Complex Example request, in 2 steps.**
+	**First, use create to expose a Private Port, which can be bound back to a Public Port at startup**:
+
+	.. sourcecode:: http
+
+	   POST /containers/create HTTP/1.1
+	   Content-Type: application/json
+
+	   {
+		"Cmd":[
+			"/usr/sbin/sshd","-D"
+		],
+		"Image":"image-with-sshd",
+		"ExposedPorts":{"22/tcp":{}}
+		}
+
+	**Example response**:
+
+	.. sourcecode:: http
+
+	   HTTP/1.1 201 OK
+	   Content-Type: application/json
+
+	   {
+		"Id":"e90e34656806"
+		"Warnings":[]
+	   }
+
+	**Second, start (using the ID returned above) the image we just created, mapping the ssh port 22 to something on the host**:
+
+	.. sourcecode:: http
+
+	   POST /containers/e90e34656806/start HTTP/1.1
+	   Content-Type: application/json
+
+	   {
+		"PortBindings": { "22/tcp": [{ "HostPort": "11022" }]} 
+		}
+
+	**Example response**:
+
+	.. sourcecode:: http
+
+		HTTP/1.1 204 No Content
+		Content-Type: text/plain; charset=utf-8
+		Content-Length: 0
+
+	**Now you can ssh into your new container on port 11022.**
+
+
+
 
 Inspect a container
 *******************
@@ -191,7 +240,7 @@ Inspect a container
 				"AttachStdin": false,
 				"AttachStdout": true,
 				"AttachStderr": true,
-				"PortSpecs": null,
+				"ExposedPorts": {},
 				"Tty": false,
 				"OpenStdin": false,
 				"StdinOnce": false,
@@ -362,7 +411,12 @@ Start a container
 
            {
                 "Binds":["/tmp:/tmp"],
-                "LxcConf":{"lxc.utsname":"docker"}
+                "LxcConf":{"lxc.utsname":"docker"},
+                "ContainerIDFile": "",
+                "Privileged": false,
+                "PortBindings": {"22/tcp": [{HostIp:"", HostPort:""}]},
+                "Links": [],
+                "PublishAllPorts": false
            }
 
         **Example response**:
@@ -795,7 +849,7 @@ Inspect an image
 				"AttachStdin":false,
 				"AttachStdout":false,
 				"AttachStderr":false,
-				"PortSpecs":null,
+				"ExposedPorts":{},
 				"Tty":true,
 				"OpenStdin":true,
 				"StdinOnce":false,
@@ -995,36 +1049,36 @@ Build an image from Dockerfile via stdin
 
 .. http:post:: /build
 
-   Build an image from Dockerfile via stdin
+    Build an image from Dockerfile via stdin
 
-   **Example request**:
+    **Example request**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
-      POST /build HTTP/1.1
+        POST /build HTTP/1.1
 
-      {{ STREAM }}
+        {{ STREAM }}
 
-   **Example response**:
+    **Example response**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
-      HTTP/1.1 200 OK
+        HTTP/1.1 200 OK
 
-      {{ STREAM }}
+        {{ STREAM }}
 
 
-       The stream must be a tar archive compressed with one of the following algorithms:
-       identity (no compression), gzip, bzip2, xz. The archive must include a file called
-       `Dockerfile` at its root. It may include any number of other files, which will be
-       accessible in the build context (See the ADD build command).
+    The stream must be a tar archive compressed with one of the following algorithms:
+    identity (no compression), gzip, bzip2, xz. The archive must include a file called
+    `Dockerfile` at its root. It may include any number of other files, which will be
+    accessible in the build context (See the ADD build command).
+    
+    The Content-type header should be set to "application/tar".
 
-       The Content-type header should be set to "application/tar".
-
-	:query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
-	:query q: suppress verbose build output
+    :query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
+    :query q: suppress verbose build output
     :query nocache: do not use the cache when building the image
-	:statuscode 200: no error
+    :statuscode 200: no error
     :statuscode 500: server error
 
 
@@ -1141,7 +1195,7 @@ Create a new image from a container's changes
        
        {
            "Cmd": ["cat", "/world"],
-           "PortSpecs":["22"]
+           "ExposedPorts":{"22/tcp":{}}
        }
 
     **Example response**:

docs/sources/api/remote_api_client_libraries.rst

@@ -1,4 +1,4 @@
-:title: Registry API
+:title: Remote API Client Libraries
 :description: Various client libraries available to use with the Docker remote API
 :keywords: API, Docker, index, registry, REST, documentation, clients, Python, Ruby, Javascript, Erlang, Go
 
@@ -12,26 +12,28 @@ compatibility. Please file issues with the library owners.  If you
 find more library implementations, please list them in Docker doc bugs
 and we will add the libraries here.
 
-+----------------------+----------------+--------------------------------------------+
-| Language/Framework   | Name           | Repository                                 |
-+======================+================+============================================+
-| Python               | docker-py      | https://github.com/dotcloud/docker-py      |
-+----------------------+----------------+--------------------------------------------+
-| Ruby                 | docker-client  | https://github.com/geku/docker-client      |
-+----------------------+----------------+--------------------------------------------+
-| Ruby                 | docker-api     | https://github.com/swipely/docker-api      |
-+----------------------+----------------+--------------------------------------------+
-| Javascript (NodeJS)  | docker.io      | https://github.com/appersonlabs/docker.io  |
-|                      |                | Install via NPM: `npm install docker.io`   |
-+----------------------+----------------+--------------------------------------------+
-| Javascript           | docker-js      | https://github.com/dgoujard/docker-js      |
-+----------------------+----------------+--------------------------------------------+
-| Javascript (Angular) | dockerui       | https://github.com/crosbymichael/dockerui  |
-| **WebUI**            |                |                                            |
-+----------------------+----------------+--------------------------------------------+
-| Java                 | docker-java    | https://github.com/kpelykh/docker-java     |
-+----------------------+----------------+--------------------------------------------+
-| Erlang               | erldocker      | https://github.com/proger/erldocker        |
-+----------------------+----------------+--------------------------------------------+
-| Go                   | go-dockerclient| https://github.com/fsouza/go-dockerclient  |
-+----------------------+----------------+--------------------------------------------+
++----------------------+----------------+--------------------------------------------+----------+
+| Language/Framework   | Name           | Repository                                 | Status   |
++======================+================+============================================+==========+
+| Python               | docker-py      | https://github.com/dotcloud/docker-py      | Active   |
++----------------------+----------------+--------------------------------------------+----------+
+| Ruby                 | docker-client  | https://github.com/geku/docker-client      | Outdated |
++----------------------+----------------+--------------------------------------------+----------+
+| Ruby                 | docker-api     | https://github.com/swipely/docker-api      | Active   |
++----------------------+----------------+--------------------------------------------+----------+
+| Javascript (NodeJS)  | docker.io      | https://github.com/appersonlabs/docker.io  | Active   |
+|                      |                | Install via NPM: `npm install docker.io`   |          |
++----------------------+----------------+--------------------------------------------+----------+
+| Javascript           | docker-js      | https://github.com/dgoujard/docker-js      | Active   |
++----------------------+----------------+--------------------------------------------+----------+
+| Javascript (Angular) | dockerui       | https://github.com/crosbymichael/dockerui  | Active   |
+| **WebUI**            |                |                                            |          |
++----------------------+----------------+--------------------------------------------+----------+
+| Java                 | docker-java    | https://github.com/kpelykh/docker-java     | Active   |
++----------------------+----------------+--------------------------------------------+----------+
+| Erlang               | erldocker      | https://github.com/proger/erldocker        | Active   |
++----------------------+----------------+--------------------------------------------+----------+
+| Go                   | go-dockerclient| https://github.com/fsouza/go-dockerclient  | Active   |
++----------------------+----------------+--------------------------------------------+----------+
+| PHP                  | Alvine         | http://pear.alvine.io/ (alpha)             | Active   |
++----------------------+----------------+--------------------------------------------+----------+

docs/sources/commandline/cli.rst

@@ -41,7 +41,7 @@ To stop a container, use ``docker stop``
 To kill the container, use ``docker kill``
 
 .. _cli_attach_examples:
- 
+
 Examples:
 ~~~~~~~~~
 
@@ -55,8 +55,8 @@ Examples:
      Mem:    373572k total,   355560k used,    18012k free,    27872k buffers
      Swap:   786428k total,        0k used,   786428k free,   221740k cached
 
-     PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND            
-      1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top                
+     PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
+      1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top
 
       top - 02:05:55 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
       Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
@@ -64,8 +64,8 @@ Examples:
       Mem:    373572k total,   355244k used,    18328k free,    27872k buffers
       Swap:   786428k total,        0k used,   786428k free,   221776k cached
 
-        PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND            
-	    1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top                
+        PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
+	    1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
 
 
       top - 02:05:58 up  3:06,  0 users,  load average: 0.01, 0.02, 0.05
@@ -74,9 +74,9 @@ Examples:
       Mem:    373572k total,   355780k used,    17792k free,    27880k buffers
       Swap:   786428k total,        0k used,   786428k free,   221776k cached
 
-      PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND            
-           1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top                
-     ^C$ 
+      PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
+           1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
+     ^C$
      $ sudo docker stop $ID
 
 .. _cli_build:
@@ -88,31 +88,65 @@ Examples:
 
     Usage: docker build [OPTIONS] PATH | URL | -
     Build a new container image from the source code at PATH
-      -t="": Repository name (and optionally a tag) to be applied to the resulting image in case of success.
+      -t="": Repository name (and optionally a tag) to be applied 
+             to the resulting image in case of success.
       -q=false: Suppress verbose build output.
       -no-cache: Do not use the cache when building the image.
       -rm: Remove intermediate containers after a successful build
-    When a single Dockerfile is given as URL, then no context is set. When a git repository is set as URL, the repository is used as context
+
+The files at PATH or URL are called the "context" of the build. The
+build process may refer to any of the files in the context, for
+example when using an :ref:`ADD <dockerfile_add>` instruction.  When a
+single ``Dockerfile`` is given as URL, then no context is set.  When a
+git repository is set as URL, then the repository is used as the
+context
 
 .. _cli_build_examples:
 
+.. seealso:: :ref:`dockerbuilder`.
+
 Examples:
 ~~~~~~~~~
 
 .. code-block:: bash
 
     sudo docker build .
+    Uploading context 10240 bytes
+    Step 1 : FROM busybox
+    Pulling repository busybox
+     ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
+    Step 2 : RUN ls -lh /
+     ---> Running in 9c9e81692ae9
+    total 24
+    drwxr-xr-x    2 root     root        4.0K Mar 12  2013 bin
+    drwxr-xr-x    5 root     root        4.0K Oct 19 00:19 dev
+    drwxr-xr-x    2 root     root        4.0K Oct 19 00:19 etc
+    drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 lib
+    lrwxrwxrwx    1 root     root           3 Mar 12  2013 lib64 -> lib
+    dr-xr-xr-x  116 root     root           0 Nov 15 23:34 proc
+    lrwxrwxrwx    1 root     root           3 Mar 12  2013 sbin -> bin
+    dr-xr-xr-x   13 root     root           0 Nov 15 23:34 sys
+    drwxr-xr-x    2 root     root        4.0K Mar 12  2013 tmp
+    drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 usr
+     ---> b35f4035db3f
+    Step 3 : CMD echo Hello World
+     ---> Running in 02071fceb21b
+     ---> f52f38b7823e
+    Successfully built f52f38b7823e
 
-This will read the ``Dockerfile`` from the current directory. It will
-also send any other files and directories found in the current
-directory to the ``docker`` daemon.
+This example specifies that the PATH is ``.``, and so all the files in
+the local directory get tar'd and sent to the Docker daemon.  The PATH
+specifies where to find the files for the "context" of the build on
+the Docker daemon. Remember that the daemon could be running on a
+remote machine and that no parsing of the Dockerfile happens at the
+client side (where you're running ``docker build``). That means that
+*all* the files at PATH get sent, not just the ones listed to
+:ref:`ADD <dockerfile_add>` in the ``Dockerfile``.
+
+The transfer of context from the local machine to the Docker daemon is
+what the ``docker`` client means when you see the "Uploading context"
+message.
 
-The contents of this directory would be used by ``ADD`` commands found
-within the ``Dockerfile``.  This will send a lot of data to the
-``docker`` daemon if the current directory contains a lot of data.  If
-the absolute path is provided instead of ``.`` then only the files and
-directories required by the ADD commands from the ``Dockerfile`` will be
-added to the context and transferred to the ``docker`` daemon.
 
 .. code-block:: bash
 
@@ -129,17 +163,15 @@ tag will be ``2.0``
 
 This will read a ``Dockerfile`` from *stdin* without context. Due to
 the lack of a context, no contents of any local directory will be sent
-to the ``docker`` daemon.  ``ADD`` doesn't work when running in this
-mode because the absence of the context provides no source files to
-copy to the container.
-
+to the ``docker`` daemon.  Since there is no context, a Dockerfile
+``ADD`` only works if it refers to a remote URL.
 
 .. code-block:: bash
 
     sudo docker build github.com/creack/docker-firefox
 
-This will clone the Github repository and use it as context. The
-``Dockerfile`` at the root of the repository is used as
+This will clone the Github repository and use the cloned repository as
+context. The ``Dockerfile`` at the root of the repository is used as
 ``Dockerfile``.  Note that you can specify an arbitrary git repository
 by using the ``git://`` schema.
 
@@ -151,16 +183,35 @@ by using the ``git://`` schema.
 
 ::
 
-    Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY [TAG]]
+    Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]
 
     Create a new image from a container's changes
 
       -m="": Commit message
       -author="": Author (eg. "John Hannibal Smith <hannibal@a-team.com>"
-      -run="": Configuration to be applied when the image is launched with `docker run`. 
-               (ex: '{"Cmd": ["cat", "/world"], "PortSpecs": ["22"]}')
+      -run="": Configuration to be applied when the image is launched with `docker run`.
+               (ex: -run='{"Cmd": ["cat", "/world"], "PortSpecs": ["22"]}')
 
-Full -run example (multiline is ok within a single quote ``'``)
+Simple commit of an existing container
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+	$ docker ps
+	ID                  IMAGE               COMMAND             CREATED             STATUS              PORTS
+	c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                             
+	197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                             
+	$ docker commit c3f279d17e0a  SvenDowideit/testimage:version3
+	f5283438590d
+	$ docker images | head
+	REPOSITORY                        TAG                 ID                  CREATED             SIZE
+	SvenDowideit/testimage            version3            f5283438590d        16 seconds ago      204.2 MB (virtual 335.7 MB)
+	
+
+Full -run example
+.................
+
+(multiline is ok within a single quote ``'``)
 
 ::
 
@@ -201,10 +252,15 @@ Full -run example (multiline is ok within a single quote ``'``)
 
 ::
 
-    Usage: docker cp CONTAINER:RESOURCE HOSTPATH
+    Usage: docker cp CONTAINER:PATH HOSTPATH
 
     Copy files/folders from the containers filesystem to the host
     path.  Paths are relative to the root of the filesystem.
+    
+.. code-block:: bash
+
+    $ sudo docker cp 7bb0e258aefe:/etc/debian_version .
+    $ sudo docker cp blue_frog:/etc/hosts .
 
 .. _cli_diff:
 
@@ -213,9 +269,33 @@ Full -run example (multiline is ok within a single quote ``'``)
 
 ::
 
-    Usage: docker diff CONTAINER [OPTIONS]
+    Usage: docker diff CONTAINER
+ 
+    List the changed files and directories in a container's filesystem
 
-    Inspect changes on a container's filesystem
+There are 3 events that are listed in the 'diff':
+
+1. ```A``` - Add
+2. ```D``` - Delete
+3. ```C``` - Change
+
+for example:
+
+.. code-block:: bash
+
+	$ sudo docker diff 7bb0e258aefe
+
+	C /dev
+	A /dev/kmsg
+	C /etc
+	A /etc/mtab
+	A /go
+	A /go/src
+	A /go/src/github.com
+	A /go/src/github.com/dotcloud
+	A /go/src/github.com/dotcloud/docker
+	A /go/src/github.com/dotcloud/docker/.git
+	....
 
 .. _cli_events:
 
@@ -227,6 +307,9 @@ Full -run example (multiline is ok within a single quote ``'``)
     Usage: docker events
 
     Get real time events from the server
+    
+    -since="": Show previously created events and then stream.
+               (either seconds since epoch, or date string as below)
 
 .. _cli_events_example:
 
@@ -239,7 +322,7 @@ Shell 1: Listening for events
 .............................
 
 .. code-block:: bash
-    
+
     $ sudo docker events
 
 Shell 2: Start and Stop a Container
@@ -259,6 +342,23 @@ Shell 1: (Again .. now showing events)
     [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
     [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
 
+Show events in the past from a specified time
+.............................................
+
+.. code-block:: bash
+
+    $ sudo docker events -since 1378216169
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
+
+    $ sudo docker events -since '2013-09-03'
+    [2013-09-03 15:49:26 +0200 CEST] 4386fb97867d: (from 12de384bfb10) start
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
+
+    $ sudo docker events -since '2013-09-03 15:49:29 +0200 CEST'
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die
+    [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop
 
 .. _cli_export:
 
@@ -282,6 +382,43 @@ Shell 1: (Again .. now showing events)
 
     Show the history of an image
 
+      -notrunc=false: Don't truncate output
+      -q=false: only show numeric IDs
+
+To see how the docker:latest image was built:
+
+.. code-block:: bash
+
+	$ docker history docker
+	ID                  CREATED             CREATED BY
+	docker:latest       19 hours ago        /bin/sh -c #(nop) ADD . in /go/src/github.com/dotcloud/docker
+	cf5f2467662d        2 weeks ago         /bin/sh -c #(nop) ENTRYPOINT ["hack/dind"]
+	3538fbe372bf        2 weeks ago         /bin/sh -c #(nop) WORKDIR /go/src/github.com/dotcloud/docker
+	7450f65072e5        2 weeks ago         /bin/sh -c #(nop) VOLUME /var/lib/docker
+	b79d62b97328        2 weeks ago         /bin/sh -c apt-get install -y -q lxc
+	36714852a550        2 weeks ago         /bin/sh -c apt-get install -y -q iptables
+	8c4c706df1d6        2 weeks ago         /bin/sh -c /bin/echo -e '[default]\naccess_key=$AWS_ACCESS_KEY\nsecret_key=$AWS_SECRET_KEYn' > /.s3cfg
+	b89989433c48        2 weeks ago         /bin/sh -c pip install python-magic
+	a23e640d85b5        2 weeks ago         /bin/sh -c pip install s3cmd
+	41f54fec7e79        2 weeks ago         /bin/sh -c apt-get install -y -q python-pip
+	d9bc04add907        2 weeks ago         /bin/sh -c apt-get install -y -q reprepro dpkg-sig
+	e74f4760fa70        2 weeks ago         /bin/sh -c gem install --no-rdoc --no-ri fpm
+	1e43224726eb        2 weeks ago         /bin/sh -c apt-get install -y -q ruby1.9.3 rubygems libffi-dev
+	460953ae9d7f        2 weeks ago         /bin/sh -c #(nop) ENV GOPATH=/go:/go/src/github.com/dotcloud/docker/vendor
+	8b63eb1d666b        2 weeks ago         /bin/sh -c #(nop) ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/goroot/bin
+	3087f3bcedf2        2 weeks ago         /bin/sh -c #(nop) ENV GOROOT=/goroot
+	635840d198e5        2 weeks ago         /bin/sh -c cd /goroot/src && ./make.bash
+	439f4a0592ba        2 weeks ago         /bin/sh -c curl -s https://go.googlecode.com/files/go1.1.2.src.tar.gz | tar -v -C / -xz && mv /go /goroot
+	13967ed36e93        2 weeks ago         /bin/sh -c #(nop) ENV CGO_ENABLED=0
+	bf7424458437        2 weeks ago         /bin/sh -c apt-get install -y -q build-essential
+	a89ec997c3bf        2 weeks ago         /bin/sh -c apt-get install -y -q mercurial
+	b9f165c6e749        2 weeks ago         /bin/sh -c apt-get install -y -q git
+	17a64374afa7        2 weeks ago         /bin/sh -c apt-get install -y -q curl
+	d5e85dc5b1d8        2 weeks ago         /bin/sh -c apt-get update
+	13e642467c11        2 weeks ago         /bin/sh -c echo 'deb http://archive.ubuntu.com/ubuntu precise main universe' > /etc/apt/sources.list
+	ae6dde92a94e        2 weeks ago         /bin/sh -c #(nop) MAINTAINER Solomon Hykes <solomon@dotcloud.com>
+	ubuntu:12.04        6 months ago 
+
 .. _cli_images:
 
 ``images``
@@ -293,20 +430,86 @@ Shell 1: (Again .. now showing events)
 
     List images
 
-      -a=false: show all images
+      -a=false: show all images (by default filter out the intermediate images used to build)
+      -notrunc=false: Don't truncate output
       -q=false: only show numeric IDs
-      -viz=false: output in graphviz format
+      -tree=false: output graph in tree format
+      -viz=false: output graph in graphviz format
+      
+Listing the most recently created images
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+	$ sudo docker images | head
+	REPOSITORY                    TAG                 IMAGE ID            CREATED             SIZE
+	<none>                        <none>              77af4d6b9913        19 hours ago        30.53 MB (virtual 1.089 GB)
+	committest                    latest              b6fa739cedf5        19 hours ago        30.53 MB (virtual 1.089 GB)
+	<none>                        <none>              78a85c484f71        19 hours ago        30.53 MB (virtual 1.089 GB)
+	docker                        latest              30557a29d5ab        20 hours ago        30.53 MB (virtual 1.089 GB)
+	<none>                        <none>              0124422dd9f9        20 hours ago        30.53 MB (virtual 1.089 GB)
+	<none>                        <none>              18ad6fad3402        22 hours ago        23.68 MB (virtual 1.082 GB)
+	<none>                        <none>              f9f1e26352f0        23 hours ago        30.46 MB (virtual 1.089 GB)
+	tryout                        latest              2629d1fa0b81        23 hours ago        16.4 kB (virtual 131.5 MB)
+	<none>                        <none>              5ed6274db6ce        24 hours ago        30.44 MB (virtual 1.089 GB)
+
+Listing the full length image IDs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+	$ sudo docker images -notrunc | head
+	REPOSITORY                    TAG                 IMAGE ID                                                           CREATED             SIZE
+	<none>                        <none>              77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182   19 hours ago        30.53 MB (virtual 1.089 GB)
+	committest                    latest              b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f   19 hours ago        30.53 MB (virtual 1.089 GB)
+	<none>                        <none>              78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921   19 hours ago        30.53 MB (virtual 1.089 GB)
+	docker                        latest              30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4   20 hours ago        30.53 MB (virtual 1.089 GB)
+	<none>                        <none>              0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5   20 hours ago        30.53 MB (virtual 1.089 GB)
+	<none>                        <none>              18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b   22 hours ago        23.68 MB (virtual 1.082 GB)
+	<none>                        <none>              f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a   23 hours ago        30.46 MB (virtual 1.089 GB)
+	tryout                        latest              2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074   23 hours ago        16.4 kB (virtual 131.5 MB)
+	<none>                        <none>              5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df   24 hours ago        30.44 MB (virtual 1.089 GB)
 
 Displaying images visually
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-::
+.. code-block:: bash
 
-    sudo docker images -viz | dot -Tpng -o docker.png
+    $ sudo docker images -viz | dot -Tpng -o docker.png
 
 .. image:: docker_images.gif
    :alt: Example inheritance graph of Docker images.
 
+
+Displaying image hierarchy
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    $ sudo docker images -tree
+
+    |─8dbd9e392a96 Size: 131.5 MB (virtual 131.5 MB) Tags: ubuntu:12.04,ubuntu:latest,ubuntu:precise
+    └─27cf78414709 Size: 180.1 MB (virtual 180.1 MB)
+      └─b750fe79269d Size: 24.65 kB (virtual 180.1 MB) Tags: ubuntu:12.10,ubuntu:quantal
+        |─f98de3b610d5 Size: 12.29 kB (virtual 180.1 MB)
+        | └─7da80deb7dbf Size: 16.38 kB (virtual 180.1 MB)
+        |   └─65ed2fee0a34 Size: 20.66 kB (virtual 180.2 MB)
+        |     └─a2b9ea53dddc Size: 819.7 MB (virtual 999.8 MB)
+        |       └─a29b932eaba8 Size: 28.67 kB (virtual 999.9 MB)
+        |         └─e270a44f124d Size: 12.29 kB (virtual 999.9 MB) Tags: progrium/buildstep:latest
+        └─17e74ac162d8 Size: 53.93 kB (virtual 180.2 MB)
+          └─339a3f56b760 Size: 24.65 kB (virtual 180.2 MB)
+            └─904fcc40e34d Size: 96.7 MB (virtual 276.9 MB)
+              └─b1b0235328dd Size: 363.3 MB (virtual 640.2 MB)
+                └─7cb05d1acb3b Size: 20.48 kB (virtual 640.2 MB)
+                  └─47bf6f34832d Size: 20.48 kB (virtual 640.2 MB)
+                    └─f165104e82ed Size: 12.29 kB (virtual 640.2 MB)
+                      └─d9cf85a47b7e Size: 1.911 MB (virtual 642.2 MB)
+                        └─3ee562df86ca Size: 17.07 kB (virtual 642.2 MB)
+                          └─b05fc2d00e4a Size: 24.96 kB (virtual 642.2 MB)
+                            └─c96a99614930 Size: 12.29 kB (virtual 642.2 MB)
+                              └─a6a357a48c49 Size: 12.29 kB (virtual 642.2 MB) Tags: ndj/mongodb:latest
+
 .. _cli_import:
 
 ``import``
@@ -314,7 +517,7 @@ Displaying images visually
 
 ::
 
-    Usage: docker import URL|- [REPOSITORY [TAG]]
+    Usage: docker import URL|- [REPOSITORY[:TAG]]
 
     Create a new filesystem image from the contents of a tarball
 
@@ -330,14 +533,16 @@ Examples
 Import from a remote location
 .............................
 
-``$ sudo docker import http://example.com/exampleimage.tgz exampleimagerepo``
+This will create a new untagged image.
+
+``$ sudo docker import http://example.com/exampleimage.tgz``
 
 Import from a local file
 ........................
 
 Import to docker via pipe and standard in
 
-``$ cat exampleimage.tgz | sudo docker import - exampleimagelocal``
+``$ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new``
 
 Import from a local directory
 .............................
@@ -360,6 +565,21 @@ might not get preserved.
 
     Display system-wide information.
 
+.. code-block:: bash
+
+	$ sudo docker info
+	Containers: 292
+	Images: 194
+	Debug mode (server): false
+	Debug mode (client): false
+	Fds: 22
+	Goroutines: 67
+	LXC Version: 0.9.0
+	EventsListeners: 115
+	Kernel Version: 3.8.0-33-generic
+	WARNING: No swap limit support
+
+
 .. _cli_insert:
 
 ``insert``
@@ -401,7 +621,27 @@ Insert file from github
 
     Usage: docker kill CONTAINER [CONTAINER...]
 
-    Kill a running container
+    Kill a running container (Send SIGKILL)
+
+The main process inside the container will be sent SIGKILL.
+
+Known Issues (kill)
+~~~~~~~~~~~~~~~~~~~
+
+* :issue:`197` indicates that ``docker kill`` may leave directories
+  behind and make it difficult to remove the container.
+
+.. _cli_load:
+
+``load``
+--------
+
+::
+
+    Usage: docker load < repository.tar
+
+    Loads a tarred repository from the standard input stream.
+    Restores both images and tags.
 
 .. _cli_login:
 
@@ -510,7 +750,13 @@ Insert file from github
 
     Remove one or more containers
         -link="": Remove the link instead of the actual container
- 
+
+Known Issues (rm)
+~~~~~~~~~~~~~~~~~~~
+
+* :issue:`197` indicates that ``docker kill`` may leave directories
+  behind and make it difficult to remove the container.
+
 
 Examples:
 ~~~~~~~~~
@@ -533,6 +779,15 @@ This will remove the container referenced under the link ``/redis``.
 This will remove the underlying link between ``/webapp`` and the ``/redis`` containers removing all
 network communication.
 
+.. code-block:: bash
+
+    $ docker rm `docker ps -a -q`
+
+
+This command will delete all stopped containers. The command ``docker ps -a -q`` will return all
+existing container IDs and pass them to the ``rm`` command which will delete them. Any running
+containers will not be deleted.
+
 .. _cli_rmi:
 
 ``rmi``
@@ -563,7 +818,7 @@ network communication.
       -h="": Container host name
       -i=false: Keep stdin open even if not attached
       -privileged=false: Give extended privileges to this container
-      -m=0: Memory limit (in bytes)
+      -m="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
       -n=true: Enable networking for this container
       -p=[]: Map a network port to the container
       -rm=false: Automatically remove the container when it exits (incompatible with -d)
@@ -571,7 +826,7 @@ network communication.
       -u="": Username or UID
       -dns=[]: Set custom dns servers for the container
       -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro]. If "container-dir" is missing, then docker creates a new volume.
-      -volumes-from="": Mount all volumes from the given container
+      -volumes-from="": Mount all volumes from the given container(s)
       -entrypoint="": Overwrite the default entrypoint set by the image
       -w="": Working directory inside the container
       -lxc-conf=[]: Add custom lxc options -lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
@@ -579,6 +834,7 @@ network communication.
       -expose=[]: Expose a port from the container without publishing it to your host
       -link="": Add link to another container (name:alias)
       -name="": Assign the specified name to the container. If no name is specific docker will generate a random name
+      -P=false: Publish all exposed ports to the host interfaces
 
 Examples
 --------
@@ -615,60 +871,82 @@ use-cases, like running Docker within Docker.
 
    docker  run -w /path/to/dir/ -i -t  ubuntu pwd
 
-The ``-w`` lets the command being executed inside directory given, 
-here /path/to/dir/. If the path does not exists it is created inside the 
+The ``-w`` lets the command being executed inside directory given,
+here /path/to/dir/. If the path does not exists it is created inside the
 container.
 
 .. code-block:: bash
 
    docker  run  -v `pwd`:`pwd` -w `pwd` -i -t  ubuntu pwd
 
-The ``-v`` flag mounts the current working directory into the container. 
-The ``-w`` lets the command being executed inside the current 
+The ``-v`` flag mounts the current working directory into the container.
+The ``-w`` lets the command being executed inside the current
 working directory, by changing into the directory to the value
 returned by ``pwd``. So this combination executes the command
 using the container, but inside the current working directory.
 
 .. code-block:: bash
 
-    docker run -p 127.0.0.0::80 ubuntu bash
+    docker run -p 127.0.0.1:80:8080 ubuntu bash
 
-This the ``-p`` flag now allows you to bind a port to a specific
-interface of the host machine.  In this example port ``80`` of the 
-container will have a dynamically allocated port bound to 127.0.0.1 
-of the host.
-
-.. code-block:: bash
-
-    docker run -p 127.0.0.1:80:80 ubuntu bash
-
-This will bind port ``80`` of the container to port ``80`` on 127.0.0.1 of your
-host machine.
+This binds port ``8080`` of the container to port ``80`` on 127.0.0.1 of the
+host machine. :ref:`port_redirection` explains in detail how to manipulate ports
+in Docker.
 
 .. code-block:: bash
 
     docker run -expose 80 ubuntu bash
 
-This will expose port ``80`` of the container for use within a link
-without publishing the port to the host system's interfaces.  
+This exposes port ``80`` of the container for use within a link without
+publishing the port to the host system's interfaces. :ref:`port_redirection`
+explains in detail how to manipulate ports in Docker.
 
 .. code-block:: bash
 
     docker run -name console -t -i ubuntu bash
 
-This will create and run a new container with the container name 
+This will create and run a new container with the container name
 being ``console``.
 
 .. code-block:: bash
 
     docker run -link /redis:redis -name console ubuntu bash
 
-The ``-link`` flag will link the container named ``/redis`` into the 
+The ``-link`` flag will link the container named ``/redis`` into the
 newly created container with the alias ``redis``.  The new container
 can access the network and environment of the redis container via
-environment variables.  The ``-name`` flag will assign the name ``console`` 
+environment variables.  The ``-name`` flag will assign the name ``console``
 to the newly created container.
 
+.. code-block:: bash
+
+   docker run -volumes-from 777f7dc92da7,ba8c0c54f0f2:ro -i -t ubuntu pwd
+
+The ``-volumes-from`` flag mounts all the defined volumes from the
+refrence containers. Containers can be specified by a comma seperated
+list or by repetitions of the ``-volumes-from`` argument. The container
+id may be optionally suffixed with ``:ro`` or ``:rw`` to mount the volumes in
+read-only or read-write mode, respectively. By default, the volumes are mounted
+in the same mode (rw or ro) as the reference container.
+
+Known Issues (run -volumes-from)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* :issue:`2702`: "lxc-start: Permission denied - failed to mount"
+  could indicate a permissions problem with AppArmor. Please see the
+  issue for a workaround.
+
+.. _cli_save:
+
+``save``
+
+::
+
+    Usage: docker save image > repository.tar
+
+    Streams a tarred repository to the standard output stream.
+    Contains all parent layers, and all tags + versions.
+
 .. _cli_search:
 
 ``search``
@@ -678,8 +956,11 @@ to the newly created container.
 
     Usage: docker search TERM
 
-    Searches for the TERM parameter on the Docker index and prints out
-    a list of repositories that match.
+    Search the docker index for images
+
+     -notrunc=false: Don't truncate output
+     -stars=0: Only displays with at least xxx stars
+     -trusted=false: Only show trusted builds
 
 .. _cli_start:
 
@@ -704,10 +985,12 @@ to the newly created container.
 
     Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...]
 
-    Stop a running container
+    Stop a running container (Send SIGTERM, and then SIGKILL after grace period)
 
       -t=10: Number of seconds to wait for the container to stop before killing it.
 
+The main process inside the container will receive SIGTERM, and after a grace period, SIGKILL
+
 .. _cli_tag:
 
 ``tag``
@@ -715,7 +998,7 @@ to the newly created container.
 
 ::
 
-    Usage: docker tag [OPTIONS] IMAGE REPOSITORY [TAG]
+    Usage: docker tag [OPTIONS] IMAGE REPOSITORY[:TAG]
 
     Tag an image into a repository
 
@@ -728,7 +1011,7 @@ to the newly created container.
 
 ::
 
-    Usage: docker top CONTAINER
+    Usage: docker top CONTAINER [ps OPTIONS]
 
     Lookup the running processes of a container
 
@@ -750,6 +1033,3 @@ Show the version of the docker client, daemon, and latest released version.
     Usage: docker wait [OPTIONS] NAME
 
     Block until a container stops, then print its exit code.
-
-
-

docs/sources/conf.py

@@ -40,7 +40,11 @@ html_additional_pages = {
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinxcontrib.httpdomain']
+extensions = ['sphinxcontrib.httpdomain', 'sphinx.ext.extlinks']
+
+# Configure extlinks
+extlinks = { 'issue': ('https://github.com/dotcloud/docker/issues/%s',
+	               'Issue ') }
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -231,7 +235,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('toctree', 'docker', u'Docker Documentation',
+    ('commandline/cli', 'docker', u'Docker Documentation',
      [u'Team Docker'], 1)
 ]
 

docs/sources/contributing/contributing.rst

@@ -10,13 +10,16 @@ Want to hack on Docker? Awesome!
 The repository includes `all the instructions you need to get
 started <https://github.com/dotcloud/docker/blob/master/CONTRIBUTING.md>`_.
 
-The developer environment `Dockerfile <https://github.com/dotcloud/docker/blob/master/Dockerfile>`_
+The `developer environment Dockerfile
+<https://github.com/dotcloud/docker/blob/master/Dockerfile>`_
 specifies the tools and versions used to test and build Docker.
 
 If you're making changes to the documentation, see the
 `README.md <https://github.com/dotcloud/docker/blob/master/docs/README.md>`_.
 
-The documentation environment `Dockerfile <https://github.com/dotcloud/docker/blob/master/docs/Dockerfile>`_
+The `documentation environment Dockerfile
+<https://github.com/dotcloud/docker/blob/master/docs/Dockerfile>`_
 specifies the tools and versions used to build the Documentation.
 
-Further interesting details can be found in the `Packaging hints <https://github.com/dotcloud/docker/blob/master/hack/PACKAGERS.md>`_.
+Further interesting details can be found in the `Packaging hints
+<https://github.com/dotcloud/docker/blob/master/hack/PACKAGERS.md>`_.

docs/sources/contributing/devenvironment.rst

@@ -56,7 +56,7 @@ To create the Docker binary, run this command:
 
 .. code-block:: bash
 
-	sudo docker run -lxc-conf=lxc.aa_profile=unconfined -privileged -v `pwd`:/go/src/github.com/dotcloud/docker docker hack/make.sh binary
+	sudo docker run -privileged -v `pwd`:/go/src/github.com/dotcloud/docker docker hack/make.sh binary
 
 This will create the Docker binary in ``./bundles/<version>-dev/binary/``
 
@@ -64,20 +64,15 @@ This will create the Docker binary in ``./bundles/<version>-dev/binary/``
 Step 5: Run the Tests
 ---------------------
 
-To run the Docker test cases you first need to disable `AppArmor <https://wiki.ubuntu.com/AppArmor>`_ using the following commands
-
-.. code-block:: bash
-
-	sudo /etc/init.d/apparmor stop
-	sudo /etc/init.d/apparmor teardown
-
 To execute the test cases, run this command:
 
 .. code-block:: bash
 
-	sudo docker run -lxc-conf=lxc.aa_profile=unconfined -privileged -v `pwd`:/go/src/github.com/dotcloud/docker docker hack/make.sh test
+	sudo docker run -privileged -v `pwd`:/go/src/github.com/dotcloud/docker docker hack/make.sh test
 
 
+Note: if you're running the tests in vagrant, you need to specify a dns entry in the command: `-dns 8.8.8.8`
+
 If the test are successful then the tail of the output should look something like this
 
 .. code-block:: bash

docs/sources/examples/couchdb_data_volumes.rst

@@ -10,7 +10,7 @@ CouchDB Service
 .. include:: example_header.inc
 
 Here's an example of using data volumes to share the same data between
-2 CouchDB containers.  This could be used for hot upgrades, testing
+two CouchDB containers.  This could be used for hot upgrades, testing
 different versions of CouchDB on the same data, etc.
 
 Create first database
@@ -20,28 +20,28 @@ Note that we're marking ``/var/lib/couchdb`` as a data volume.
 
 .. code-block:: bash
 
-    COUCH1=$(sudo docker run -d -v /var/lib/couchdb shykes/couchdb:2013-05-03)
+    COUCH1=$(sudo docker run -d -p 5984 -v /var/lib/couchdb shykes/couchdb:2013-05-03)
 
 Add data to the first database
 ------------------------------
 
-We're assuming your docker host is reachable at `localhost`. If not,
-replace `localhost` with the public IP of your docker host.
+We're assuming your Docker host is reachable at ``localhost``. If not,
+replace ``localhost`` with the public IP of your Docker host.
 
 .. code-block:: bash
 
     HOST=localhost
-    URL="http://$HOST:$(sudo docker port $COUCH1 5984)/_utils/"
+    URL="http://$HOST:$(sudo docker port $COUCH1 5984 | grep -Po '\d+$')/_utils/"
     echo "Navigate to $URL in your browser, and use the couch interface to add data"
 
 Create second database
 ----------------------
 
-This time, we're requesting shared access to $COUCH1's volumes.
+This time, we're requesting shared access to ``$COUCH1``'s volumes.
 
 .. code-block:: bash
 
-    COUCH2=$(sudo docker run -d -volumes-from $COUCH1 shykes/couchdb:2013-05-03)
+    COUCH2=$(sudo docker run -d -p 5984 -volumes-from $COUCH1 shykes/couchdb:2013-05-03)
 
 Browse data on the second database
 ----------------------------------
@@ -49,8 +49,8 @@ Browse data on the second database
 .. code-block:: bash
 
     HOST=localhost
-    URL="http://$HOST:$(sudo docker port $COUCH2 5984)/_utils/"
+    URL="http://$HOST:$(sudo docker port $COUCH2 5984 | grep -Po '\d+$')/_utils/"
     echo "Navigate to $URL in your browser. You should see the same data as in the first database"'!'
 
-Congratulations, you are running 2 Couchdb containers, completely
+Congratulations, you are now running two Couchdb containers, completely
 isolated from each other *except* for their data.

docs/sources/examples/example_header.inc

@@ -1,4 +1,7 @@
 
 .. note::
     
-    This example assumes you have Docker running in daemon mode. For more information please see :ref:`running_examples`
+    * This example assumes you have Docker running in daemon mode. For
+      more information please see :ref:`running_examples`.
+    * **If you don't like sudo** then see :ref:`dockergroup`
+

docs/sources/examples/hello_world.rst

@@ -12,16 +12,16 @@ Hello World
 Running the Examples
 ====================
 
-All the examples assume your machine is running the docker daemon. To
-run the docker daemon in the background, simply type:
+All the examples assume your machine is running the ``docker`` daemon. To
+run the ``docker`` daemon in the background, simply type:
 
 .. code-block:: bash
 
    sudo docker -d &
 
-Now you can run docker in client mode: by default all commands will be
+Now you can run Docker in client mode: by default all commands will be
 forwarded to the ``docker`` daemon via a protected Unix socket, so you
-must run as root.
+must run as the ``root`` or via the ``sudo`` command.
 
 .. code-block:: bash
 
@@ -38,23 +38,24 @@ Hello World
 
 This is the most basic example available for using Docker.
 
-Download the base image (named "ubuntu"):
+Download the base image which is named ``ubuntu``:
 
 .. code-block:: bash
 
     # Download an ubuntu image
     sudo docker pull ubuntu
 
-Alternatively to the *ubuntu* image, you can select *busybox*, a bare
+Alternatively to the ``ubuntu`` image, you can select ``busybox``, a bare
 minimal Linux system. The images are retrieved from the Docker
 repository.
 
 
 .. code-block:: bash
 
-    #run a simple echo command, that will echo hello world back to the console over standard out.
     sudo docker run ubuntu /bin/echo hello world
 
+This command will run a simple ``echo`` command, that will echo ``hello world`` back to the console over standard out.
+
 **Explanation:**
 
 - **"sudo"** execute the following commands as user *root* 
@@ -100,9 +101,9 @@ we stop it.
     CONTAINER_ID=$(sudo docker run -d ubuntu /bin/sh -c "while true; do echo hello world; sleep 1; done")
 
 We are going to run a simple hello world daemon in a new container
-made from the *ubuntu* image.
+made from the ``ubuntu`` image.
 
-- **"docker run -d "** run a command in a new container. We pass "-d"
+- **"sudo docker run -d "** run a command in a new container. We pass "-d"
   so it runs as a daemon.
 - **"ubuntu"** is the image we want to run the command inside of.
 - **"/bin/sh -c"** is the command we want to run in the container
@@ -126,10 +127,12 @@ Check the logs make sure it is working correctly.
 
     sudo docker attach $CONTAINER_ID
 
-Attach to the container to see the results in realtime.
+Attach to the container to see the results in real-time.
 
 - **"docker attach**" This will allow us to attach to a background
   process to see what is going on.
+- **"-sig-proxy=true"** Proxify all received signal to the process
+  (even in non-tty mode)
 - **$CONTAINER_ID** The Id of the container we want to attach too.
 
 Exit from the container attachment by pressing Control-C.

docs/sources/examples/index.rst

@@ -10,7 +10,7 @@ Examples
 
 Here are some examples of how to use Docker to create running
 processes, starting from a very simple *Hello World* and progressing
-to more substantial services like you might find in production.
+to more substantial services like those which you might find in production.
 
 .. toctree::
    :maxdepth: 1
@@ -24,4 +24,3 @@ to more substantial services like you might find in production.
    postgresql_service
    mongodb
    running_riak_service
-   linking_into_redis

docs/sources/examples/linking_into_redis.rst

@@ -1,132 +0,0 @@
-:title: Linking to an Redis container
-:description: Running redis linked into your web app
-:keywords: docker, example, networking, redis, link
-
-.. _linking_redis:
-
-Linking Redis
-=============
-
-.. include:: example_header.inc
-
-Building a redis container to link as a child of our web application.
-
-Building the redis container
-----------------------------
-
-Lets build a redis image with the following Dockerfile.
-
-.. code-block:: bash
-
-    git clone https://github.com/antirez/redis.git
-    cd redis
-    git checkout 2.6
-
-    # Save this Dockerfile to the root of the redis repository.  
-
-    # Build redis from source
-    # Make sure you have the redis source code checked out in
-    # the same directory as this Dockerfile
-    FROM ubuntu
-
-    RUN echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list
-    RUN apt-get update
-    RUN apt-get upgrade -y
-
-    RUN apt-get install -y gcc make g++ build-essential libc6-dev tcl
-
-    ADD . /redis
-
-    RUN (cd /redis && make)
-
-    RUN mkdir -p /redis-data
-    VOLUME ["/redis-data"]
-    EXPOSE 6379
-
-    ENTRYPOINT ["/redis/src/redis-server"]
-    CMD ["--dir", "/redis-data"]
-
-    # docker build our new redis image from source
-    docker build -t redis-2.6 .
-
-
-We need to ``EXPOSE`` the default port of 6379 so that our link knows what ports 
-to connect to our redis container on.  If you do not expose any ports for the
-image then docker will not be able to establish the link between containers.
-
-
-Run the redis container
------------------------
-
-.. code-block:: bash
-    
-    docker run -d -e PASSWORD=docker -name redis redis-2.6 --requirepass docker
- 
-This will run our redis container wit the password docker 
-to secure our service.  By specifying the ``-name`` flag on run 
-we will assign the name ``redis`` to this container.  If we do not specify a name  for 
-our container via the ``-name`` flag docker will automatically generate a name for us.
-We can issue all the commands that you would expect; start, stop, attach, using the name for our container.
-The name also allows us to link other containers into this one.
-
-Linking redis as a child
-------------------------
-
-Next we can start a new web application that has a dependency on redis and apply a link 
-to connect both containers.  If you noticed when running our redis server we did not use
-the ``-p`` flag to publish the redis port to the host system.  Redis exposed port 6379 via the Dockerfile 
-and this is all we need to establish a link.
-
-Now lets start our web application with a link into redis.
-
-.. code-block:: bash
-   
-    docker run -t -i -link redis:db -name webapp ubuntu bash
-
-    root@4c01db0b339c:/# env
-
-    HOSTNAME=4c01db0b339c
-    DB_NAME=/webapp/db
-    TERM=xterm
-    DB_PORT=tcp://172.17.0.8:6379
-    DB_PORT_6379_TCP=tcp://172.17.0.8:6379
-    DB_PORT_6379_TCP_PROTO=tcp
-    DB_PORT_6379_TCP_ADDR=172.17.0.8
-    DB_PORT_6379_TCP_PORT=6379
-    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-    PWD=/
-    DB_ENV_PASSWORD=dockerpass
-    SHLVL=1
-    HOME=/
-    container=lxc
-    _=/usr/bin/env
-    root@4c01db0b339c:/#
-
-
-When we inspect the environment of the linked container we can see a few extra environment 
-variables have been added.  When you specified ``-link redis:db`` you are telling docker
-to link the container named ``redis`` into this new container with the alias ``db``.  
-Environment variables are prefixed with the alias so that the parent container can access
-network and environment information from the containers that are linked into it.
-
-.. code-block:: bash
-
-    # The name of the child container
-    DB_NAME=/webapp/db
-
-    # The default protocol, ip, and port of the service running in the container
-    DB_PORT=tcp://172.17.0.8:6379
-
-    # A specific protocol, ip, and port of various services
-    DB_PORT_6379_TCP=tcp://172.17.0.8:6379
-    DB_PORT_6379_TCP_PROTO=tcp
-    DB_PORT_6379_TCP_ADDR=172.17.0.8
-    DB_PORT_6379_TCP_PORT=6379
-
-    # Get environment variables of the container 
-    DB_ENV_PASSWORD=dockerpass
-
-
-Accessing the network information along with the environment of the child container allows
-us to easily connect to the redis service on the specific ip and port and use the password
-specified in the environment.

docs/sources/examples/mongodb.rst

@@ -10,8 +10,8 @@ Building an Image with MongoDB
 .. include:: example_header.inc
 
 The goal of this example is to show how you can build your own
-docker images with MongoDB preinstalled. We will do that by
-constructing a Dockerfile that downloads a base image, adds an
+Docker images with MongoDB pre-installed. We will do that by
+constructing a ``Dockerfile`` that downloads a base image, adds an
 apt source and installs the database software on Ubuntu.
 
 Creating a ``Dockerfile``
@@ -41,7 +41,7 @@ Since we want to be running the latest version of MongoDB we'll need to add the
     RUN echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' | tee /etc/apt/sources.list.d/10gen.list
 
 Then, we don't want Ubuntu to complain about init not being available so we'll
-divert /sbin/initctl to /bin/true so it thinks everything is working.
+divert ``/sbin/initctl`` to ``/bin/true`` so it thinks everything is working.
 
 .. code-block:: bash
 
@@ -65,8 +65,8 @@ run without needing to provide a special configuration file)
     # Create the MongoDB data directory
     RUN mkdir -p /data/db
 
-Finally, we'll expose the standard port that MongoDB runs on (27107) as well as
-define an ENTRYPOINT for the container.
+Finally, we'll expose the standard port that MongoDB runs on, 27107, as well as
+define an ``ENTRYPOINT`` instruction for the container.
 
 .. code-block:: bash
 
@@ -78,7 +78,7 @@ run all of the commands.
 
 .. code-block:: bash
 
-    docker build -t <yourname>/mongodb .
+    sudo docker build -t <yourname>/mongodb .
 
 Now you should be able to run ``mongod`` as a daemon and be able to connect on
 the local port!
@@ -86,13 +86,13 @@ the local port!
 .. code-block:: bash
 
     # Regular style
-    MONGO_ID=$(docker run -d <yourname>/mongodb)
+    MONGO_ID=$(sudo docker run -d <yourname>/mongodb)
 
     # Lean and mean
-    MONGO_ID=$(docker run -d <yourname>/mongodb --noprealloc --smallfiles)
+    MONGO_ID=$(sudo docker run -d <yourname>/mongodb --noprealloc --smallfiles)
 
     # Check the logs out
-    docker logs $MONGO_ID
+    sudo docker logs $MONGO_ID
 
     # Connect and play around
     mongo --port <port you get from `docker ps`>

docs/sources/examples/nodejs_web_app.rst

@@ -10,7 +10,7 @@ Node.js Web App
 .. include:: example_header.inc
 
 The goal of this example is to show you how you can build your own
-docker images from a parent image using a ``Dockerfile`` . We will do
+Docker images from a parent image using a ``Dockerfile`` . We will do
 that by making a simple Node.js hello world web application running on
 CentOS. You can get the full source code at
 https://github.com/gasi/docker-node-hello.
@@ -55,7 +55,7 @@ Then, create an ``index.js`` file that defines a web app using the
 
 
 In the next steps, we’ll look at how you can run this app inside a CentOS
-container using docker. First, you’ll need to build a docker image of your app.
+container using Docker. First, you’ll need to build a Docker image of your app.
 
 Creating a ``Dockerfile``
 +++++++++++++++++++++++++
@@ -67,8 +67,8 @@ Create an empty file called ``Dockerfile``:
     touch Dockerfile
 
 Open the ``Dockerfile`` in your favorite text editor and add the following line
-that defines the version of docker the image requires to build
-(this example uses docker 0.3.4):
+that defines the version of Docker the image requires to build
+(this example uses Docker 0.3.4):
 
 .. code-block:: bash
 
@@ -76,7 +76,7 @@ that defines the version of docker the image requires to build
 
 Next, define the parent image you want to use to build your own image on top of.
 Here, we’ll use `CentOS <https://index.docker.io/_/centos/>`_ (tag: ``6.4``)
-available on the `docker index`_:
+available on the `Docker index`_:
 
 .. code-block:: bash
 
@@ -95,23 +95,23 @@ To install the right package for CentOS, we’ll use the instructions from the
     # Install Node.js and npm
     RUN     yum install -y npm
 
-To bundle your app’s source code inside the docker image, use the ``ADD``
-command:
+To bundle your app’s source code inside the Docker image, use the ``ADD``
+instruction:
 
 .. code-block:: bash
 
     # Bundle app source
     ADD . /src
 
-Install your app dependencies using npm:
+Install your app dependencies using the ``npm`` binary:
 
 .. code-block:: bash
 
     # Install app dependencies
     RUN cd /src; npm install
 
-Your app binds to port ``8080`` so you’ll use the ``EXPOSE`` command
-to have it mapped by the docker daemon:
+Your app binds to port ``8080`` so you’ll use the ``EXPOSE`` instruction
+to have it mapped by the ``docker`` daemon:
 
 .. code-block:: bash
 
@@ -152,7 +152,7 @@ Building your image
 +++++++++++++++++++
 
 Go to the directory that has your ``Dockerfile`` and run the following
-command to build a docker image. The ``-t`` flag let’s you tag your
+command to build a Docker image. The ``-t`` flag let’s you tag your
 image so it’s easier to find later using the ``docker images``
 command:
 
@@ -160,7 +160,7 @@ command:
 
     sudo docker build -t <your username>/centos-node-hello .
 
-Your image will now be listed by docker:
+Your image will now be listed by Docker:
 
 .. code-block:: bash
 
@@ -176,11 +176,11 @@ Run the image
 +++++++++++++
 
 Running your image with ``-d`` runs the container in detached mode, leaving the
-container running in the background. Run the image you previously built:
+container running in the background. The ``-p`` flag redirects a public port to a private port in the container. Run the image you previously built:
 
 .. code-block:: bash
 
-    sudo docker run -d <your username>/centos-node-hello
+    sudo docker run -p 49160:8080 -d <your username>/centos-node-hello
 
 Print the output of your app:
 
@@ -199,17 +199,17 @@ Print the output of your app:
 Test
 ++++
 
-To test your app, get the the port of your app that docker mapped:
+To test your app, get the the port of your app that Docker mapped:
 
 .. code-block:: bash
 
-    docker ps
+    sudo docker ps
 
     > # Example
     > ID            IMAGE                          COMMAND              ...   PORTS
     > ecce33b30ebf  gasi/centos-node-hello:latest  node /src/index.js         49160->8080
 
-In the example above, docker mapped the ``8080`` port of the container to
+In the example above, Docker mapped the ``8080`` port of the container to
 ``49160``.
 
 Now you can call your app using ``curl`` (install if needed via:
@@ -229,7 +229,7 @@ Now you can call your app using ``curl`` (install if needed via:
     > Hello World
 
 We hope this tutorial helped you get up and running with Node.js and
-CentOS on docker. You can get the full source code at
+CentOS on Docker. You can get the full source code at
 https://github.com/gasi/docker-node-hello.
 
 Continue to :ref:`running_redis_service`.

docs/sources/examples/postgresql_service.rst

@@ -13,7 +13,7 @@ PostgreSQL Service
 
 .. note::
 
-    As of version 0.5.2, docker requires root privileges to run.
+    As of version 0.5.2, Docker requires root privileges to run.
     You have to either manually adjust your system configuration (permissions on
     /var/run/docker.sock or sudo config), or prefix `docker` with `sudo`. Check
     `this thread`_ for details.
@@ -24,8 +24,7 @@ PostgreSQL Service
 Installing PostgreSQL on Docker
 -------------------------------
 
-For clarity I won't be showing commands output.
-
+For clarity I won't be showing command output.
 
 Run an interactive shell in Docker container.
 
@@ -62,7 +61,7 @@ Finally, install PostgreSQL 9.2
 
 Now, create a PostgreSQL superuser role that can create databases and
 other roles.  Following Vagrant's convention the role will be named
-`docker` with `docker` password assigned to it.
+``docker`` with ``docker`` password assigned to it.
 
 .. code-block:: bash
 
@@ -108,7 +107,7 @@ Bash prompt; you can also locate it using ``docker ps -a``.
 
 .. code-block:: bash
 
-    docker commit <container_id> <your username>/postgresql
+    sudo docker commit <container_id> <your username>/postgresql
 
 Finally, run PostgreSQL server via ``docker``.
 

docs/sources/examples/python_web_app.rst

@@ -10,9 +10,9 @@ Python Web App
 .. include:: example_header.inc
 
 The goal of this example is to show you how you can author your own
-docker images using a parent image, making changes to it, and then
+Docker images using a parent image, making changes to it, and then
 saving the results as a new image. We will do that by making a simple
-hello flask web application image.
+hello Flask web application image.
 
 **Steps:**
 
@@ -20,36 +20,37 @@ hello flask web application image.
 
     sudo docker pull shykes/pybuilder
 
-We are downloading the "shykes/pybuilder" docker image
+We are downloading the ``shykes/pybuilder`` Docker image
 
 .. code-block:: bash
 
     URL=http://github.com/shykes/helloflask/archive/master.tar.gz
 
-We set a URL variable that points to a tarball of a simple helloflask web app
+We set a ``URL`` variable that points to a tarball of a simple helloflask web app
 
 .. code-block:: bash
 
     BUILD_JOB=$(sudo docker run -d -t shykes/pybuilder:latest /usr/local/bin/buildapp $URL)
 
-Inside of the "shykes/pybuilder" image there is a command called
-buildapp, we are running that command and passing the $URL variable
+Inside of the ``shykes/pybuilder`` image there is a command called
+``buildapp``, we are running that command and passing the ``$URL`` variable
 from step 2 to it, and running the whole thing inside of a new
-container. BUILD_JOB will be set with the new container_id.
+container. The ``BUILD_JOB`` environment variable will be set with the new container ID.
 
 .. code-block:: bash
 
-    sudo docker attach $BUILD_JOB
+    sudo docker attach -sig-proxy=false $BUILD_JOB
     [...]
 
 While this container is running, we can attach to the new container to
-see what is going on. Ctrl-C to disconnect.
+see what is going on. The flag ``-sig-proxy`` set as ``false`` allows you to connect and
+disconnect (Ctrl-C) to it without stopping the container.
 
 .. code-block:: bash
 
     sudo docker ps -a
-    
-List all docker containers. If this container has already finished
+
+List all Docker containers. If this container has already finished
 running, it will still be listed here.
 
 .. code-block:: bash
@@ -57,8 +58,8 @@ running, it will still be listed here.
     BUILD_IMG=$(sudo docker commit $BUILD_JOB _/builds/github.com/shykes/helloflask/master)
 
 Save the changes we just made in the container to a new image called
-``_/builds/github.com/hykes/helloflask/master`` and save the image id in
-the BUILD_IMG variable name.
+``_/builds/github.com/hykes/helloflask/master`` and save the image ID in
+the ``BUILD_IMG`` variable name.
 
 .. code-block:: bash
 
@@ -72,24 +73,24 @@ the BUILD_IMG variable name.
 - **/usr/local/bin/runapp** is the command which starts the web app.
 
 Use the new image we just created and create a new container with
-network port 5000, and return the container id and store in the
-WEB_WORKER variable.
+network port 5000, and return the container ID and store in the
+``WEB_WORKER`` variable.
 
 .. code-block:: bash
 
     sudo docker logs $WEB_WORKER
      * Running on http://0.0.0.0:5000/
 
-View the logs for the new container using the WEB_WORKER variable, and
-if everything worked as planned you should see the line "Running on
-http://0.0.0.0:5000/" in the log output.
+View the logs for the new container using the ``WEB_WORKER`` variable, and
+if everything worked as planned you should see the line ``Running on
+http://0.0.0.0:5000/`` in the log output.
 
 .. code-block:: bash
 
-    WEB_PORT=$(sudo docker port $WEB_WORKER 5000)
+    WEB_PORT=$(sudo docker port $WEB_WORKER 5000 | awk -F: '{ print $2 }')
 
 Look up the public-facing port which is NAT-ed. Find the private port
-used by the container and store it inside of the WEB_PORT variable.
+used by the container and store it inside of the ``WEB_PORT`` variable.
 
 .. code-block:: bash
 
@@ -97,8 +98,8 @@ used by the container and store it inside of the WEB_PORT variable.
     curl http://127.0.0.1:$WEB_PORT
       Hello world!
 
-Access the web app using curl. If everything worked as planned you
-should see the line "Hello world!" inside of your console.
+Access the web app using the ``curl`` binary. If everything worked as planned you
+should see the line ``Hello world!`` inside of your console.
 
 **Video:**
 

docs/sources/examples/running_redis_service.rst

@@ -9,74 +9,93 @@ Redis Service
 
 .. include:: example_header.inc
 
-Very simple, no frills, redis service.
+Very simple, no frills, Redis service attached to a web application using a link.
 
-Open a docker container
------------------------
+Create a docker container for Redis
+-----------------------------------
+
+Firstly, we create a ``Dockerfile`` for our new Redis image.
 
 .. code-block:: bash
 
-    sudo docker run -i -t ubuntu /bin/bash
+    FROM        ubuntu:12.10
+    RUN         apt-get update
+    RUN         apt-get -y install redis-server
+    EXPOSE      6379
+    ENTRYPOINT  ["/usr/bin/redis-server"]
 
-Building your image
--------------------
-
-Update your Docker container, install the Redis server.  Once
-installed, exit out of the Docker container.
+Next we build an image from our ``Dockerfile``. Replace ``<your username>`` 
+with your own user name.
 
 .. code-block:: bash
 
-    apt-get update
-    apt-get install redis-server
-    exit
-
-Snapshot the installation
--------------------------
-
-.. code-block:: bash
-
-    docker ps -a  # grab the container id (this will be the first one in the list)
-    docker commit <container_id> <your username>/redis
+    sudo docker build -t <your username>/redis .
 
 Run the service
 ---------------
 
-Running the service with `-d` runs the container in detached mode, leaving the
-container running in the background. Use your snapshot.
+Use the image we've just created and name your container ``redis``.
+
+Running the service with ``-d`` runs the container in detached mode, leaving the
+container running in the background.
+
+Importantly, we're not exposing any ports on our container. Instead we're going to 
+use a container link to provide access to our Redis database.
 
 .. code-block:: bash
 
-    sudo docker run -d -p 6379 <your username>/redis /usr/bin/redis-server
+    sudo docker run -name redis -d <your username>/redis
 
-Test 1
-++++++
+Create your web application container
+-------------------------------------
 
-Connect to the container with the redis-cli.
+Next we can create a container for our application. We're going to use the ``-link`` 
+flag to create a link to the ``redis`` container we've just created with an alias of 
+``db``. This will create a secure tunnel to the ``redis`` container and expose the 
+Redis instance running inside that container to only this container.
 
 .. code-block:: bash
 
-    sudo docker ps  # grab the new container id
-    sudo docker inspect <container_id>    # grab the ipaddress of the container
-    redis-cli -h <ipaddress> -p 6379
-    redis 10.0.3.32:6379> set docker awesome
+    sudo docker run -link redis:db -i -t ubuntu:12.10 /bin/bash
+
+Once inside our freshly created container we need to install Redis to get the 
+``redis-cli`` binary to test our connection.
+
+.. code-block:: bash
+
+    apt-get update
+    apt-get -y install redis-server
+    service redis-server stop
+
+Now we can test the connection. Firstly, let's look at the available environmental 
+variables in our web application container. We can use these to get the IP and port 
+of our ``redis`` container.
+
+.. code-block:: bash
+
+    env
+    . . .
+    DB_NAME=/violet_wolf/db
+    DB_PORT_6379_TCP_PORT=6379
+    DB_PORT=tcp://172.17.0.33:6379
+    DB_PORT_6379_TCP=tcp://172.17.0.33:6379
+    DB_PORT_6379_TCP_ADDR=172.17.0.33
+    DB_PORT_6379_TCP_PROTO=tcp
+
+We can see that we've got a small list of environment variables prefixed with ``DB``.
+The ``DB`` comes from the link alias specified when we launched the container. Let's use 
+the ``DB_PORT_6379_TCP_ADDR`` variable to connect to our Redis container.
+
+.. code-block:: bash
+
+    redis-cli -h $DB_PORT_6379_TCP_ADDR
+    redis 172.17.0.33:6379>
+    redis 172.17.0.33:6379> set docker awesome
     OK
-    redis 10.0.3.32:6379> get docker
+    redis 172.17.0.33:6379> get docker
     "awesome"
-    redis 10.0.3.32:6379> exit
+    redis 172.17.0.33:6379> exit
 
-Test 2
-++++++
+We could easily use this or other environment variables in our web application to make a 
+connection to our ``redis`` container.
 
-Connect to the host os with the redis-cli.
-
-.. code-block:: bash
-
-    sudo docker ps  # grab the new container id
-    sudo docker port <container_id> 6379  # grab the external port
-    ip addr show   # grab the host ip address
-    redis-cli -h <host ipaddress> -p <external port>
-    redis 192.168.0.1:49153> set docker awesome
-    OK
-    redis 192.168.0.1:49153> get docker
-    "awesome"
-    redis 192.168.0.1:49153> exit

docs/sources/examples/running_riak_service.rst

@@ -107,7 +107,7 @@ Create a ``supervisord`` configuration file
 +++++++++++++++++++++++++++++++++++++++++++
 
 Create an empty file called ``supervisord.conf``. Make sure it's at the same
-level as your ``Dockerfile``:
+directory level as your ``Dockerfile``:
 
 .. code-block:: bash
 

docs/sources/examples/running_ssh_service.rst

@@ -12,14 +12,14 @@ SSH Daemon Service
 
 **Video:**
 
-I've create a little screencast to show how to create a sshd service
+I've created a little screencast to show how to create an SSHd service
 and connect to it. It is something like 11 minutes and not entirely
-smooth, but gives you a good idea.
+smooth, but it gives you a good idea.
 
 .. note::
-   This screencast was created before ``docker`` version 0.5.2, so the
+   This screencast was created before Docker version 0.5.2, so the
    daemon is unprotected and available via a TCP port. When you run
-   through the same steps in a newer version of ``docker``, you will
+   through the same steps in a newer version of Docker, you will
    need to add ``sudo`` in front of each ``docker`` command in order
    to reach the daemon over its protected Unix socket.
 
@@ -29,13 +29,14 @@ smooth, but gives you a good idea.
       <iframe width="800" height="400" src="http://ascii.io/a/2637/raw" frameborder="0"></iframe>
     </div>
         
-You can also get this sshd container by using
-::
+You can also get this sshd container by using:
+
+.. code-block:: bash
 
     sudo docker pull dhrp/sshd
 
 
-The password is 'screencast'
+The password is ``screencast``.
 
 **Video's Transcription:**
 

docs/sources/installation/amazon.rst

@@ -22,12 +22,10 @@ Amazon QuickStart
 
 1. **Choose an image:**
 
-   * Open http://cloud-images.ubuntu.com/locator/ec2/
-   * Enter ``amd64 precise`` in the search field (it will search as you
-     type)
-   * Pick an image by clicking on the image name. *An EBS-enabled
-     image will let you use a t1.micro instance.* Clicking on the image 
-     name will take you to your AWS Console.
+   * Launch the `Create Instance Wizard` <https://console.aws.amazon.com/ec2/v2/home?#LaunchInstanceWizard:> menu on your AWS Console
+   * Select "Community AMIs" option and serch for ``amd64 precise`` (click enter to search)
+   * If you choose a EBS enabled AMI you will be able to launch a `t1.micro` instance (more info on `pricing` <http://aws.amazon.com/en/ec2/pricing/> )
+   * When you click select you'll be taken to the instance setup, and you're one click away from having your Ubuntu VM up and running.
 
 2. **Tell CloudInit to install Docker:**
 
@@ -102,26 +100,45 @@ Docker that way too. Vagrant 1.1 or higher is required.
    we need to set them there first. Make sure you have everything on
    amazon aws setup so you can (manually) deploy a new image to EC2.
 
+   Note that where possible these variables are the same as those honored by
+   the ec2 api tools.
    ::
 
-       export AWS_ACCESS_KEY_ID=xxx
-       export AWS_SECRET_ACCESS_KEY=xxx
+       export AWS_ACCESS_KEY=xxx
+       export AWS_SECRET_KEY=xxx
        export AWS_KEYPAIR_NAME=xxx
-       export AWS_SSH_PRIVKEY=xxx
+       export SSH_PRIVKEY_PATH=xxx
 
-   The environment variables are:
+       export BOX_NAME=xxx
+       export AWS_REGION=xxx
+       export AWS_AMI=xxx
+       export AWS_INSTANCE_TYPE=xxx
 
-   * ``AWS_ACCESS_KEY_ID`` - The API key used to make requests to AWS
-   * ``AWS_SECRET_ACCESS_KEY`` - The secret key to make AWS API requests
+   The required environment variables are:
+
+   * ``AWS_ACCESS_KEY`` - The API key used to make requests to AWS
+   * ``AWS_SECRET_KEY`` - The secret key to make AWS API requests
    * ``AWS_KEYPAIR_NAME`` - The name of the keypair used for this EC2 instance
-   * ``AWS_SSH_PRIVKEY`` - The path to the private key for the named
+   * ``SSH_PRIVKEY_PATH`` - The path to the private key for the named
      keypair, for example ``~/.ssh/docker.pem``
 
+   There are a number of optional environment variables:
+
+   * ``BOX_NAME`` - The name of the vagrant box to use.  Defaults to
+     ``ubuntu``.
+   * ``AWS_REGION`` - The aws region to spawn the vm in.  Defaults to
+     ``us-east-1``.
+   * ``AWS_AMI`` - The aws AMI to start with as a base.  This must be
+     be an ubuntu 12.04 precise image.  You must change this value if
+     ``AWS_REGION`` is set to a value other than ``us-east-1``.
+     This is because AMIs are region specific.  Defaults to ``ami-69f5a900``.
+   * ``AWS_INSTANCE_TYPE`` - The aws instance type.  Defaults to ``t1.micro``.
+
    You can check if they are set correctly by doing something like
 
    ::
 
-      echo $AWS_ACCESS_KEY_ID
+      echo $AWS_ACCESS_KEY
 
 6. Do the magic!
 

docs/sources/installation/index.rst

@@ -19,11 +19,12 @@ Contents:
 
    ubuntulinux
    binaries
+   security
+   upgrading
+   kernel
    vagrant
    windows
    amazon
    rackspace
    archlinux
    gentoolinux
-   upgrading
-   kernel

docs/sources/installation/kernel.rst

@@ -25,6 +25,7 @@ If you cannot or do not want to use the "official" kernels,
 here is some technical background about the features (both optional and
 mandatory) that docker needs to run successfully.
 
+
 Linux version 3.8 or above
 --------------------------
 
@@ -39,6 +40,15 @@ The symptoms include:
 - kernel crash causing the machine to freeze for a few minutes, or even
   completely.
 
+Additionally, kernels prior 3.4 did not implement ``reboot_pid_ns``,
+which means that the ``reboot()`` syscall could reboot the host machine,
+instead of terminating the container. To work around that problem,
+LXC userland tools (since version 0.8) automatically drop the ``SYS_BOOT``
+capability when necessary. Still, if you run a pre-3.4 kernel with pre-0.8
+LXC tools, be aware that containers can reboot the whole host! This is
+not something that Docker wants to address in the short term, since you
+shouldn't use kernels prior 3.8 with Docker anyway.
+
 While it is still possible to use older kernels for development, it is
 really not advised to do so.
 

docs/sources/installation/security.rst

@@ -0,0 +1,267 @@
+:title: Docker Security
+:description: Review of the Docker Daemon attack surface
+:keywords: Docker, Docker documentation, security
+
+.. _dockersecurity:
+
+Docker Security
+===============
+
+  *Adapted from* `Containers & Docker: How Secure are They? <blogsecurity>`_
+
+There are three major areas to consider when reviewing Docker security:
+
+* the intrinsic security of containers, as implemented by kernel
+  namespaces and cgroups;
+* the attack surface of the Docker daemon itself;
+* the "hardening" security features of the kernel and how they
+  interact with containers.
+
+Kernel Namespaces
+-----------------
+
+Docker containers are essentially LXC containers, and they come with
+the same security features. When you start a container with ``docker
+run``, behind the scenes Docker uses ``lxc-start`` to execute the
+Docker container. This creates a set of namespaces and control groups
+for the container. Those namespaces and control groups are not created
+by Docker itself, but by ``lxc-start``. This means that as the LXC
+userland tools evolve (and provide additional namespaces and isolation
+features), Docker will automatically make use of them.
+
+**Namespaces provide the first and most straightforward form of
+isolation**: processes running within a container cannot see, and even
+less affect, processes running in another container, or in the host
+system.
+
+**Each container also gets its own network stack**, meaning that a
+container doesn’t get a privileged access to the sockets or interfaces
+of another container. Of course, if the host system is setup
+accordingly, containers can interact with each other through their
+respective network interfaces — just like they can interact with
+external hosts. When you specify public ports for your containers or
+use :ref:`links <working_with_links_names>` then IP traffic is allowed
+between containers. They can ping each other, send/receive UDP
+packets, and establish TCP connections, but that can be restricted if
+necessary. From a network architecture point of view, all containers
+on a given Docker host are sitting on bridge interfaces. This means
+that they are just like physical machines connected through a common
+Ethernet switch; no more, no less.
+
+How mature is the code providing kernel namespaces and private
+networking?  Kernel namespaces were introduced `between kernel version
+2.6.15 and 2.6.26
+<http://lxc.sourceforge.net/index.php/about/kernel-namespaces/>`_. This
+means that since July 2008 (date of the 2.6.26 release, now 5 years
+ago), namespace code has been exercised and scrutinized on a large
+number of production systems. And there is more: the design and
+inspiration for the namespaces code are even older. Namespaces are
+actually an effort to reimplement the features of `OpenVZ
+<http://en.wikipedia.org/wiki/OpenVZ>`_ in such a way that they could
+be merged within the mainstream kernel. And OpenVZ was initially
+released in 2005, so both the design and the implementation are
+pretty mature.
+
+Control Groups
+--------------
+
+Control Groups are the other key component of Linux Containers. They
+implement resource accounting and limiting. They provide a lot of very
+useful metrics, but they also help to ensure that each container gets
+its fair share of memory, CPU, disk I/O; and, more importantly, that a
+single container cannot bring the system down by exhausting one of
+those resources.
+
+So while they do not play a role in preventing one container from
+accessing or affecting the data and processes of another container,
+they are essential to fend off some denial-of-service attacks. They
+are particularly important on multi-tenant platforms, like public and
+private PaaS, to guarantee a consistent uptime (and performance) even
+when some applications start to misbehave.
+
+Control Groups have been around for a while as well: the code was
+started in 2006, and initially merged in kernel 2.6.24.
+
+Docker Daemon Attack Surface
+----------------------------
+
+Running containers (and applications) with Docker implies running the
+Docker daemon. This daemon currently requires root privileges, and you
+should therefore be aware of some important details.
+
+First of all, **only trusted users should be allowed to control your
+Docker daemon**. This is a direct consequence of some powerful Docker
+features. Specifically, Docker allows you to share a directory between
+the Docker host and a guest container; and it allows you to do so
+without limiting the access rights of the container. This means that
+you can start a container where the ``/host`` directory will be the
+``/`` directory on your host; and the container will be able to alter
+your host filesystem without any restriction. This sounds crazy? Well,
+you have to know that **all virtualization systems allowing filesystem
+resource sharing behave the same way**. Nothing prevents you from
+sharing your root filesystem (or even your root block device) with a
+virtual machine.
+
+This has a strong security implication: if you instrument Docker from
+e.g. a web server to provision containers through an API, you should
+be even more careful than usual with parameter checking, to make sure
+that a malicious user cannot pass crafted parameters causing Docker to
+create arbitrary containers.
+
+For this reason, the REST API endpoint (used by the Docker CLI to
+communicate with the Docker daemon) changed in Docker 0.5.2, and now
+uses a UNIX socket instead of a TCP socket bound on 127.0.0.1 (the
+latter being prone to cross-site-scripting attacks if you happen to
+run Docker directly on your local machine, outside of a VM). You can
+then use traditional UNIX permission checks to limit access to the
+control socket.
+
+You can also expose the REST API over HTTP if you explicitly decide
+so. However, if you do that, being aware of the abovementioned
+security implication, you should ensure that it will be reachable
+only from a trusted network or VPN; or protected with e.g. ``stunnel``
+and client SSL certificates.
+
+Recent improvements in Linux namespaces will soon allow to run
+full-featured containers without root privileges, thanks to the new
+user namespace. This is covered in detail `here
+<http://s3hh.wordpress.com/2013/07/19/creating-and-using-containers-without-privilege/>`_. Moreover,
+this will solve the problem caused by sharing filesystems between host
+and guest, since the user namespace allows users within containers
+(including the root user) to be mapped to other users in the host
+system.
+
+The end goal for Docker is therefore to implement two additional
+security improvements:
+
+* map the root user of a container to a non-root user of the Docker
+  host, to mitigate the effects of a container-to-host privilege
+  escalation;
+* allow the Docker daemon to run without root privileges, and delegate
+  operations requiring those privileges to well-audited sub-processes,
+  each with its own (very limited) scope: virtual network setup,
+  filesystem management, etc.
+
+Finally, if you run Docker on a server, it is recommended to run
+exclusively Docker in the server, and move all other services within
+containers controlled by Docker. Of course, it is fine to keep your
+favorite admin tools (probably at least an SSH server), as well as
+existing monitoring/supervision processes (e.g. NRPE, collectd, etc).
+
+Linux Kernel Capabilities
+-------------------------
+
+By default, Docker starts containers with a very restricted set of
+capabilities. What does that mean?
+
+Capabilities turn the binary "root/non-root" dichotomy into a
+fine-grained access control system. Processes (like web servers) that
+just need to bind on a port below 1024 do not have to run as root:
+they can just be granted the ``net_bind_service`` capability
+instead. And there are many other capabilities, for almost all the
+specific areas where root privileges are usually needed.
+
+This means a lot for container security; let’s see why!
+
+Your average server (bare metal or virtual machine) needs to run a
+bunch of processes as root. Those typically include SSH, cron,
+syslogd; hardware management tools (to e.g. load modules), network
+configuration tools (to handle e.g. DHCP, WPA, or VPNs), and much
+more. A container is very different, because almost all of those tasks
+are handled by the infrastructure around the container:
+
+* SSH access will typically be managed by a single server running in
+  the Docker host;
+* ``cron``, when necessary, should run as a user process, dedicated
+  and tailored for the app that needs its scheduling service, rather
+  than as a platform-wide facility;
+* log management will also typically be handed to Docker, or by
+  third-party services like Loggly or Splunk;
+* hardware management is irrelevant, meaning that you never need to
+  run ``udevd`` or equivalent daemons within containers;
+* network management happens outside of the containers, enforcing
+  separation of concerns as much as possible, meaning that a container
+  should never need to perform ``ifconfig``, ``route``, or ip commands
+  (except when a container is specifically engineered to behave like a
+  router or firewall, of course).
+
+This means that in most cases, containers will not need "real" root
+privileges *at all*. And therefore, containers can run with a reduced
+capability set; meaning that "root" within a container has much less
+privileges than the real "root". For instance, it is possible to:
+
+* deny all "mount" operations;
+* deny access to raw sockets (to prevent packet spoofing);
+* deny access to some filesystem operations, like creating new device
+  nodes, changing the owner of files, or altering attributes
+  (including the immutable flag);
+* deny module loading;
+* and many others.
+
+This means that even if an intruder manages to escalate to root within
+a container, it will be much harder to do serious damage, or to
+escalate to the host.
+
+This won't affect regular web apps; but malicious users will find that
+the arsenal at their disposal has shrunk considerably! You can see
+`the list of dropped capabilities in the Docker code
+<https://github.com/dotcloud/docker/blob/v0.5.0/lxc_template.go#L97>`_,
+and a full list of available capabilities in `Linux manpages
+<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_.
+
+Of course, you can always enable extra capabilities if you really need
+them (for instance, if you want to use a FUSE-based filesystem), but
+by default, Docker containers will be locked down to ensure maximum
+safety.
+
+Other Kernel Security Features
+------------------------------
+
+Capabilities are just one of the many security features provided by
+modern Linux kernels. It is also possible to leverage existing,
+well-known systems like TOMOYO, AppArmor, SELinux, GRSEC, etc. with
+Docker.
+
+While Docker currently only enables capabilities, it doesn't interfere
+with the other systems. This means that there are many different ways
+to harden a Docker host. Here are a few examples.
+
+* You can run a kernel with GRSEC and PAX. This will add many safety
+  checks, both at compile-time and run-time; it will also defeat many
+  exploits, thanks to techniques like address randomization. It
+  doesn’t require Docker-specific configuration, since those security
+  features apply system-wide, independently of containers.
+* If your distribution comes with security model templates for LXC
+  containers, you can use them out of the box. For instance, Ubuntu
+  comes with AppArmor templates for LXC, and those templates provide
+  an extra safety net (even though it overlaps greatly with
+  capabilities).
+* You can define your own policies using your favorite access control
+  mechanism. Since Docker containers are standard LXC containers,
+  there is nothing “magic” or specific to Docker.
+
+Just like there are many third-party tools to augment Docker
+containers with e.g. special network topologies or shared filesystems,
+you can expect to see tools to harden existing Docker containers
+without affecting Docker’s core.
+
+Conclusions
+-----------
+
+Docker containers are, by default, quite secure; especially if you
+take care of running your processes inside the containers as
+non-privileged users (i.e. non root).
+
+You can add an extra layer of safety by enabling Apparmor, SELinux,
+GRSEC, or your favorite hardening solution.
+
+Last but not least, if you see interesting security features in other
+containerization systems, you will be able to implement them as well
+with Docker, since everything is provided by the kernel anyway.
+
+For more context and especially for comparisons with VMs and other
+container systems, please also see the `original blog post
+<blogsecurity>`_.
+
+.. _blogsecurity: http://blog.docker.io/2013/08/containers-docker-how-secure-are-they/
+

docs/sources/installation/ubuntulinux.rst

@@ -162,8 +162,8 @@ Verify it worked
 Docker and UFW
 ^^^^^^^^^^^^^^
 
-Docker uses a bridge to manage containers networking, by default UFW
-drop all `forwarding`, a first step is to enable forwarding:
+Docker uses a bridge to manage container networking. By default, UFW
+drops all `forwarding`, thus a first step is to enable UFW forwarding:
 
 .. code-block:: bash
 

docs/sources/installation/vagrant.rst

@@ -9,7 +9,7 @@ Using Vagrant (Mac, Linux)
 
 This guide will setup a new virtualbox virtual machine with docker
 installed on your computer. This works on most operating systems,
-including MacOX, Windows, Linux, FreeBSD and others. If you can
+including MacOSX, Windows, Linux, FreeBSD and others. If you can
 install these and have at least 400MB RAM to spare you should be good.
 
 Install Vagrant and Virtualbox

docs/sources/installation/windows.rst

@@ -208,6 +208,10 @@ configuration / Device configuration)
 
 .. image:: images/win/hp_bios_vm.JPG
 
+On some machines the BIOS menu can only be accessed before startup.
+To access BIOS in this scenario you should restart your computer and 
+press ESC/Enter when prompted to access the boot and BIOS controls. Typically
+the option to allow virtualization is contained within the BIOS/Security menu.
 
 Docker is not installed
 ```````````````````````

docs/sources/terms/container.rst

@@ -38,3 +38,10 @@ was when the container was stopped.
 You can promote a container to an :ref:`image_def` with ``docker
 commit``. Once a container is an image, you can use it as a parent for
 new containers.
+
+Container IDs
+.............
+All containers are identified by a 64 hexadecimal digit string (internally a 256bit 
+value). To simplify their use, a short ID of the first 12 characters can be used 
+on the commandline. There is a small possibility of short id collisions, so the 
+docker server will always return the long ID.

docs/sources/terms/image.rst

@@ -36,3 +36,11 @@ Base Image
 ..........
 
 An image that has no parent is a **base image**.
+
+Image IDs
+.........
+All images are identified by a 64 hexadecimal digit string (internally a 256bit 
+value). To simplify their use, a short ID of the first 12 characters can be used 
+on the command line. There is a small possibility of short id collisions, so the 
+docker server will always return the long ID.
+

docs/sources/use/basics.rst

@@ -22,15 +22,29 @@ specify the path to it and manually start it.
     # Run docker in daemon mode
     sudo <path to>/docker -d &
 
-
-Running an interactive shell
-----------------------------
+Download a pre-built image
+--------------------------
 
 .. code-block:: bash
 
   # Download an ubuntu image
   sudo docker pull ubuntu
 
+This will find the ``ubuntu`` image by name in the :ref:`Central Index 
+<searching_central_index>` and download it from the top-level Central 
+Repository to a local image cache.
+
+.. NOTE:: When the image has successfully downloaded, you will see a
+   12 character hash ``539c0211cd76: Download complete`` which is the
+   short form of the image ID. These short image IDs are the first 12
+   characters of the full image ID - which can be found using ``docker
+   inspect`` or ``docker images -notrunc=true``
+
+Running an interactive shell
+----------------------------
+
+.. code-block:: bash
+
   # Run an interactive shell in the ubuntu image,
   # allocate a tty, attach stdin and stdout
   # To detach the tty without exiting the shell,
@@ -39,32 +53,36 @@ Running an interactive shell
 
 .. _dockergroup:
 
-Why ``sudo``?
--------------
+sudo and the docker Group
+-------------------------
 
 The ``docker`` daemon always runs as root, and since ``docker``
 version 0.5.2, ``docker`` binds to a Unix socket instead of a TCP
 port. By default that Unix socket is owned by the user *root*, and so,
 by default, you can access it with ``sudo``.
 
-Starting in version 0.5.3, if you create a Unix group called *docker*
-and add users to it, then the ``docker`` daemon will make the
-ownership of the Unix socket read/writable by the *docker* group when
-the daemon starts. The ``docker`` daemon must always run as root, but
-if you run the ``docker`` client as a user in the *docker* group then
-you don't need to add ``sudo`` to all the client commands.
+Starting in version 0.5.3, if you (or your Docker installer) create a
+Unix group called *docker* and add users to it, then the ``docker``
+daemon will make the ownership of the Unix socket read/writable by the
+*docker* group when the daemon starts. The ``docker`` daemon must
+always run as root, but if you run the ``docker`` client as a user in
+the *docker* group then you don't need to add ``sudo`` to all the
+client commands.
+
+**Example:**
 
 .. code-block:: bash
 
-  # Add the docker group
+  # Add the docker group if it doesn't already exist.
   sudo groupadd docker
 
-  # Add the ubuntu user to the docker group
+  # Add the user "ubuntu" to the docker group.
+  # Change the user name to match your preferred user.
   # You may have to logout and log back in again for
-  # this to take effect
+  # this to take effect.
   sudo gpasswd -a ubuntu docker
 
-  # Restart the docker daemon
+  # Restart the docker daemon.
   sudo service docker restart
 
 .. _bind_docker:
@@ -72,7 +90,7 @@ you don't need to add ``sudo`` to all the client commands.
 Bind Docker to another host/port or a Unix socket
 -------------------------------------------------
 
-.. DANGER:: Changing the default ``docker`` daemon binding to a TCP
+.. warning:: Changing the default ``docker`` daemon binding to a TCP
    port or Unix *docker* user group will increase your security risks
    by allowing non-root users to potentially gain *root* access on the
    host (`e.g. #1369
@@ -138,22 +156,19 @@ Listing all running containers
 
   sudo docker ps
 
-Expose a service on a TCP port
+Bind a service on a TCP port
 ------------------------------
 
 .. code-block:: bash
 
-  # Expose port 4444 of this container, and tell netcat to listen on it
+  # Bind port 4444 of this container, and tell netcat to listen on it
   JOB=$(sudo docker run -d -p 4444 ubuntu:12.10 /bin/nc -l 4444)
 
   # Which public port is NATed to my container?
-  PORT=$(sudo docker port $JOB 4444)
+  PORT=$(sudo docker port $JOB 4444 | awk -F: '{ print $2 }')
 
-  # Connect to the public port via the host's public address
-  # Please note that because of how routing works connecting to localhost or 127.0.0.1 $PORT will not work.
-  # Replace *eth0* according to your local interface name.
-  IP=$(ip -o -4 addr list eth0 | perl -n -e 'if (m{inet\s([\d\.]+)\/\d+\s}xms) { print $1 }')
-  echo hello world | nc $IP $PORT
+  # Connect to the public port
+  echo hello world | nc 127.0.0.1 $PORT
 
   # Verify that the network connection worked
   echo "Daemon received: $(sudo docker logs $JOB)"
@@ -183,4 +198,3 @@ You now have a image state from which you can create new instances.
 
 Read more about :ref:`working_with_the_repository` or continue to the
 complete :ref:`cli`
-

docs/sources/use/builder.rst

@@ -15,27 +15,39 @@ commit them along the way, giving you a final image.
 
 .. contents:: Table of Contents
 
+.. _dockerfile_usage:
+
 1. Usage
 ========
 
-To build an image from a source repository, create a description file
-called ``Dockerfile`` at the root of your repository. This file will
-describe the steps to assemble the image.
+To :ref:`build <cli_build>` an image from a source repository, create
+a description file called ``Dockerfile`` at the root of your
+repository. This file will describe the steps to assemble the image.
 
 Then call ``docker build`` with the path of your source repository as
-argument:
+argument (for example, ``.``):
 
     ``sudo docker build .``
 
+The path to the source repository defines where to find the *context*
+of the build. The build is run by the Docker daemon, not by the CLI,
+so the whole context must be transferred to the daemon. The Docker CLI
+reports "Uploading context" when the context is sent to the daemon.
+
 You can specify a repository and tag at which to save the new image if the
 build succeeds:
 
     ``sudo docker build -t shykes/myapp .``
 
-Docker will run your steps one-by-one, committing the result if necessary,
-before finally outputting the ID of your new image.
+The Docker daemon will run your steps one-by-one, committing the
+result if necessary, before finally outputting the ID of your new
+image. The Docker daemon will automatically clean up the context you
+sent.
 
-When you're done with your build, you're ready to look into :ref:`image_push`.
+When you're done with your build, you're ready to look into
+:ref:`image_push`.
+
+.. _dockerfile_format:
 
 2. Format
 =========
@@ -63,12 +75,16 @@ allows statements like:
     # Comment
     RUN echo 'we are running some # of cool things'
 
+.. _dockerfile_instructions:
+
 3. Instructions
 ===============
 
 Here is the set of instructions you can use in a ``Dockerfile`` for
 building images.
 
+.. _dockerfile_from:
+
 3.1 FROM
 --------
 
@@ -94,6 +110,8 @@ output by the commit before each new ``FROM`` command.
 If no ``tag`` is given to the ``FROM`` instruction, ``latest`` is
 assumed. If the used tag does not exist, an error will be returned.
 
+.. _dockerfile_maintainer:
+
 3.2 MAINTAINER
 --------------
 
@@ -102,6 +120,8 @@ assumed. If the used tag does not exist, an error will be returned.
 The ``MAINTAINER`` instruction allows you to set the *Author* field of
 the generated images.
 
+.. _dockerfile_run:
+
 3.3 RUN
 -------
 
@@ -116,6 +136,16 @@ core concepts of Docker where commits are cheap and containers can be
 created from any point in an image's history, much like source
 control.
 
+Known Issues (RUN)
+..................
+
+* :issue:`783` is about file permissions problems that can occur when
+  using the AUFS file system. You might notice it during an attempt to
+  ``rm`` a file, for example. The issue describes a workaround.
+* :issue:`2424` Locale will not be set automatically.
+
+.. _dockerfile_cmd:
+
 3.4 CMD
 -------
 
@@ -159,7 +189,7 @@ array:
 
 If you would like your container to run the same executable every
 time, then you should consider using ``ENTRYPOINT`` in combination
-with ``CMD``. See :ref:`entrypoint_def`.
+with ``CMD``. See :ref:`dockerfile_entrypoint`.
 
 If the user specifies arguments to ``docker run`` then they will
 override the default specified in CMD.
@@ -169,15 +199,19 @@ override the default specified in CMD.
     command and commits the result; ``CMD`` does not execute anything at
     build time, but specifies the intended command for the image.
 
+.. _dockerfile_expose:
+
 3.5 EXPOSE
 ----------
 
     ``EXPOSE <port> [<port>...]``
 
-The ``EXPOSE`` instruction sets ports to be publicly exposed when
-running the image. This is functionally equivalent to running ``docker
-commit -run '{"PortSpecs": ["<port>", "<port2>"]}'`` outside the
-builder. Take a look at :ref:`port_redirection` for more information.
+The ``EXPOSE`` instruction exposes ports for use within links. This is
+functionally equivalent to running ``docker commit -run '{"PortSpecs":
+["<port>", "<port2>"]}'`` outside the builder. Refer to
+:ref:`port_redirection` for detailed information.
+
+.. _dockerfile_env:
 
 3.6 ENV
 -------
@@ -193,6 +227,8 @@ with ``<key>=<value>``
     The environment variables will persist when a container is run
     from the resulting image.
 
+.. _dockerfile_add:
+
 3.7 ADD
 -------
 
@@ -208,8 +244,19 @@ a remote file URL.
 ``<dest>`` is the path at which the source will be copied in the
 destination container.
 
+All new files and directories are created with mode 0755, uid and gid
+0.
+
+.. note::
+   if you build using STDIN (``docker build - < somefile``), there is no build 
+   context, so the Dockerfile can only contain an URL based ADD statement.
+
 The copy obeys the following rules:
 
+* The ``<src>`` path must be inside the *context* of the build; you cannot 
+  ``ADD ../something /something``, because the first step of a 
+  ``docker build`` is to send the context directory (and subdirectories) to 
+  the docker daemon.
 * If ``<src>`` is a URL and ``<dest>`` does not end with a trailing slash,
   then a file is downloaded from the URL and copied to ``<dest>``.
 * If ``<src>`` is a URL and ``<dest>`` does end with a trailing slash,
@@ -220,8 +267,9 @@ The copy obeys the following rules:
   (``http://example.com`` will not work).
 * If ``<src>`` is a directory, the entire directory is copied,
   including filesystem metadata.
-* If ``<src>`` is a tar archive in a recognized compression format
-  (identity, gzip, bzip2 or xz), it is unpacked as a directory.
+* If ``<src>`` is a *local* tar archive in a recognized compression
+  format (identity, gzip, bzip2 or xz) then it is unpacked as a
+  directory. Resources from *remote* URLs are **not** decompressed.
 
   When a directory is copied or unpacked, it has the same behavior as
   ``tar -x``: the result is the union of
@@ -229,7 +277,7 @@ The copy obeys the following rules:
   1. whatever existed at the destination path and
   2. the contents of the source tree,
 
-  with conflicts resolved in favor of 2) on a file-by-file basis.
+  with conflicts resolved in favor of "2." on a file-by-file basis.
 
 * If ``<src>`` is any other kind of file, it is copied individually
   along with its metadata. In this case, if ``<dest>`` ends with a
@@ -237,12 +285,11 @@ The copy obeys the following rules:
   contents of ``<src>`` will be written at ``<dest>/base(<src>)``.
 * If ``<dest>`` does not end with a trailing slash, it will be
   considered a regular file and the contents of ``<src>`` will be
-  written at ``<dst>``.
+  written at ``<dest>``.
 * If ``<dest>`` doesn't exist, it is created along with all missing
-  directories in its path. All new files and directories are created
-  with mode 0755, uid and gid 0.
+  directories in its path.
 
-.. _entrypoint_def:
+.. _dockerfile_entrypoint:
 
 3.8 ENTRYPOINT
 --------------
@@ -291,14 +338,18 @@ this optional but default, you could use a CMD:
     CMD ["-l", "-"]
     ENTRYPOINT ["/usr/bin/wc"]
 
+.. _dockerfile_volume:
 
 3.9 VOLUME
 ----------
 
     ``VOLUME ["/data"]``
 
-The ``VOLUME`` instruction will add one or more new volumes to any
-container created from the image.
+The ``VOLUME`` instruction will create a mount point with the specified name and mark it 
+as holding externally mounted volumes from native host or other containers. For more information/examples 
+and mounting instructions via docker client, refer to :ref:`volume_def` documentation. 
+
+.. _dockerfile_user:
 
 3.10 USER
 ---------
@@ -308,6 +359,8 @@ container created from the image.
 The ``USER`` instruction sets the username or UID to use when running
 the image.
 
+.. _dockerfile_workdir:
+
 3.11 WORKDIR
 ------------
 
@@ -316,6 +369,7 @@ the image.
 The ``WORKDIR`` instruction sets the working directory in which
 the command given by ``CMD`` is executed.
 
+.. _dockerfile_examples:
 
 4. Dockerfile Examples
 ======================

docs/sources/use/host_integration.rst

@@ -29,14 +29,32 @@ Here are a few sample scripts for systemd and upstart to integrate with docker.
 Sample Upstart Script
 ---------------------
 
+In this example we've already created a container to run Redis with an id of
+0a7e070b698b.  To create an upstart script for our container, we create a file
+named ``/etc/init/redis.conf`` and place the following into it:
+
 .. code-block:: bash
 
    description "Redis container"
    author "Me"
-   start on filesystem and started lxc-net and started docker
+   start on filesystem and started docker
    stop on runlevel [!2345]
    respawn
-   exec docker start -a 0a7e070b698b
+   script
+     # Wait for docker to finish starting up first.
+     FILE=/var/run/docker.sock
+     while [ ! -e $FILE ] ; do
+       inotifywait -t 2 -e create $(dirname $FILE)
+     done
+     /usr/bin/docker start -a 0a7e070b698b
+   end script
+
+Next, we have to configure docker so that it's run with the option ``-r=false``.
+Run the following command:
+
+.. code-block:: bash
+
+   $ sudo sh -c "echo 'DOCKER_OPTS=\"-r=false\"' > /etc/default/docker"
 
 
 Sample systemd Script

docs/sources/use/index.rst

@@ -19,3 +19,5 @@ Contents:
    port_redirection
    puppet
    host_integration
+   working_with_volumes
+   working_with_links_names

docs/sources/use/port_redirection.rst

@@ -8,29 +8,136 @@
 Port redirection
 ================
 
-Docker can redirect public TCP and UDP ports to your container, so it can be
-reached over the network.  Port redirection is done on ``docker run``
-using the -p flag.
-
-A port redirect is specified as *PUBLIC:PRIVATE*, where TCP port
-*PUBLIC* will be redirected to TCP port *PRIVATE*. As a special case,
-the public port can be omitted, in which case a random public port
-will be allocated.
+Interacting with a service is commonly done through a connection to a
+port. When this service runs inside a container, one can connect to
+the port after finding the IP address of the container as follows:
 
 .. code-block:: bash
 
-    # A random PUBLIC port is redirected to PRIVATE port 80 on the container
-    sudo docker run -p 80 <image> <cmd>
+    # Find IP address of container with ID <container_id>
+    docker inspect <container_id> | grep IPAddress | cut -d '"' -f 4
 
-    # PUBLIC port 80 is redirected to PRIVATE port 80
-    sudo docker run -p 80:80 <image> <cmd>
+However, this IP address is local to the host system and the container
+port is not reachable by the outside world. Furthermore, even if the
+port is used locally, e.g. by another container, this method is
+tedious as the IP address of the container changes every time it
+starts.
 
-To redirect a UDP port the redirection must be expressed as *PUBLIC:PRIVATE/udp*:
+Docker addresses these two problems and give a simple and robust way
+to access services running inside containers.
+
+To allow non-local clients to reach the service running inside the
+container, Docker provide ways to bind the container port to an
+interface of the host system. To simplify communication between
+containers, Docker provides the linking mechanism.
+
+Binding a port to an host interface
+-----------------------------------
+
+To bind a port of the container to a specific interface of the host
+system, use the ``-p`` parameter of the ``docker run`` command:
 
 .. code-block:: bash
 
-    # PUBLIC port 5300 is redirected to the PRIVATE port 53 using UDP
-    sudo docker run -p 5300:53/udp <image> <cmd>
+    # General syntax
+    docker run -p [([<host_interface>:[host_port]])|(<host_port>):]<container_port>[/udp] <image> <cmd>
 
-Default port redirects can be built into a container with the
-``EXPOSE`` build command.
+When no host interface is provided, the port is bound to all available
+interfaces of the host machine (aka INADDR_ANY, or 0.0.0.0).When no host port is
+provided, one is dynamically allocated. The possible combinations of options for
+TCP port are the following:
+
+.. code-block:: bash
+
+    # Bind TCP port 8080 of the container to TCP port 80 on 127.0.0.1 of the host machine.
+    docker run -p 127.0.0.1:80:8080 <image> <cmd>
+
+    # Bind TCP port 8080 of the container to a dynamically allocated TCP port on 127.0.0.1 of the host machine.
+    docker run -p 127.0.0.1::8080 <image> <cmd>
+
+    # Bind TCP port 8080 of the container to TCP port 80 on all available interfaces of the host machine.
+    docker run -p 80:8080 <image> <cmd>
+
+    # Bind TCP port 8080 of the container to a dynamically allocated TCP port on all available interfaces of the host machine.
+    docker run -p 8080 <image> <cmd>
+
+UDP ports can also be bound by adding a trailing ``/udp``. All the
+combinations described for TCP work. Here is only one example:
+
+.. code-block:: bash
+
+    # Bind UDP port 5353 of the container to UDP port 53 on 127.0.0.1 of the host machine.
+    docker run -p 127.0.0.1:53:5353/udp <image> <cmd>
+
+The command ``docker port`` lists the interface and port on the host
+machine bound to a given container port. It is useful when using
+dynamically allocated ports:
+
+.. code-block:: bash
+
+   # Bind to a dynamically allocated port
+   docker run -p 127.0.0.1::8080 -name dyn-bound <image> <cmd>
+
+   # Lookup the actual port
+   docker port dyn-bound 8080
+   127.0.0.1:49160
+
+
+Linking a container
+-------------------
+
+Communication between two containers can also be established in a
+docker-specific way called linking.
+
+To briefly present the concept of linking, let us consider two
+containers: ``server``, containing the service, and ``client``,
+accessing the service.  Once ``server`` is running, ``client`` is
+started and links to server. Linking sets environment variables in
+``client`` giving it some information about ``server``. In this sense,
+linking is a method of service discovery.
+
+Let us now get back to our topic of interest; communication between
+the two containers. We mentioned that the tricky part about this
+communication was that the IP address of ``server`` was not
+fixed. Therefore, some of the environment variables are going to be
+used to inform ``client`` about this IP address. This process called
+exposure, is possible because ``client`` is started after ``server``
+has been started.
+
+Here is a full example. On ``server``, the port of interest is
+exposed. The exposure is done either through the ``-expose`` parameter
+to the ``docker run`` command, or the ``EXPOSE`` build command in a
+Dockerfile:
+
+.. code-block:: bash
+
+    # Expose port 80
+    docker run -expose 80 -name server <image> <cmd>
+
+The ``client`` then links to the ``server``:
+
+.. code-block:: bash
+
+    # Link
+    docker run -name client -link server:linked-server <image> <cmd>
+
+``client`` locally refers to ``server`` as ``linked-server``. The
+following environment variables, among others, are available on
+``client``:
+
+.. code-block:: bash
+
+    # The default protocol, ip, and port of the service running in the container
+    LINKED-SERVER_PORT=tcp://172.17.0.8:80
+
+    # A specific protocol, ip, and port of various services
+    LINKED-SERVER_PORT_80_TCP=tcp://172.17.0.8:80
+    LINKED-SERVER_PORT_80_TCP_PROTO=tcp
+    LINKED-SERVER_PORT_80_TCP_ADDR=172.17.0.8
+    LINKED-SERVER_PORT_80_TCP_PORT=80
+
+This tells ``client`` that a service is running on port 80 of
+``server`` and that ``server`` is accessible at the IP address
+172.17.0.8
+
+Note: Using the ``-p`` parameter also exposes the port..

docs/sources/use/working_with_links_names.rst

@@ -0,0 +1,104 @@
+:title: Working with Links and Names
+:description: How to create and use links and names
+:keywords: Examples, Usage, links, docker, documentation, examples, names, name, container naming
+
+.. _working_with_links_names:
+
+Working with Links and Names
+============================
+
+From version 0.6.5 you are now able to ``name`` a container and ``link`` it to another
+container by referring to its name. This will create a parent -> child relationship
+where the parent container can see selected information about its child.
+
+.. _run_name:
+
+Container Naming
+----------------
+
+.. versionadded:: v0.6.5
+
+You can now name your container by using the ``-name`` flag. If no name is provided, Docker
+will automatically generate a name. You can see this name using the ``docker ps`` command.
+
+.. code-block:: bash
+
+    # format is "sudo docker run -name <container_name> <image_name> <command>"
+    $ sudo docker run -name test ubuntu /bin/bash
+
+    # the flag "-a" Show all containers. Only running containers are shown by default.
+    $ sudo docker ps -a
+    CONTAINER ID        IMAGE                            COMMAND             CREATED             STATUS              PORTS               NAMES
+    2522602a0d99        ubuntu:12.04                     /bin/bash           14 seconds ago      Exit 0                                  test
+
+.. _run_link:
+
+Links: service discovery for docker
+-----------------------------------
+
+.. versionadded:: v0.6.5
+
+Links allow containers to discover and securely communicate with each other by using the
+flag ``-link name:alias``. Inter-container communication can be disabled with the daemon
+flag ``-icc=false``. With this flag set to false, Container A cannot access Container B
+unless explicitly allowed via a link. This is a huge win for securing your containers.
+When two containers are linked together Docker creates a parent child relationship
+between the containers. The parent container will be able to access information via
+environment variables of the child such as name, exposed ports, IP and other selected
+environment variables.
+
+When linking two containers Docker will use the exposed ports of the container to create
+a secure tunnel for the parent to access. If a database container only exposes port 8080
+then the linked container will only be allowed to access port 8080 and nothing else if
+inter-container communication is set to false.
+
+.. code-block:: bash
+
+    # Example: there is an image called redis-2.6 that exposes the port 6379 and starts redis-server.
+    # Let's name the container as "redis" based on that image and run it as daemon.
+    $ sudo docker run -d -name redis redis-2.6
+
+We can issue all the commands that you would expect using the name "redis"; start, stop,
+attach, using the name for our container. The name also allows us to link other containers
+into this one.
+
+Next, we can start a new web application that has a dependency on Redis and apply a link
+to connect both containers. If you noticed when running our Redis server we did not use
+the -p flag to publish the Redis port to the host system. Redis exposed port 6379 and
+this is all we need to establish a link.
+
+.. code-block:: bash
+
+    # Linking the redis container as a child
+    $ sudo docker run -t -i -link redis:db -name webapp ubuntu bash
+
+When you specified -link redis:db you are telling docker to link the container named redis
+into this new container with the alias db. Environment variables are prefixed with the alias
+so that the parent container can access network and environment information from the containers
+that are linked into it.
+
+If we inspect the environment variables of the second container, we would see all the information
+about the child container.
+
+.. code-block:: bash
+
+    $ root@4c01db0b339c:/# env
+
+    HOSTNAME=4c01db0b339c
+    DB_NAME=/webapp/db
+    TERM=xterm
+    DB_PORT=tcp://172.17.0.8:6379
+    DB_PORT_6379_TCP=tcp://172.17.0.8:6379
+    DB_PORT_6379_TCP_PROTO=tcp
+    DB_PORT_6379_TCP_ADDR=172.17.0.8
+    DB_PORT_6379_TCP_PORT=6379
+    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    PWD=/
+    SHLVL=1
+    HOME=/
+    container=lxc
+    _=/usr/bin/env
+    root@4c01db0b339c:/#
+
+Accessing the network information along with the environment of the child container allows
+us to easily connect to the Redis service on the specific IP and port in the environment.

docs/sources/use/working_with_volumes.rst

@@ -0,0 +1,89 @@
+:title: Working with Volumes
+:description: How to create and share volumes
+:keywords: Examples, Usage, volume, docker, documentation, examples
+
+.. _volume_def:
+
+Data Volume
+===========
+
+.. versionadded:: v0.3.0
+   Data volumes have been available since version 1 of the
+   :doc:`../api/docker_remote_api`
+
+A *data volume* is a specially-designated directory within one or more
+containers that bypasses the :ref:`ufs_def` to provide several useful
+features for persistant or shared data:
+
+* **Data volumes can be shared and reused between containers.** This
+  is the feature that makes data volumes so powerful. You can use it
+  for anything from hot database upgrades to custom backup or
+  replication tools. See the example below.
+* **Changes to a data volume are made directly**, without the overhead
+  of a copy-on-write mechanism. This is good for very large files.
+* **Changes to a data volume will not be included at the next commit**
+  because they are not recorded as regular filesystem changes in the
+  top layer of the :ref:`ufs_def`
+
+Each container can have zero or more data volumes.
+
+Getting Started
+...............
+
+Using data volumes is as simple as adding a new flag: ``-v``. The
+parameter ``-v`` can be used more than once in order to create more
+volumes within the new container. The example below shows the
+instruction to create a container with two new volumes::
+
+  docker run -v /var/volume1 -v /var/volume2 shykes/couchdb
+
+For a Dockerfile, the VOLUME instruction will add one or more new
+volumes to any container created from the image::
+
+  VOLUME ["/var/volume1", "/var/volume2"]
+
+
+Mount Volumes from an Existing Container:
+-----------------------------------------
+
+The command below creates a new container which is runnning as daemon
+``-d`` and with one volume ``/var/lib/couchdb``::
+
+  COUCH1=$(sudo docker run -d -v /var/lib/couchdb shykes/couchdb:2013-05-03)
+
+From the container id of that previous container ``$COUCH1`` it's
+possible to create new container sharing the same volume using the
+parameter ``-volumes-from container_id``::
+
+  COUCH2=$(sudo docker run -d -volumes-from $COUCH1 shykes/couchdb:2013-05-03)
+
+Now, the second container has the all the information from the first volume.
+
+
+Mount a Host Directory as a Container Volume:
+---------------------------------------------
+
+::
+
+  -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro].
+  If "host-dir" is missing, then docker creates a new volume.
+
+This is not available for a Dockerfile due the portability and sharing
+purpose of it. The [host-dir] volumes is something 100% host dependent
+and will break on any other machine.
+
+For example::
+
+  sudo docker run -v /var/logs:/var/host_logs:ro shykes/couchdb:2013-05-03
+
+The command above mounts the host directory ``/var/logs`` into the
+container with read only permissions as ``/var/host_logs``.
+
+.. versionadded:: v0.5.0
+
+Known Issues
+............
+
+* :issue:`2702`: "lxc-start: Permission denied - failed to mount"
+  could indicate a permissions problem with AppArmor. Please see the
+  issue for a workaround.

docs/sources/use/workingwithrepository.rst

@@ -177,6 +177,15 @@ you can push and pull it like any other repository, but it will
 there will be no user name checking performed. Your registry will
 function completely independently from the Central Index.
 
+.. raw:: html
+
+   <iframe width="640" height="360"
+   src="//www.youtube.com/embed/CAewZCBT4PI?rel=0" frameborder="0"
+   allowfullscreen></iframe>
+
+.. seealso:: `Docker Blog: How to use your own registry 
+   <http://blog.docker.io/2013/07/how-to-use-your-own-registry/>`_
+
 Authentication file
 -------------------
 

docs/theme/docker/layout.html

@@ -129,7 +129,8 @@
                 <div class="row footer">
                     <div class="span12 tbox">
                         <div class="tbox">
-                            <p>Docker is an open source project, sponsored by  <a href="https://dotcloud.com">dotCloud</a>, under the <a href="https://github.com/dotcloud/docker/blob/master/LICENSE" title="Docker licence, hosted in the Github repository">apache 2.0 licence</a></p>
+                            <p>Docker is an open source project, sponsored by  <a href="https://www.docker.com">Docker Inc.</a>, under the <a href="https://github.com/dotcloud/docker/blob/master/LICENSE" title="Docker licence, hosted in the Github repository">apache 2.0 licence</a></p>
+                            <p>Documentation proudly hosted by <a href="http://www.readthedocs.org">Read the Docs</a></p>
                         </div>
 
                         <div class="social links">

engine/MAINTAINERS

@@ -0,0 +1 @@
+Solomon Hykes <solomon@dotcloud.com>

engine/engine.go

@@ -0,0 +1,116 @@
+package engine
+
+import (
+	"fmt"
+	"github.com/dotcloud/docker/utils"
+	"log"
+	"os"
+	"runtime"
+	"strings"
+)
+
+type Handler func(*Job) string
+
+var globalHandlers map[string]Handler
+
+func init() {
+	globalHandlers = make(map[string]Handler)
+}
+
+func Register(name string, handler Handler) error {
+	_, exists := globalHandlers[name]
+	if exists {
+		return fmt.Errorf("Can't overwrite global handler for command %s", name)
+	}
+	globalHandlers[name] = handler
+	return nil
+}
+
+// The Engine is the core of Docker.
+// It acts as a store for *containers*, and allows manipulation of these
+// containers by executing *jobs*.
+type Engine struct {
+	root     string
+	handlers map[string]Handler
+	hack     Hack // data for temporary hackery (see hack.go)
+	id       string
+}
+
+func (eng *Engine) Root() string {
+	return eng.root
+}
+
+func (eng *Engine) Register(name string, handler Handler) error {
+	eng.Logf("Register(%s) (handlers=%v)", name, eng.handlers)
+	_, exists := eng.handlers[name]
+	if exists {
+		return fmt.Errorf("Can't overwrite handler for command %s", name)
+	}
+	eng.handlers[name] = handler
+	return nil
+}
+
+// New initializes a new engine managing the directory specified at `root`.
+// `root` is used to store containers and any other state private to the engine.
+// Changing the contents of the root without executing a job will cause unspecified
+// behavior.
+func New(root string) (*Engine, error) {
+	// Check for unsupported architectures
+	if runtime.GOARCH != "amd64" {
+		return nil, fmt.Errorf("The docker runtime currently only supports amd64 (not %s). This will change in the future. Aborting.", runtime.GOARCH)
+	}
+	// Check for unsupported kernel versions
+	// FIXME: it would be cleaner to not test for specific versions, but rather
+	// test for specific functionalities.
+	// Unfortunately we can't test for the feature "does not cause a kernel panic"
+	// without actually causing a kernel panic, so we need this workaround until
+	// the circumstances of pre-3.8 crashes are clearer.
+	// For details see http://github.com/dotcloud/docker/issues/407
+	if k, err := utils.GetKernelVersion(); err != nil {
+		log.Printf("WARNING: %s\n", err)
+	} else {
+		if utils.CompareKernelVersion(k, &utils.KernelVersionInfo{Kernel: 3, Major: 8, Minor: 0}) < 0 {
+			log.Printf("WARNING: You are running linux kernel version %s, which might be unstable running docker. Please upgrade your kernel to 3.8.0.", k.String())
+		}
+	}
+	if err := os.MkdirAll(root, 0700); err != nil && !os.IsExist(err) {
+		return nil, err
+	}
+	eng := &Engine{
+		root:     root,
+		handlers: make(map[string]Handler),
+		id:       utils.RandomString(),
+	}
+	// Copy existing global handlers
+	for k, v := range globalHandlers {
+		eng.handlers[k] = v
+	}
+	return eng, nil
+}
+
+func (eng *Engine) String() string {
+	return fmt.Sprintf("%s|%s", eng.Root(), eng.id[:8])
+}
+
+// Job creates a new job which can later be executed.
+// This function mimics `Command` from the standard os/exec package.
+func (eng *Engine) Job(name string, args ...string) *Job {
+	job := &Job{
+		Eng:    eng,
+		Name:   name,
+		Args:   args,
+		Stdin:  os.Stdin,
+		Stdout: os.Stdout,
+		Stderr: os.Stderr,
+	}
+	handler, exists := eng.handlers[name]
+	if exists {
+		job.handler = handler
+	}
+	return job
+}
+
+func (eng *Engine) Logf(format string, args ...interface{}) (n int, err error) {
+	prefixedFormat := fmt.Sprintf("[%s] %s\n", eng, strings.TrimRight(format, "\n"))
+	return fmt.Fprintf(os.Stderr, prefixedFormat, args...)
+}

engine/engine_test.go

@@ -0,0 +1,55 @@
+package engine
+
+import (
+	"testing"
+)
+
+func TestRegister(t *testing.T) {
+	if err := Register("dummy1", nil); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := Register("dummy1", nil); err == nil {
+		t.Fatalf("Expecting error, got none")
+	}
+
+	eng := newTestEngine(t)
+
+	//Should fail because globan handlers are copied
+	//at the engine creation
+	if err := eng.Register("dummy1", nil); err == nil {
+		t.Fatalf("Expecting error, got none")
+	}
+
+	if err := eng.Register("dummy2", nil); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := eng.Register("dummy2", nil); err == nil {
+		t.Fatalf("Expecting error, got none")
+	}
+}
+
+func TestJob(t *testing.T) {
+	eng := newTestEngine(t)
+	job1 := eng.Job("dummy1", "--level=awesome")
+
+	if job1.handler != nil {
+		t.Fatalf("job1.handler should be empty")
+	}
+
+	h := func(j *Job) string {
+		return j.Name
+	}
+
+	eng.Register("dummy2", h)
+	job2 := eng.Job("dummy2", "--level=awesome")
+
+	if job2.handler == nil {
+		t.Fatalf("job2.handler shouldn't be nil")
+	}
+
+	if job2.handler(job2) != job2.Name {
+		t.Fatalf("handler dummy2 was not found in job2")
+	}
+}

engine/env_test.go

@@ -0,0 +1,123 @@
+package engine
+
+import (
+	"testing"
+)
+
+func TestNewJob(t *testing.T) {
+	job := mkJob(t, "dummy", "--level=awesome")
+	if job.Name != "dummy" {
+		t.Fatalf("Wrong job name: %s", job.Name)
+	}
+	if len(job.Args) != 1 {
+		t.Fatalf("Wrong number of job arguments: %d", len(job.Args))
+	}
+	if job.Args[0] != "--level=awesome" {
+		t.Fatalf("Wrong job arguments: %s", job.Args[0])
+	}
+}
+
+func TestSetenv(t *testing.T) {
+	job := mkJob(t, "dummy")
+	job.Setenv("foo", "bar")
+	if val := job.Getenv("foo"); val != "bar" {
+		t.Fatalf("Getenv returns incorrect value: %s", val)
+	}
+
+	job.Setenv("bar", "")
+	if val := job.Getenv("bar"); val != "" {
+		t.Fatalf("Getenv returns incorrect value: %s", val)
+	}
+	if val := job.Getenv("nonexistent"); val != "" {
+		t.Fatalf("Getenv returns incorrect value: %s", val)
+	}
+}
+
+func TestSetenvBool(t *testing.T) {
+	job := mkJob(t, "dummy")
+	job.SetenvBool("foo", true)
+	if val := job.GetenvBool("foo"); !val {
+		t.Fatalf("GetenvBool returns incorrect value: %b", val)
+	}
+
+	job.SetenvBool("bar", false)
+	if val := job.GetenvBool("bar"); val {
+		t.Fatalf("GetenvBool returns incorrect value: %b", val)
+	}
+
+	if val := job.GetenvBool("nonexistent"); val {
+		t.Fatalf("GetenvBool returns incorrect value: %b", val)
+	}
+}
+
+func TestSetenvInt(t *testing.T) {
+	job := mkJob(t, "dummy")
+
+	job.SetenvInt("foo", -42)
+	if val := job.GetenvInt("foo"); val != -42 {
+		t.Fatalf("GetenvInt returns incorrect value: %d", val)
+	}
+
+	job.SetenvInt("bar", 42)
+	if val := job.GetenvInt("bar"); val != 42 {
+		t.Fatalf("GetenvInt returns incorrect value: %d", val)
+	}
+	if val := job.GetenvInt("nonexistent"); val != -1 {
+		t.Fatalf("GetenvInt returns incorrect value: %d", val)
+	}
+}
+
+func TestSetenvList(t *testing.T) {
+	job := mkJob(t, "dummy")
+
+	job.SetenvList("foo", []string{"bar"})
+	if val := job.GetenvList("foo"); len(val) != 1 || val[0] != "bar" {
+		t.Fatalf("GetenvList returns incorrect value: %v", val)
+	}
+
+	job.SetenvList("bar", nil)
+	if val := job.GetenvList("bar"); val != nil {
+		t.Fatalf("GetenvList returns incorrect value: %v", val)
+	}
+	if val := job.GetenvList("nonexistent"); val != nil {
+		t.Fatalf("GetenvList returns incorrect value: %v", val)
+	}
+}
+
+func TestImportEnv(t *testing.T) {
+	type dummy struct {
+		DummyInt         int
+		DummyStringArray []string
+	}
+
+	job := mkJob(t, "dummy")
+	if err := job.ImportEnv(&dummy{42, []string{"foo", "bar"}}); err != nil {
+		t.Fatal(err)
+	}
+
+	dmy := dummy{}
+	if err := job.ExportEnv(&dmy); err != nil {
+		t.Fatal(err)
+	}
+
+	if dmy.DummyInt != 42 {
+		t.Fatalf("Expected 42, got %d", dmy.DummyInt)
+	}
+
+	if len(dmy.DummyStringArray) != 2 || dmy.DummyStringArray[0] != "foo" || dmy.DummyStringArray[1] != "bar" {
+		t.Fatalf("Expected {foo, bar}, got %v", dmy.DummyStringArray)
+	}
+
+}
+
+func TestEnviron(t *testing.T) {
+	job := mkJob(t, "dummy")
+	job.Setenv("foo", "bar")
+	val, exists := job.Environ()["foo"]
+	if !exists {
+		t.Fatalf("foo not found in the environ")
+	}
+	if val != "bar" {
+		t.Fatalf("bar not found in the environ")
+	}
+}

engine/hack.go

@@ -0,0 +1,21 @@
+package engine
+
+type Hack map[string]interface{}
+
+func (eng *Engine) Hack_GetGlobalVar(key string) interface{} {
+	if eng.hack == nil {
+		return nil
+	}
+	val, exists := eng.hack[key]
+	if !exists {
+		return nil
+	}
+	return val
+}
+
+func (eng *Engine) Hack_SetGlobalVar(key string, val interface{}) {
+	if eng.hack == nil {
+		eng.hack = make(Hack)
+	}
+	eng.hack[key] = val
+}

engine/helpers_test.go

@@ -0,0 +1,38 @@
+package engine
+
+import (
+	"fmt"
+	"github.com/dotcloud/docker/utils"
+	"io/ioutil"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+var globalTestID string
+
+func newTestEngine(t *testing.T) *Engine {
+	// Use the caller function name as a prefix.
+	// This helps trace temp directories back to their test.
+	pc, _, _, _ := runtime.Caller(1)
+	callerLongName := runtime.FuncForPC(pc).Name()
+	parts := strings.Split(callerLongName, ".")
+	callerShortName := parts[len(parts)-1]
+	if globalTestID == "" {
+		globalTestID = utils.RandomString()[:4]
+	}
+	prefix := fmt.Sprintf("docker-test%s-%s-", globalTestID, callerShortName)
+	root, err := ioutil.TempDir("", prefix)
+	if err != nil {
+		t.Fatal(err)
+	}
+	eng, err := New(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return eng
+}
+
+func mkJob(t *testing.T, name string, args ...string) *Job {
+	return newTestEngine(t).Job(name, args...)
+}

engine/job.go

@@ -0,0 +1,342 @@
+package engine
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"io/ioutil"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+)
+
+// A job is the fundamental unit of work in the docker engine.
+// Everything docker can do should eventually be exposed as a job.
+// For example: execute a process in a container, create a new container,
+// download an archive from the internet, serve the http api, etc.
+//
+// The job API is designed after unix processes: a job has a name, arguments,
+// environment variables, standard streams for input, output and error, and
+// an exit status which can indicate success (0) or error (anything else).
+//
+// One slight variation is that jobs report their status as a string. The
+// string "0" indicates success, and any other strings indicates an error.
+// This allows for richer error reporting.
+//
+type Job struct {
+	Eng     *Engine
+	Name    string
+	Args    []string
+	env     []string
+	Stdin   io.Reader
+	Stdout  io.Writer
+	Stderr  io.Writer
+	handler func(*Job) string
+	status  string
+	onExit  []func()
+}
+
+// Run executes the job and blocks until the job completes.
+// If the job returns a failure status, an error is returned
+// which includes the status.
+func (job *Job) Run() error {
+	defer func() {
+		var wg sync.WaitGroup
+		for _, f := range job.onExit {
+			wg.Add(1)
+			go func(f func()) {
+				f()
+				wg.Done()
+			}(f)
+		}
+		wg.Wait()
+	}()
+	if job.Stdout != nil && job.Stdout != os.Stdout {
+		job.Stdout = io.MultiWriter(job.Stdout, os.Stdout)
+	}
+	if job.Stderr != nil && job.Stderr != os.Stderr {
+		job.Stderr = io.MultiWriter(job.Stderr, os.Stderr)
+	}
+	job.Eng.Logf("+job %s", job.CallString())
+	defer func() {
+		job.Eng.Logf("-job %s%s", job.CallString(), job.StatusString())
+	}()
+	if job.handler == nil {
+		job.status = "command not found"
+	} else {
+		job.status = job.handler(job)
+	}
+	if job.status != "0" {
+		return fmt.Errorf("%s: %s", job.Name, job.status)
+	}
+	return nil
+}
+
+func (job *Job) StdoutParseLines(dst *[]string, limit int) {
+	job.parseLines(job.StdoutPipe(), dst, limit)
+}
+
+func (job *Job) StderrParseLines(dst *[]string, limit int) {
+	job.parseLines(job.StderrPipe(), dst, limit)
+}
+
+func (job *Job) parseLines(src io.Reader, dst *[]string, limit int) {
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		scanner := bufio.NewScanner(src)
+		for scanner.Scan() {
+			// If the limit is reached, flush the rest of the source and return
+			if limit > 0 && len(*dst) >= limit {
+				io.Copy(ioutil.Discard, src)
+				return
+			}
+			line := scanner.Text()
+			// Append the line (with delimitor removed)
+			*dst = append(*dst, line)
+		}
+	}()
+	job.onExit = append(job.onExit, wg.Wait)
+}
+
+func (job *Job) StdoutParseString(dst *string) {
+	lines := make([]string, 0, 1)
+	job.StdoutParseLines(&lines, 1)
+	job.onExit = append(job.onExit, func() {
+		if len(lines) >= 1 {
+			*dst = lines[0]
+		}
+	})
+}
+
+func (job *Job) StderrParseString(dst *string) {
+	lines := make([]string, 0, 1)
+	job.StderrParseLines(&lines, 1)
+	job.onExit = append(job.onExit, func() { *dst = lines[0] })
+}
+
+func (job *Job) StdoutPipe() io.ReadCloser {
+	r, w := io.Pipe()
+	job.Stdout = w
+	job.onExit = append(job.onExit, func() { w.Close() })
+	return r
+}
+
+func (job *Job) StderrPipe() io.ReadCloser {
+	r, w := io.Pipe()
+	job.Stderr = w
+	job.onExit = append(job.onExit, func() { w.Close() })
+	return r
+}
+
+func (job *Job) CallString() string {
+	return fmt.Sprintf("%s(%s)", job.Name, strings.Join(job.Args, ", "))
+}
+
+func (job *Job) StatusString() string {
+	// FIXME: if a job returns the empty string, it will be printed
+	// as not having returned.
+	// (this only affects String which is a convenience function).
+	if job.status != "" {
+		var okerr string
+		if job.status == "0" {
+			okerr = "OK"
+		} else {
+			okerr = "ERR"
+		}
+		return fmt.Sprintf(" = %s (%s)", okerr, job.status)
+	}
+	return ""
+}
+
+// String returns a human-readable description of `job`
+func (job *Job) String() string {
+	return fmt.Sprintf("%s.%s%s", job.Eng, job.CallString(), job.StatusString())
+}
+
+func (job *Job) Getenv(key string) (value string) {
+	for _, kv := range job.env {
+		if strings.Index(kv, "=") == -1 {
+			continue
+		}
+		parts := strings.SplitN(kv, "=", 2)
+		if parts[0] != key {
+			continue
+		}
+		if len(parts) < 2 {
+			value = ""
+		} else {
+			value = parts[1]
+		}
+	}
+	return
+}
+
+func (job *Job) GetenvBool(key string) (value bool) {
+	s := strings.ToLower(strings.Trim(job.Getenv(key), " \t"))
+	if s == "" || s == "0" || s == "no" || s == "false" || s == "none" {
+		return false
+	}
+	return true
+}
+
+func (job *Job) SetenvBool(key string, value bool) {
+	if value {
+		job.Setenv(key, "1")
+	} else {
+		job.Setenv(key, "0")
+	}
+}
+
+func (job *Job) GetenvInt(key string) int64 {
+	s := strings.Trim(job.Getenv(key), " \t")
+	val, err := strconv.ParseInt(s, 10, 64)
+	if err != nil {
+		return -1
+	}
+	return val
+}
+
+func (job *Job) SetenvInt(key string, value int64) {
+	job.Setenv(key, fmt.Sprintf("%d", value))
+}
+
+// Returns nil if key not found
+func (job *Job) GetenvList(key string) []string {
+	sval := job.Getenv(key)
+	if sval == "" {
+		return nil
+	}
+	l := make([]string, 0, 1)
+	if err := json.Unmarshal([]byte(sval), &l); err != nil {
+		l = append(l, sval)
+	}
+	return l
+}
+
+func (job *Job) SetenvJson(key string, value interface{}) error {
+	sval, err := json.Marshal(value)
+	if err != nil {
+		return err
+	}
+	job.Setenv(key, string(sval))
+	return nil
+}
+
+func (job *Job) SetenvList(key string, value []string) error {
+	return job.SetenvJson(key, value)
+}
+
+func (job *Job) Setenv(key, value string) {
+	job.env = append(job.env, key+"="+value)
+}
+
+// DecodeEnv decodes `src` as a json dictionary, and adds
+// each decoded key-value pair to the environment.
+//
+// If `src` cannot be decoded as a json dictionary, an error
+// is returned.
+func (job *Job) DecodeEnv(src io.Reader) error {
+	m := make(map[string]interface{})
+	if err := json.NewDecoder(src).Decode(&m); err != nil {
+		return err
+	}
+	for k, v := range m {
+		// FIXME: we fix-convert float values to int, because
+		// encoding/json decodes integers to float64, but cannot encode them back.
+		// (See http://golang.org/src/pkg/encoding/json/decode.go#L46)
+		if fval, ok := v.(float64); ok {
+			job.SetenvInt(k, int64(fval))
+		} else if sval, ok := v.(string); ok {
+			job.Setenv(k, sval)
+		} else if val, err := json.Marshal(v); err == nil {
+			job.Setenv(k, string(val))
+		} else {
+			job.Setenv(k, fmt.Sprintf("%v", v))
+		}
+	}
+	return nil
+}
+
+func (job *Job) EncodeEnv(dst io.Writer) error {
+	m := make(map[string]interface{})
+	for k, v := range job.Environ() {
+		var val interface{}
+		if err := json.Unmarshal([]byte(v), &val); err == nil {
+			// FIXME: we fix-convert float values to int, because
+			// encoding/json decodes integers to float64, but cannot encode them back.
+			// (See http://golang.org/src/pkg/encoding/json/decode.go#L46)
+			if fval, isFloat := val.(float64); isFloat {
+				val = int(fval)
+			}
+			m[k] = val
+		} else {
+			m[k] = v
+		}
+	}
+	if err := json.NewEncoder(dst).Encode(&m); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (job *Job) ExportEnv(dst interface{}) (err error) {
+	defer func() {
+		if err != nil {
+			err = fmt.Errorf("ExportEnv %s", err)
+		}
+	}()
+	var buf bytes.Buffer
+	// step 1: encode/marshal the env to an intermediary json representation
+	if err := job.EncodeEnv(&buf); err != nil {
+		return err
+	}
+	// step 2: decode/unmarshal the intermediary json into the destination object
+	if err := json.NewDecoder(&buf).Decode(dst); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (job *Job) ImportEnv(src interface{}) (err error) {
+	defer func() {
+		if err != nil {
+			err = fmt.Errorf("ImportEnv: %s", err)
+		}
+	}()
+	var buf bytes.Buffer
+	if err := json.NewEncoder(&buf).Encode(src); err != nil {
+		return err
+	}
+	if err := job.DecodeEnv(&buf); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (job *Job) Environ() map[string]string {
+	m := make(map[string]string)
+	for _, kv := range job.env {
+		parts := strings.SplitN(kv, "=", 2)
+		m[parts[0]] = parts[1]
+	}
+	return m
+}
+
+func (job *Job) Logf(format string, args ...interface{}) (n int, err error) {
+	prefixedFormat := fmt.Sprintf("[%s] %s\n", job, strings.TrimRight(format, "\n"))
+	return fmt.Fprintf(job.Stderr, prefixedFormat, args...)
+}
+
+func (job *Job) Printf(format string, args ...interface{}) (n int, err error) {
+	return fmt.Fprintf(job.Stdout, format, args...)
+}
+
+func (job *Job) Errorf(format string, args ...interface{}) (n int, err error) {
+	return fmt.Fprintf(job.Stderr, format, args...)
+
+}

gograph/gograph.go

@@ -4,6 +4,7 @@ import (
 	"database/sql"
 	"fmt"
 	"path"
+	"sync"
 )
 
 const (
@@ -47,6 +48,7 @@ type WalkFunc func(fullPath string, entity *Entity) error
 // Graph database for storing entities and their relationships
 type Database struct {
 	conn *sql.DB
+	mux  sync.RWMutex
 }
 
 // Create a new graph database initialized with a root entity
@@ -54,7 +56,7 @@ func NewDatabase(conn *sql.DB, init bool) (*Database, error) {
 	if conn == nil {
 		return nil, fmt.Errorf("Database connection cannot be nil")
 	}
-	db := &Database{conn}
+	db := &Database{conn: conn}
 
 	if init {
 		if _, err := conn.Exec(createEntityTable); err != nil {
@@ -99,7 +101,9 @@ func (db *Database) Close() error {
 
 // Set the entity id for a given path
 func (db *Database) Set(fullPath, id string) (*Entity, error) {
-	// FIXME: is rollback implicit when closing the connection?
+	db.mux.Lock()
+	defer db.mux.Unlock()
+
 	rollback := func() {
 		db.conn.Exec("ROLLBACK")
 	}
@@ -134,7 +138,14 @@ func (db *Database) Set(fullPath, id string) (*Entity, error) {
 
 // Return true if a name already exists in the database
 func (db *Database) Exists(name string) bool {
-	return db.Get(name) != nil
+	db.mux.RLock()
+	defer db.mux.RUnlock()
+
+	e, err := db.get(name)
+	if err != nil {
+		return false
+	}
+	return e != nil
 }
 
 func (db *Database) setEdge(parentPath, name string, e *Entity) error {
@@ -161,6 +172,9 @@ func (db *Database) RootEntity() *Entity {
 
 // Return the entity for a given path
 func (db *Database) Get(name string) *Entity {
+	db.mux.RLock()
+	defer db.mux.RUnlock()
+
 	e, err := db.get(name)
 	if err != nil {
 		return nil
@@ -196,23 +210,36 @@ func (db *Database) get(name string) (*Entity, error) {
 // List all entities by from the name
 // The key will be the full path of the entity
 func (db *Database) List(name string, depth int) Entities {
+	db.mux.RLock()
+	defer db.mux.RUnlock()
+
 	out := Entities{}
 	e, err := db.get(name)
 	if err != nil {
 		return out
 	}
-	for c := range db.children(e, name, depth) {
+
+	children, err := db.children(e, name, depth, nil)
+	if err != nil {
+		return out
+	}
+
+	for _, c := range children {
 		out[c.FullPath] = c.Entity
 	}
 	return out
 }
 
+// Walk through the child graph of an entity, calling walkFunc for each child entity.
+// It is safe for walkFunc to call graph functions.
 func (db *Database) Walk(name string, walkFunc WalkFunc, depth int) error {
-	e, err := db.get(name)
+	children, err := db.Children(name, depth)
 	if err != nil {
 		return err
 	}
-	for c := range db.children(e, name, depth) {
+
+	// Note: the database lock must not be held while calling walkFunc
+	for _, c := range children {
 		if err := walkFunc(c.FullPath, c.Entity); err != nil {
 			return err
 		}
@@ -220,8 +247,24 @@ func (db *Database) Walk(name string, walkFunc WalkFunc, depth int) error {
 	return nil
 }
 
+// Return the children of the specified entity
+func (db *Database) Children(name string, depth int) ([]WalkMeta, error) {
+	db.mux.RLock()
+	defer db.mux.RUnlock()
+
+	e, err := db.get(name)
+	if err != nil {
+		return nil, err
+	}
+
+	return db.children(e, name, depth, nil)
+}
+
 // Return the refrence count for a specified id
 func (db *Database) Refs(id string) int {
+	db.mux.RLock()
+	defer db.mux.RUnlock()
+
 	var count int
 	if err := db.conn.QueryRow("SELECT COUNT(*) FROM edge WHERE entity_id = ?;", id).Scan(&count); err != nil {
 		return 0
@@ -231,6 +274,9 @@ func (db *Database) Refs(id string) int {
 
 // Return all the id's path references
 func (db *Database) RefPaths(id string) Edges {
+	db.mux.RLock()
+	defer db.mux.RUnlock()
+
 	refs := Edges{}
 
 	rows, err := db.conn.Query("SELECT name, parent_id FROM edge WHERE entity_id = ?;", id)
@@ -256,6 +302,9 @@ func (db *Database) RefPaths(id string) Edges {
 
 // Delete the reference to an entity at a given path
 func (db *Database) Delete(name string) error {
+	db.mux.Lock()
+	defer db.mux.Unlock()
+
 	if name == "/" {
 		return fmt.Errorf("Cannot delete root entity")
 	}
@@ -276,6 +325,9 @@ func (db *Database) Delete(name string) error {
 // Walk the graph to make sure all references to the entity
 // are removed and return the number of references removed
 func (db *Database) Purge(id string) (int, error) {
+	db.mux.Lock()
+	defer db.mux.Unlock()
+
 	rollback := func() {
 		db.conn.Exec("ROLLBACK")
 	}
@@ -310,6 +362,9 @@ func (db *Database) Purge(id string) (int, error) {
 
 // Rename an edge for a given path
 func (db *Database) Rename(currentName, newName string) error {
+	db.mux.Lock()
+	defer db.mux.Unlock()
+
 	parentPath, name := splitPath(currentName)
 	newParentPath, newEdgeName := splitPath(newName)
 
@@ -343,56 +398,51 @@ type WalkMeta struct {
 	Edge     *Edge
 }
 
-func (db *Database) children(e *Entity, name string, depth int) <-chan WalkMeta {
-	out := make(chan WalkMeta)
+func (db *Database) children(e *Entity, name string, depth int, entities []WalkMeta) ([]WalkMeta, error) {
 	if e == nil {
-		close(out)
-		return out
+		return entities, nil
 	}
 
-	go func() {
-		rows, err := db.conn.Query("SELECT entity_id, name FROM edge where parent_id = ?;", e.id)
-		if err != nil {
-			close(out)
+	rows, err := db.conn.Query("SELECT entity_id, name FROM edge where parent_id = ?;", e.id)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var entityId, entityName string
+		if err := rows.Scan(&entityId, &entityName); err != nil {
+			return nil, err
+		}
+		child := &Entity{entityId}
+		edge := &Edge{
+			ParentID: e.id,
+			Name:     entityName,
+			EntityID: child.id,
 		}
-		defer rows.Close()
 
-		for rows.Next() {
-			var entityId, entityName string
-			if err := rows.Scan(&entityId, &entityName); err != nil {
-				// Log error
-				continue
-			}
-			child := &Entity{entityId}
-			edge := &Edge{
-				ParentID: e.id,
-				Name:     entityName,
-				EntityID: child.id,
-			}
+		meta := WalkMeta{
+			Parent:   e,
+			Entity:   child,
+			FullPath: path.Join(name, edge.Name),
+			Edge:     edge,
+		}
 
-			meta := WalkMeta{
-				Parent:   e,
-				Entity:   child,
-				FullPath: path.Join(name, edge.Name),
-				Edge:     edge,
-			}
+		entities = append(entities, meta)
 
-			out <- meta
-			if depth == 0 {
-				continue
-			}
+		if depth != 0 {
 			nDepth := depth
 			if depth != -1 {
 				nDepth -= 1
 			}
-			sc := db.children(child, meta.FullPath, nDepth)
-			for c := range sc {
-				out <- c
+			entities, err = db.children(child, meta.FullPath, nDepth, entities)
+			if err != nil {
+				return nil, err
 			}
 		}
-		close(out)
-	}()
-	return out
+	}
+
+	return entities, nil
 }
 
 // Return the entity based on the parent path and name

gograph/gograph_test.go

@@ -3,6 +3,7 @@ package gograph
 import (
 	_ "code.google.com/p/gosqlite/sqlite3"
 	"database/sql"
+	"fmt"
 	"os"
 	"path"
 	"strconv"
@@ -501,3 +502,39 @@ func TestGetNameWithTrailingSlash(t *testing.T) {
 		t.Fatalf("Entity should not be nil")
 	}
 }
+
+func TestConcurrentWrites(t *testing.T) {
+	db, dbpath := newTestDb(t)
+	defer destroyTestDb(dbpath)
+
+	errs := make(chan error, 2)
+
+	save := func(name string, id string) {
+		if _, err := db.Set(fmt.Sprintf("/%s", name), id); err != nil {
+			errs <- err
+		}
+		errs <- nil
+	}
+	purge := func(id string) {
+		if _, err := db.Purge(id); err != nil {
+			errs <- err
+		}
+		errs <- nil
+	}
+
+	save("/1", "1")
+
+	go purge("1")
+	go save("/2", "2")
+
+	any := false
+	for i := 0; i < 2; i++ {
+		if err := <-errs; err != nil {
+			any = true
+			t.Log(err)
+		}
+	}
+	if any {
+		t.Fatal()
+	}
+}

graph.go

@@ -2,6 +2,7 @@ package docker
 
 import (
 	"fmt"
+	"github.com/dotcloud/docker/archive"
 	"github.com/dotcloud/docker/utils"
 	"io"
 	"io/ioutil"
@@ -94,7 +95,7 @@ func (graph *Graph) Get(name string) (*Image, error) {
 }
 
 // Create creates a new image and registers it in the graph.
-func (graph *Graph) Create(layerData Archive, container *Container, comment, author string, config *Config) (*Image, error) {
+func (graph *Graph) Create(layerData archive.Archive, container *Container, comment, author string, config *Config) (*Image, error) {
 	img := &Image{
 		ID:            GenerateID(),
 		Comment:       comment,
@@ -117,7 +118,7 @@ func (graph *Graph) Create(layerData Archive, container *Container, comment, aut
 
 // Register imports a pre-existing image into the graph.
 // FIXME: pass img as first argument
-func (graph *Graph) Register(jsonData []byte, layerData Archive, img *Image) error {
+func (graph *Graph) Register(jsonData []byte, layerData archive.Archive, img *Image) error {
 	if err := ValidateID(img.ID); err != nil {
 		return err
 	}
@@ -146,7 +147,7 @@ func (graph *Graph) Register(jsonData []byte, layerData Archive, img *Image) err
 //   The archive is stored on disk and will be automatically deleted as soon as has been read.
 //   If output is not nil, a human-readable progress bar will be written to it.
 //   FIXME: does this belong in Graph? How about MktempFile, let the caller use it for archives?
-func (graph *Graph) TempLayerArchive(id string, compression Compression, sf *utils.StreamFormatter, output io.Writer) (*TempArchive, error) {
+func (graph *Graph) TempLayerArchive(id string, compression archive.Compression, sf *utils.StreamFormatter, output io.Writer) (*archive.TempArchive, error) {
 	image, err := graph.Get(id)
 	if err != nil {
 		return nil, err
@@ -155,11 +156,11 @@ func (graph *Graph) TempLayerArchive(id string, compression Compression, sf *uti
 	if err != nil {
 		return nil, err
 	}
-	archive, err := image.TarLayer(compression)
+	a, err := image.TarLayer(compression)
 	if err != nil {
 		return nil, err
 	}
-	return NewTempArchive(utils.ProgressReader(ioutil.NopCloser(archive), 0, output, sf.FormatProgress("", "Buffering to disk", "%v/%v (%v)"), sf, true), tmp.Root)
+	return archive.NewTempArchive(utils.ProgressReader(ioutil.NopCloser(a), 0, output, sf.FormatProgress("", "Buffering to disk", "%v/%v (%v)"), sf, true), tmp.Root)
 }
 
 // Mktemp creates a temporary sub-directory inside the graph's filesystem.
@@ -201,6 +202,7 @@ func (graph *Graph) getDockerInitLayer() (string, error) {
 		"/proc":            "dir",
 		"/sys":             "dir",
 		"/.dockerinit":     "file",
+		"/.dockerenv":      "file",
 		"/etc/resolv.conf": "file",
 		"/etc/hosts":       "file",
 		"/etc/hostname":    "file",
@@ -218,12 +220,11 @@ func (graph *Graph) getDockerInitLayer() (string, error) {
 					if err := os.MkdirAll(path.Join(initLayer, path.Dir(pth)), 0755); err != nil {
 						return "", err
 					}
-
-					if f, err := os.OpenFile(path.Join(initLayer, pth), os.O_CREATE, 0755); err != nil {
+					f, err := os.OpenFile(path.Join(initLayer, pth), os.O_CREATE, 0755)
+					if err != nil {
 						return "", err
-					} else {
-						f.Close()
 					}
+					f.Close()
 				}
 			} else {
 				return "", err

graph_test.go

@@ -4,11 +4,11 @@ import (
 	"archive/tar"
 	"bytes"
 	"errors"
+	"github.com/dotcloud/docker/archive"
 	"github.com/dotcloud/docker/utils"
 	"io"
 	"io/ioutil"
 	"os"
-	"path"
 	"testing"
 	"time"
 )
@@ -120,41 +120,6 @@ func TestRegister(t *testing.T) {
 	}
 }
 
-func TestMount(t *testing.T) {
-	graph := tempGraph(t)
-	defer os.RemoveAll(graph.Root)
-	archive, err := fakeTar()
-	if err != nil {
-		t.Fatal(err)
-	}
-	image, err := graph.Create(archive, nil, "Testing", "", nil)
-	if err != nil {
-		t.Fatal(err)
-	}
-	tmp, err := ioutil.TempDir("", "docker-test-graph-mount-")
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer os.RemoveAll(tmp)
-	rootfs := path.Join(tmp, "rootfs")
-	if err := os.MkdirAll(rootfs, 0700); err != nil {
-		t.Fatal(err)
-	}
-	rw := path.Join(tmp, "rw")
-	if err := os.MkdirAll(rw, 0700); err != nil {
-		t.Fatal(err)
-	}
-	if err := image.Mount(rootfs, rw); err != nil {
-		t.Fatal(err)
-	}
-	// FIXME: test for mount contents
-	defer func() {
-		if err := Unmount(rootfs); err != nil {
-			t.Error(err)
-		}
-	}()
-}
-
 // Test that an image can be deleted by its shorthand prefix
 func TestDeletePrefix(t *testing.T) {
 	graph := tempGraph(t)
@@ -301,7 +266,7 @@ func tempGraph(t *testing.T) *Graph {
 	return graph
 }
 
-func testArchive(t *testing.T) Archive {
+func testArchive(t *testing.T) archive.Archive {
 	archive, err := fakeTar()
 	if err != nil {
 		t.Fatal(err)

hack/RELEASE-CHECKLIST.md

@@ -9,7 +9,8 @@ to keep it up-to-date.
 ### 1. Pull from master and create a release branch
 
 ```bash
-git checkout master
+export VERSION=vXXX
+git checkout release
 git pull
 git checkout -b bump_$VERSION
 ```
@@ -55,7 +56,9 @@ EXAMPLES:
 
 ### 4. Run all tests
 
-FIXME
+```bash
+docker run -privileged -lxc-conf=lxc.aa_profile=unconfined docker hack/make.sh test
+```
 
 ### 5. Test the docs
 
@@ -66,21 +69,17 @@ the docs are in ``docs/README.md``
 ### 6. Commit and create a pull request to the "release" branch
 
 ```bash
-git add CHANGELOG.md
+git add VERSION CHANGELOG.md
 git commit -m "Bump version to $VERSION"
 git push origin bump_$VERSION
 ```
 
 ### 7. Get 2 other maintainers to validate the pull request
 
-### 8. Merge the pull request and apply tags
+### 8. Apply tag
 
 ```bash
-git checkout release
-git merge bump_$VERSION
 git tag -a v$VERSION # Don't forget the v!
-git tag -f -a latest
-git push
 git push --tags
 ```
 
@@ -90,28 +89,35 @@ should see the updated docs 5-10 minutes after the merge. The docs
 will appear on http://docs.docker.io/. For more information about
 documentation releases, see ``docs/README.md``
 
-### 9. Publish binaries
+### 9. Go to github to merge the bump_$VERSION into release
+
+### 10. Publish binaries
 
 To run this you will need access to the release credentials.
 Get them from [the infrastructure maintainers](
 https://github.com/dotcloud/docker/blob/master/hack/infrastructure/MAINTAINERS).
 
 ```bash
+git checkout release
+git fetch
+git reset --hard origin/release
 docker build -t docker .
 docker run  \
-	-e AWS_S3_BUCKET=get-nightly.docker.io \
-	-e AWS_ACCESS_KEY=$(cat ~/.aws/access_key) \
-	-e AWS_SECRET_KEY=$(cat ~/.aws/secret_key) \
-	-e GPG_PASSPHRASE=supersecretsesame \
-	docker
-	hack/release.sh
+       -e AWS_S3_BUCKET=test.docker.io \
+       -e AWS_ACCESS_KEY=$(cat ~/.aws/access_key) \
+       -e AWS_SECRET_KEY=$(cat ~/.aws/secret_key) \
+       -e GPG_PASSPHRASE=supersecretsesame \
+       -privileged -lxc-conf=lxc.aa_profile=unconfined \
+       -t -i \
+       docker \
+       hack/release.sh
 ```
 
 It will build and upload the binaries on the specified bucket (you should
-use get-nightly.docker.io for general testing, and once everything is fine,
+use test.docker.io for general testing, and once everything is fine,
 switch to get.docker.io).
 
 
-### 10. Rejoice!
+### 11. Rejoice!
 
 Congratulations! You're done.

hack/ROADMAP.md

@@ -5,7 +5,7 @@ It is a curated selection of planned improvements which are either important, di
 
 For a more complete view of planned and requested improvements, see [the Github issues](https://github.com/dotcloud/docker/issues).
 
-Tu suggest changes to the roadmap, including additions, please write the change as if it were already in effect, and make a pull request.
+To suggest changes to the roadmap, including additions, please write the change as if it were already in effect, and make a pull request.
 
 
 ## Container wiring and service discovery

hack/dind

@@ -21,6 +21,14 @@ mountpoint -q $CGROUP ||
 		exit 1
 	}
 
+if [ -d /sys/kernel/security ] && ! mountpoint -q /sys/kernel/security
+then
+    mount -t securityfs none /sys/kernel/security || {
+	echo "Could not mount /sys/kernel/security."
+	echo "AppArmor detection and -privileged mode might break."
+    }
+fi
+
 # Mount the cgroup hierarchies exactly as they are in the parent system.
 for SUBSYS in $(cut -d: -f2 /proc/1/cgroup)
 do

hack/infrastructure/docker-ci/Dockerfile

@@ -1,14 +1,16 @@
-# VERSION:        0.22
-# DOCKER-VERSION  0.6.3
-# AUTHOR:         Daniel Mizyrycki <daniel@dotcloud.com>
-# DESCRIPTION:    Deploy docker-ci on Amazon EC2
+# VERSION:        0.25
+# DOCKER-VERSION  0.6.6
+# AUTHOR:         Daniel Mizyrycki <daniel@docker.com>
+# DESCRIPTION:    Deploy docker-ci on Digital Ocean
 # COMMENTS:
 #     CONFIG_JSON is an environment variable json string loaded as:
 #
 # export CONFIG_JSON='
-#     { "AWS_TAG":             "EC2_instance_name",
-#       "AWS_ACCESS_KEY":      "EC2_access_key",
-#       "AWS_SECRET_KEY":      "EC2_secret_key",
+#     { "DROPLET_NAME":        "docker-ci",
+#       "DO_CLIENT_ID":        "Digital_Ocean_client_id",
+#       "DO_API_KEY":          "Digital_Ocean_api_key",
+#       "DOCKER_KEY_ID":       "Digital_Ocean_ssh_key_id",
+#       "DOCKER_CI_KEY_PATH":  "docker-ci_private_key_path",
 #       "DOCKER_CI_PUB":       "$(cat docker-ci_ssh_public_key.pub)",
 #       "DOCKER_CI_KEY":       "$(cat docker-ci_ssh_private_key.key)",
 #       "BUILDBOT_PWD":        "Buildbot_server_password",
@@ -33,9 +35,11 @@
 
 from ubuntu:12.04
 
-run echo 'deb http://archive.ubuntu.com/ubuntu precise main universe' > /etc/apt/sources.list
-run apt-get update; apt-get install -y python2.7 python-dev python-pip ssh rsync less vim
-run pip install boto fabric
+run echo 'deb http://archive.ubuntu.com/ubuntu precise main universe' \
+    > /etc/apt/sources.list
+run apt-get update; apt-get install -y git python2.7 python-dev libevent-dev \
+    python-pip ssh rsync less vim
+run pip install requests fabric
 
 # Add deployment code and set default container command
 add . /docker-ci

hack/infrastructure/docker-ci/VERSION

@@ -0,0 +1 @@
+0.4.5

hack/infrastructure/docker-ci/buildbot/master.cfg

@@ -17,15 +17,12 @@ PORT_GITHUB = 8011      # Buildbot github hook port
 PORT_MASTER = 9989      # Port where buildbot master listen buildworkers
 TEST_USER = 'buildbot'  # Credential to authenticate build triggers
 TEST_PWD = 'docker'     # Credential to authenticate build triggers
-BUILDER_NAME = 'docker'
 GITHUB_DOCKER = 'github.com/dotcloud/docker'
 BUILDBOT_PATH = '/data/buildbot'
 DOCKER_PATH = '/go/src/github.com/dotcloud/docker'
 DOCKER_CI_PATH = '/docker-ci'
-BUILDER_PATH = '/data/buildbot/slave/{0}/build'.format(BUILDER_NAME)
-PULL_REQUEST_PATH = '/data/buildbot/slave/pullrequest/build'
 
-# Credentials set by setup.sh and Vagrantfile
+# Credentials set by setup.sh from deployment.py
 BUILDBOT_PWD = ''
 IRC_PWD = ''
 IRC_CHANNEL = ''
@@ -45,50 +42,59 @@ c['slavePortnum'] = PORT_MASTER
 
 
 # Schedulers
-c['schedulers'] = [ForceScheduler(name='trigger', builderNames=[BUILDER_NAME,
-    'index','registry','coverage','nightlyrelease'])]
-c['schedulers'] += [SingleBranchScheduler(name="all",
-    change_filter=filter.ChangeFilter(branch='master'), treeStableTimer=None,
-    builderNames=[BUILDER_NAME])]
+c['schedulers'] = [ForceScheduler(name='trigger', builderNames=['docker',
+    'index','registry','docker-coverage','registry-coverage','nightlyrelease'])]
+c['schedulers'] += [SingleBranchScheduler(name="all", treeStableTimer=None,
+    change_filter=filter.ChangeFilter(branch='master',
+    repository='https://github.com/dotcloud/docker'), builderNames=['docker'])]
 c['schedulers'] += [SingleBranchScheduler(name='pullrequest',
     change_filter=filter.ChangeFilter(category='github_pullrequest'), treeStableTimer=None,
     builderNames=['pullrequest'])]
-c['schedulers'] += [Nightly(name='daily', branch=None, builderNames=['nightlyrelease'],
-    hour=7, minute=00)]
+c['schedulers'] += [Nightly(name='daily', branch=None, builderNames=['nightlyrelease',
+    'docker-coverage','registry-coverage'], hour=7, minute=00)]
 c['schedulers'] += [Nightly(name='every4hrs', branch=None, builderNames=['registry','index'],
     hour=range(0,24,4), minute=15)]
 
 # Builders
 # Docker commit test
+test_cmd = ('docker run -privileged mzdaniel/test_docker hack/dind'
+    ' test_docker.sh %(src::revision)s')
 factory = BuildFactory()
 factory.addStep(ShellCommand(description='Docker', logEnviron=False,
-    usePTY=True, command=['sh', '-c', Interpolate(
-    '{0}/docker-test/test_docker.sh %(src::revision)s'.format(DOCKER_CI_PATH))]))
+    usePTY=True, command=["sh", "-c", Interpolate(test_cmd)]))
 c['builders'] = [BuilderConfig(name='docker',slavenames=['buildworker'],
     factory=factory)]
 
 # Docker pull request test
+test_cmd = ('docker run -privileged mzdaniel/test_docker hack/dind'
+    ' test_docker.sh %(src::revision)s %(src::repository)s %(src::branch)s')
 factory = BuildFactory()
 factory.addStep(ShellCommand(description='pull_request', logEnviron=False,
-    usePTY=True, command=['sh', '-c', Interpolate(
-    '{0}/docker-test/test_docker.sh %(src::revision)s %(src::repository)s'
-    ' %(src::branch)s'.format(DOCKER_CI_PATH))]))
+    usePTY=True, command=["sh", "-c", Interpolate(test_cmd)]))
 c['builders'] += [BuilderConfig(name='pullrequest',slavenames=['buildworker'],
     factory=factory)]
 
 # Docker coverage test
 factory = BuildFactory()
-factory.addStep(ShellCommand(description='Coverage', logEnviron=False,
+factory.addStep(ShellCommand(description='docker-coverage', logEnviron=False,
     usePTY=True, command='{0}/docker-coverage/coverage-docker.sh'.format(
     DOCKER_CI_PATH)))
-c['builders'] += [BuilderConfig(name='coverage',slavenames=['buildworker'],
+c['builders'] += [BuilderConfig(name='docker-coverage',slavenames=['buildworker'],
+    factory=factory)]
+
+# Docker registry coverage test
+factory = BuildFactory()
+factory.addStep(ShellCommand(description='registry-coverage', logEnviron=False,
+    usePTY=True, command='docker run registry_coverage'.format(
+    DOCKER_CI_PATH)))
+c['builders'] += [BuilderConfig(name='registry-coverage',slavenames=['buildworker'],
     factory=factory)]
 
 # Registry functional test
 factory = BuildFactory()
 factory.addStep(ShellCommand(description='registry', logEnviron=False,
     command='. {0}/master/credentials.cfg; '
-    '/docker-ci/functionaltests/test_registry.sh'.format(BUILDBOT_PATH),
+    '{1}/functionaltests/test_registry.sh'.format(BUILDBOT_PATH, DOCKER_CI_PATH),
     usePTY=True))
 c['builders'] += [BuilderConfig(name='registry',slavenames=['buildworker'],
     factory=factory)]
@@ -97,17 +103,17 @@ c['builders'] += [BuilderConfig(name='registry',slavenames=['buildworker'],
 factory = BuildFactory()
 factory.addStep(ShellCommand(description='index', logEnviron=False,
     command='. {0}/master/credentials.cfg; '
-    '{1}/testing/functionaltests/test_index.py'.format(BUILDBOT_PATH,
-    DOCKER_PATH), usePTY=True))
+    '{1}/functionaltests/test_index.py'.format(BUILDBOT_PATH, DOCKER_CI_PATH),
+    usePTY=True))
 c['builders'] += [BuilderConfig(name='index',slavenames=['buildworker'],
     factory=factory)]
 
 # Docker nightly release
-nightlyrelease_cmd = ('docker run -i -t -privileged -lxc-conf=lxc.aa_profile=unconfined'
-    ' -e AWS_S3_BUCKET=test.docker.io dockerbuilder')
+nightlyrelease_cmd = ('docker version; docker run -i -t -privileged -e AWS_S3_BUCKET='
+    'test.docker.io dockerbuilder hack/dind dockerbuild.sh')
 factory = BuildFactory()
-factory.addStep(ShellCommand(description='NightlyRelease',logEnviron=False,usePTY=True,
-    command=nightlyrelease_cmd))
+factory.addStep(ShellCommand(description='NightlyRelease',logEnviron=False,
+    usePTY=True, command=nightlyrelease_cmd))
 c['builders'] += [BuilderConfig(name='nightlyrelease',slavenames=['buildworker'],
     factory=factory)]
 

hack/infrastructure/docker-ci/deployment.py

@@ -1,11 +1,11 @@
 #!/usr/bin/env python
 
-import os, sys, re, json, base64
-from boto.ec2.connection import EC2Connection
+import os, sys, re, json, requests, base64
 from subprocess import call
 from fabric import api
 from fabric.api import cd, run, put, sudo
 from os import environ as env
+from datetime import datetime
 from time import sleep
 
 # Remove SSH private key as it needs more processing
@@ -20,42 +20,41 @@ for key in CONFIG:
 env['DOCKER_CI_KEY'] = re.sub('^.+"DOCKER_CI_KEY".+?"(.+?)".+','\\1',
     env['CONFIG_JSON'],flags=re.DOTALL)
 
-
-AWS_TAG = env.get('AWS_TAG','docker-ci')
-AWS_KEY_NAME = 'dotcloud-dev'       # Same as CONFIG_JSON['DOCKER_CI_PUB']
-AWS_AMI = 'ami-d582d6bc'            # Ubuntu 13.04
-AWS_REGION = 'us-east-1'
-AWS_TYPE = 'm1.small'
-AWS_SEC_GROUPS = 'gateway'
-AWS_IMAGE_USER = 'ubuntu'
+DROPLET_NAME = env.get('DROPLET_NAME','docker-ci')
+TIMEOUT = 120            # Seconds before timeout droplet creation
+IMAGE_ID = 1004145       # Docker on Ubuntu 13.04
+REGION_ID = 4            # New York 2
+SIZE_ID = 62             # memory 2GB
+DO_IMAGE_USER = 'root'   # Image user on Digital Ocean
+API_URL = 'https://api.digitalocean.com/'
 DOCKER_PATH = '/go/src/github.com/dotcloud/docker'
 DOCKER_CI_PATH = '/docker-ci'
 CFG_PATH = '{}/buildbot'.format(DOCKER_CI_PATH)
 
 
-class AWS_EC2:
-    '''Amazon EC2'''
-    def __init__(self, access_key, secret_key):
+class DigitalOcean():
+
+    def __init__(self, key, client):
         '''Set default API parameters'''
-        self.handler = EC2Connection(access_key, secret_key)
-    def create_instance(self, tag, instance_type):
-        reservation = self.handler.run_instances(**instance_type)
-        instance = reservation.instances[0]
-        sleep(10)
-        while instance.state != 'running':
-            sleep(5)
-            instance.update()
-            print "Instance state: %s" % (instance.state)
-        instance.add_tag("Name",tag)
-        print "instance %s done!" % (instance.id)
-        return instance.ip_address
-    def get_instances(self):
-        return self.handler.get_all_instances()
-    def get_tags(self):
-        return dict([(i.instances[0].id, i.instances[0].tags['Name'])
-            for i in self.handler.get_all_instances() if i.instances[0].tags])
-    def del_instance(self, instance_id):
-        self.handler.terminate_instances(instance_ids=[instance_id])
+        self.key = key
+        self.client = client
+        self.api_url = API_URL
+
+    def api(self, cmd_path, api_arg={}):
+        '''Make api call'''
+        api_arg.update({'api_key':self.key, 'client_id':self.client})
+        resp = requests.get(self.api_url + cmd_path, params=api_arg).text
+        resp = json.loads(resp)
+        if resp['status'] != 'OK':
+            raise Exception(resp['error_message'])
+        return resp
+
+    def droplet_data(self, name):
+        '''Get droplet data'''
+        data = self.api('droplets')
+        data = [droplet for droplet in data['droplets']
+            if droplet['name'] == name]
+        return data[0] if data else {}
 
 
 def json_fmt(data):
@@ -63,20 +62,36 @@ def json_fmt(data):
     return json.dumps(data, sort_keys = True, indent = 2)
 
 
-# Create EC2 API handler
-ec2 = AWS_EC2(env['AWS_ACCESS_KEY'], env['AWS_SECRET_KEY'])
+do = DigitalOcean(env['DO_API_KEY'], env['DO_CLIENT_ID'])
 
-# Stop processing if AWS_TAG exists on EC2
-if AWS_TAG in ec2.get_tags().values():
-    print ('Instance: {} already deployed. Not further processing.'
-        .format(AWS_TAG))
+# Get DROPLET_NAME data
+data = do.droplet_data(DROPLET_NAME)
+
+# Stop processing if DROPLET_NAME exists on Digital Ocean
+if data:
+    print ('Droplet: {} already deployed. Not further processing.'
+        .format(DROPLET_NAME))
     exit(1)
 
-ip = ec2.create_instance(AWS_TAG, {'image_id':AWS_AMI, 'instance_type':AWS_TYPE,
-    'security_groups':[AWS_SEC_GROUPS], 'key_name':AWS_KEY_NAME})
+# Create droplet
+do.api('droplets/new', {'name':DROPLET_NAME, 'region_id':REGION_ID,
+    'image_id':IMAGE_ID, 'size_id':SIZE_ID,
+    'ssh_key_ids':[env['DOCKER_KEY_ID']]})
 
-# Wait 30 seconds for the machine to boot
-sleep(30)
+# Wait for droplet to be created.
+start_time = datetime.now()
+while (data.get('status','') != 'active' and (
+ datetime.now()-start_time).seconds < TIMEOUT):
+    data = do.droplet_data(DROPLET_NAME)
+    print data['status']
+    sleep(3)
+
+# Wait for the machine to boot
+sleep(15)
+
+# Get droplet IP
+ip = str(data['ip_address'])
+print 'droplet: {}    ip: {}'.format(DROPLET_NAME, ip)
 
 # Create docker-ci ssh private key so docker-ci docker container can communicate
 # with its EC2 instance
@@ -86,7 +101,7 @@ os.chmod('/root/.ssh/id_rsa',0600)
 open('/root/.ssh/config','w').write('StrictHostKeyChecking no\n')
 
 api.env.host_string = ip
-api.env.user = AWS_IMAGE_USER
+api.env.user = DO_IMAGE_USER
 api.env.key_filename = '/root/.ssh/id_rsa'
 
 # Correct timezone
@@ -100,20 +115,17 @@ sudo("echo '{}' >> /root/.ssh/authorized_keys".format(env['DOCKER_CI_PUB']))
 credentials = {
     'AWS_ACCESS_KEY': env['PKG_ACCESS_KEY'],
     'AWS_SECRET_KEY': env['PKG_SECRET_KEY'],
-    'GPG_PASSPHRASE': env['PKG_GPG_PASSPHRASE'],
-    'INDEX_AUTH': env['INDEX_AUTH']}
+    'GPG_PASSPHRASE': env['PKG_GPG_PASSPHRASE']}
 open(DOCKER_CI_PATH + '/nightlyrelease/release_credentials.json', 'w').write(
     base64.b64encode(json.dumps(credentials)))
 
 # Transfer docker
 sudo('mkdir -p ' + DOCKER_CI_PATH)
-sudo('chown {}.{} {}'.format(AWS_IMAGE_USER, AWS_IMAGE_USER, DOCKER_CI_PATH))
-call('/usr/bin/rsync -aH {} {}@{}:{}'.format(DOCKER_CI_PATH, AWS_IMAGE_USER, ip,
+sudo('chown {}.{} {}'.format(DO_IMAGE_USER, DO_IMAGE_USER, DOCKER_CI_PATH))
+call('/usr/bin/rsync -aH {} {}@{}:{}'.format(DOCKER_CI_PATH, DO_IMAGE_USER, ip,
     os.path.dirname(DOCKER_CI_PATH)), shell=True)
 
 # Install Docker and Buildbot dependencies
-sudo('addgroup docker')
-sudo('usermod -a -G docker ubuntu')
 sudo('mkdir /mnt/docker; ln -s /mnt/docker /var/lib/docker')
 sudo('wget -q -O - https://get.docker.io/gpg | apt-key add -')
 sudo('echo deb https://get.docker.io/ubuntu docker main >'
@@ -123,7 +135,7 @@ sudo('echo -e "deb http://archive.ubuntu.com/ubuntu raring main universe\n'
     ' > /etc/apt/sources.list; apt-get update')
 sudo('DEBIAN_FRONTEND=noninteractive apt-get install -q -y wget python-dev'
     ' python-pip supervisor git mercurial linux-image-extra-$(uname -r)'
-    ' aufs-tools make libfontconfig libevent-dev')
+    ' aufs-tools make libfontconfig libevent-dev libsqlite3-dev libssl-dev')
 sudo('wget -O - https://go.googlecode.com/files/go1.1.2.linux-amd64.tar.gz | '
     'tar -v -C /usr/local -xz; ln -s /usr/local/go/bin/go /usr/bin/go')
 sudo('GOPATH=/go go get -d github.com/dotcloud/docker')
@@ -135,15 +147,16 @@ sudo('curl -s https://phantomjs.googlecode.com/files/'
     'phantomjs-1.9.1-linux-x86_64.tar.bz2 | tar jx -C /usr/bin'
     ' --strip-components=2 phantomjs-1.9.1-linux-x86_64/bin/phantomjs')
 
-#### FIXME. Temporarily install docker with proper apparmor handling
-sudo('stop docker')
-sudo('wget -q -O /usr/bin/docker http://test.docker.io/test/docker')
-sudo('start docker')
-
 # Build docker-ci containers
 sudo('cd {}; docker build -t docker .'.format(DOCKER_PATH))
+sudo('cd {}; docker build -t docker-ci .'.format(DOCKER_CI_PATH))
 sudo('cd {}/nightlyrelease; docker build -t dockerbuilder .'.format(
     DOCKER_CI_PATH))
+sudo('cd {}/registry-coverage; docker build -t registry_coverage .'.format(
+    DOCKER_CI_PATH))
+
+# Download docker-ci testing container
+sudo('docker pull mzdaniel/test_docker')
 
 # Setup buildbot
 sudo('mkdir /data')
@@ -153,3 +166,6 @@ sudo('{0}/setup.sh root {0} {1} {2} {3} {4} {5} {6} {7} {8} {9} {10}'
     env['SMTP_PWD'], env['EMAIL_RCP'], env['REGISTRY_USER'],
     env['REGISTRY_PWD'], env['REGISTRY_BUCKET'], env['REGISTRY_ACCESS_KEY'],
     env['REGISTRY_SECRET_KEY']))
+
+# Preventively reboot docker-ci daily
+sudo('ln -s /sbin/reboot /etc/cron.daily')

hack/infrastructure/docker-ci/docker-test/Dockerfile

@@ -0,0 +1,25 @@
+# VERSION:        0.4
+# DOCKER-VERSION  0.6.6
+# AUTHOR:         Daniel Mizyrycki <daniel@docker.com>
+# DESCRIPTION:    Testing docker PRs and commits on top of master using
+# REFERENCES:     This code reuses the excellent implementation of
+#                 Docker in Docker made by Jerome Petazzoni.
+#                 https://github.com/jpetazzo/dind
+# COMMENTS:
+#   This Dockerfile adapts /Dockerfile to enable docker PRs and commits testing
+#   Optional arguments:
+#       [commit]  (default: 'HEAD')
+#       [repo]    (default: 'http://github.com/dotcloud/docker')
+#       [branch]  (default: 'master')
+# TO_BUILD:       docker build -t test_docker .
+# TO_RUN:         docker run -privileged test_docker hack/dind test_docker.sh [commit] [repo] [branch]
+
+from docker
+maintainer Daniel Mizyrycki <daniel@docker.com>
+
+# Setup go in PATH. Extracted from /Dockerfile
+env PATH /usr/local/go/bin:$PATH
+
+# Add test_docker.sh
+add test_docker.sh /usr/bin/test_docker.sh
+run chmod +x /usr/bin/test_docker.sh

hack/infrastructure/docker-ci/docker-test/test_docker.sh

@@ -5,31 +5,29 @@ COMMIT=${1-HEAD}
 REPO=${2-http://github.com/dotcloud/docker}
 BRANCH=${3-master}
 
-# Generate a random string of $1 characters
-function random {
-    cat /dev/urandom | tr -cd 'a-f0-9' | head -c $1
-}
-
 # Compute test paths
-BASE_PATH=`pwd`/test_docker_$(random 12)
-DOCKER_PATH=$BASE_PATH/go/src/github.com/dotcloud/docker
-export GOPATH=$BASE_PATH/go:$DOCKER_PATH/vendor
+DOCKER_PATH=/go/src/github.com/dotcloud/docker
+
+# Timestamp
+echo
+date; echo
 
 # Fetch latest master
-mkdir -p $DOCKER_PATH
+cd /
+rm -rf /go
+git clone -q -b master http://github.com/dotcloud/docker $DOCKER_PATH
 cd $DOCKER_PATH
-git init .
-git fetch -q http://github.com/dotcloud/docker master
-git reset --hard FETCH_HEAD
 
 # Merge commit
 git fetch -q "$REPO" "$BRANCH"
-git merge --no-edit $COMMIT || exit 1
+git merge --no-edit $COMMIT || exit 255
 
 # Test commit
-go test -v; exit_status=$?
+./hack/make.sh test; exit_status=$?
 
-# Cleanup testing directory
-rm -rf $BASE_PATH
+# Display load if test fails
+if [ $exit_status -ne 0 ] ; then
+    uptime; echo; free
+fi
 
 exit $exit_status

hack/infrastructure/docker-ci/functionaltests/test_registry.sh

@@ -8,10 +8,12 @@ rm -rf docker-registry
 # Setup the environment
 export SETTINGS_FLAVOR=test
 export DOCKER_REGISTRY_CONFIG=config_test.yml
+export PYTHONPATH=$(pwd)/docker-registry/test
 
 # Get latest docker registry
 git clone -q https://github.com/dotcloud/docker-registry.git
 cd docker-registry
+sed -Ei "s#(boto_bucket: ).+#\1_env:S3_BUCKET#" config_test.yml
 
 # Get dependencies
 pip install -q -r requirements.txt
@@ -20,7 +22,6 @@ pip install -q tox
 
 # Run registry tests
 tox || exit 1
-export PYTHONPATH=$(pwd)/docker-registry
 python -m unittest discover -p s3.py -s test || exit 1
 python -m unittest discover -p workflow.py -s test
 

hack/infrastructure/docker-ci/nightlyrelease/Dockerfile

@@ -1,20 +1,19 @@
-# VERSION:        1.2
-# DOCKER-VERSION  0.6.3
-# AUTHOR:         Daniel Mizyrycki <daniel@dotcloud.com>
+# VERSION:        1.6
+# DOCKER-VERSION  0.6.6
+# AUTHOR:         Daniel Mizyrycki <daniel@docker.com>
 # DESCRIPTION:    Build docker nightly release using Docker in Docker.
 # REFERENCES:     This code reuses the excellent implementation of docker in docker
 #                 made by Jerome Petazzoni.  https://github.com/jpetazzo/dind
 # COMMENTS:
 #   release_credentials.json is a base64 json encoded file containing:
 #       { "AWS_ACCESS_KEY": "Test_docker_AWS_S3_bucket_id",
-#         "AWS_SECRET_KEY='Test_docker_AWS_S3_bucket_key'
-#         "GPG_PASSPHRASE='Test_docker_GPG_passphrase_signature'
-#         "INDEX_AUTH='Encripted_index_authentication' }
+#         "AWS_SECRET_KEY": "Test_docker_AWS_S3_bucket_key",
+#         "GPG_PASSPHRASE": "Test_docker_GPG_passphrase_signature" }
 # TO_BUILD:       docker build -t dockerbuilder .
-# TO_RELEASE:     docker run -i -t -privileged -lxc-conf="lxc.aa_profile = unconfined" -e AWS_S3_BUCKET="test.docker.io" dockerbuilder
+# TO_RELEASE:     docker run -i -t -privileged -e AWS_S3_BUCKET="test.docker.io" dockerbuilder hack/dind dockerbuild.sh
 
 from docker
-maintainer Daniel Mizyrycki <daniel@dotcloud.com>
+maintainer Daniel Mizyrycki <daniel@docker.com>
 
 # Add docker dependencies and downloading packages
 run echo 'deb http://archive.ubuntu.com/ubuntu precise main universe' > /etc/apt/sources.list
@@ -23,15 +22,9 @@ run apt-get update; apt-get install -y -q wget python2.7
 # Add production docker binary
 run wget -q -O /usr/bin/docker http://get.docker.io/builds/Linux/x86_64/docker-latest; chmod +x /usr/bin/docker
 
-#### FIXME. Temporarily install docker with proper apparmor handling
-run wget -q -O /usr/bin/docker http://test.docker.io/test/docker; chmod +x /usr/bin/docker
-
 # Add proto docker builder
-add ./dockerbuild /usr/bin/dockerbuild
-run chmod +x /usr/bin/dockerbuild
+add ./dockerbuild.sh /usr/bin/dockerbuild.sh
+run chmod +x /usr/bin/dockerbuild.sh
 
 # Add release credentials
 add ./release_credentials.json /root/release_credentials.json
-
-# Launch build process in a container
-cmd dockerbuild

hack/infrastructure/docker-ci/nightlyrelease/dockerbuild

@@ -1,45 +0,0 @@
-#!/bin/bash
-
-# Variables AWS_ACCESS_KEY, AWS_SECRET_KEY, PG_PASSPHRASE and INDEX_AUTH
-# are decoded from /root/release_credentials.json
-# Variable AWS_S3_BUCKET is passed to the environment from docker run -e
-
-# Enable debugging
-set -x
-
-# Fetch docker master branch
-rm -rf  /go/src/github.com/dotcloud/docker
-cd /
-git clone -q http://github.com/dotcloud/docker /go/src/github.com/dotcloud/docker
-cd /go/src/github.com/dotcloud/docker
-
-echo FIXME. Temporarily add Jerome changeset with proper apparmor handling
-git fetch  http://github.com/jpetazzo/docker escape-apparmor-confinement:escape-apparmor-confinement
-git rebase --onto master master escape-apparmor-confinement
-
-# Launch docker daemon using dind inside the container
-./hack/dind /usr/bin/docker -d &
-sleep 5
-
-# Add an uncommitted change to generate a timestamped release
-date > timestamp
-
-# Build the docker package using /Dockerfile
-docker build -t docker .
-
-# Run Docker unittests binary and Ubuntu package
-docker run -privileged -lxc-conf=lxc.aa_profile=unconfined docker hack/make.sh || exit 1
-
-# Turn debug off to load credentials from the environment
-set +x
-eval $(cat /root/release_credentials.json  | python -c '
-import sys,json,base64;
-d=json.loads(base64.b64decode(sys.stdin.read()));
-exec("""for k in d: print "export {0}=\\"{1}\\"".format(k,d[k])""")')
-echo '{"https://index.docker.io/v1/":{"auth":"'$INDEX_AUTH'","email":"engineering@dotcloud.com"}}' > /.dockercfg
-set -x
-
-# Push docker nightly
-echo docker run -i -t -privileged -e AWS_S3_BUCKET=$AWS_S3_BUCKET -e AWS_ACCESS_KEY=XXXXX -e AWS_SECRET_KEY=XXXXX -e GPG_PASSPHRASE=XXXXX release  hack/release.sh
-set +x
-docker run -i -t -privileged -e AWS_S3_BUCKET=$AWS_S3_BUCKET -e AWS_ACCESS_KEY=$AWS_ACCESS_KEY -e AWS_SECRET_KEY=$AWS_SECRET_KEY -e GPG_PASSPHRASE=$GPG_PASSPHRASE  release  hack/release.sh

hack/infrastructure/docker-ci/nightlyrelease/dockerbuild.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# Variables AWS_ACCESS_KEY, AWS_SECRET_KEY and PG_PASSPHRASE are decoded
+# from /root/release_credentials.json
+# Variable AWS_S3_BUCKET is passed to the environment from docker run -e
+
+# Turn debug off to load credentials from the environment
+set +x
+eval $(cat /root/release_credentials.json  | python -c '
+import sys,json,base64;
+d=json.loads(base64.b64decode(sys.stdin.read()));
+exec("""for k in d: print "export {0}=\\"{1}\\"".format(k,d[k])""")')
+
+# Fetch docker master branch
+set -x
+cd /
+rm -rf /go
+git clone -q -b master http://github.com/dotcloud/docker /go/src/github.com/dotcloud/docker
+cd /go/src/github.com/dotcloud/docker
+
+# Launch docker daemon using dind inside the container
+/usr/bin/docker version
+/usr/bin/docker -d &
+sleep 5
+
+# Build Docker release container
+docker build -t docker .
+
+# Test docker and if everything works well, release
+echo docker run -i -t -privileged -e AWS_S3_BUCKET=$AWS_S3_BUCKET -e AWS_ACCESS_KEY=XXXXX -e AWS_SECRET_KEY=XXXXX -e GPG_PASSPHRASE=XXXXX docker hack/release.sh
+set +x
+docker run -privileged -i -t -e AWS_S3_BUCKET=$AWS_S3_BUCKET -e AWS_ACCESS_KEY=$AWS_ACCESS_KEY -e AWS_SECRET_KEY=$AWS_SECRET_KEY -e GPG_PASSPHRASE=$GPG_PASSPHRASE docker hack/release.sh
+exit_status=$?
+
+# Display load if test fails
+set -x
+if [ $exit_status -ne 0 ] ; then
+    uptime; echo; free
+    exit 1
+fi

hack/infrastructure/docker-ci/nightlyrelease/release_credentials.json

@@ -1 +0,0 @@
-eyAiQVdTX0FDQ0VTU19LRVkiOiAiIiwKICAiQVdTX1NFQ1JFVF9LRVkiOiAiIiwKICAiR1BHX1BBU1NQSFJBU0UiOiAiIiwKICAiSU5ERVhfQVVUSCI6ICIiIH0=

hack/infrastructure/docker-ci/registry-coverage/Dockerfile

@@ -0,0 +1,18 @@
+# VERSION:        0.1
+# DOCKER-VERSION  0.6.4
+# AUTHOR:         Daniel Mizyrycki <daniel@dotcloud.com>
+# DESCRIPTION:    Docker registry coverage
+# COMMENTS:       Add registry coverage into the docker-ci image
+# TO_BUILD:       docker build -t registry_coverage .
+# TO_RUN:         docker run registry_coverage
+
+from docker-ci
+maintainer Daniel Mizyrycki <daniel@dotcloud.com>
+
+# Add registry_coverager.sh and dependencies
+run pip install coverage flask pyyaml requests simplejson python-glanceclient \
+    blinker redis boto gevent rsa mock
+add registry_coverage.sh /usr/bin/registry_coverage.sh
+run chmod +x /usr/bin/registry_coverage.sh
+
+cmd "/usr/bin/registry_coverage.sh"