@@ -134,6 +134,12 @@ docker pull base

 docker run -i -t base /bin/bash

 ```

+Detaching from the interactive shell

+------------------------------------

+```

+# In order to detach without killing the shell, you can use the escape sequence Ctrl-p + Ctrl-q

+# Note: this works only in tty mode (run with -t option).

+```

 Starting a long-running worker process

 --------------------------------------

@@ -183,7 +189,9 @@ JOB=$(docker run -d -p 4444 base /bin/nc -l -p 4444)

 PORT=$(docker port $JOB 4444)

 # Connect to the public port via the host's public address

-echo hello world | nc $(hostname) $PORT

+# Please note that because of how routing works connecting to localhost or 127.0.0.1 $PORT will not work.

+IP=$(ifconfig eth0 | perl -n -e 'if (m/inet addr:([\d\.]+)/g) { print $1 }')

+echo hello world | nc $IP $PORT

 # Verify that the network connection worked

 echo "Daemon received: $(docker logs $JOB)"

@@ -18,7 +18,7 @@ import (

 	"unicode"

 )

-const VERSION = "0.1.3"

+const VERSION = "0.1.4"

 var GIT_COMMIT string

@@ -62,7 +62,7 @@ func (srv *Server) Help() string {

 }

 // 'docker login': login / register a user to registry service.

-func (srv *Server) CmdLogin(stdin io.ReadCloser, stdout io.Writer, args ...string) error {

+func (srv *Server) CmdLogin(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {

 	// Read a line on raw terminal with support for simple backspace

 	// sequences and echo.

 	//

@@ -113,6 +113,8 @@ func (srv *Server) CmdLogin(stdin io.ReadCloser, stdout io.Writer, args ...strin

 		return readStringOnRawTerminal(stdin, stdout, false)

 	}

+	stdout.SetOptionRawTerminal()

+

 	cmd := rcli.Subcmd(stdout, "login", "", "Register or Login to the docker registry server")

 	if err := cmd.Parse(args); err != nil {

 		return nil

@@ -417,7 +419,8 @@ func (srv *Server) CmdKill(stdin io.ReadCloser, stdout io.Writer, args ...string

 	return nil

 }

-func (srv *Server) CmdImport(stdin io.ReadCloser, stdout io.Writer, args ...string) error {

+func (srv *Server) CmdImport(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {

+	stdout.Flush()

 	cmd := rcli.Subcmd(stdout, "import", "[OPTIONS] URL|- [REPOSITORY [TAG]]", "Create a new filesystem image from the contents of a tarball")

 	var archive io.Reader

 	var resp *http.Response

@@ -464,7 +467,7 @@ func (srv *Server) CmdImport(stdin io.ReadCloser, stdout io.Writer, args ...stri

 	return nil

 }

-func (srv *Server) CmdPush(stdin io.ReadCloser, stdout io.Writer, args ...string) error {

+func (srv *Server) CmdPush(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {

 	cmd := rcli.Subcmd(stdout, "push", "NAME", "Push an image or a repository to the registry")

 	if err := cmd.Parse(args); err != nil {

 		return nil

@@ -784,7 +787,7 @@ func (srv *Server) CmdLogs(stdin io.ReadCloser, stdout io.Writer, args ...string

 	return fmt.Errorf("No such container: %s", cmd.Arg(0))

 }

-func (srv *Server) CmdAttach(stdin io.ReadCloser, stdout io.Writer, args ...string) error {

+func (srv *Server) CmdAttach(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {

 	cmd := rcli.Subcmd(stdout, "attach", "CONTAINER", "Attach to a running container")

 	if err := cmd.Parse(args); err != nil {

 		return nil

@@ -799,6 +802,11 @@ func (srv *Server) CmdAttach(stdin io.ReadCloser, stdout io.Writer, args ...stri

 		return fmt.Errorf("No such container: %s", name)

 	}

+	if container.Config.Tty {

+		stdout.SetOptionRawTerminal()

+	}

+	// Flush the options to make sure the client sets the raw mode

+	stdout.Flush()

 	return <-container.Attach(stdin, nil, stdout, stdout)

 }

@@ -870,7 +878,7 @@ func (srv *Server) CmdTag(stdin io.ReadCloser, stdout io.Writer, args ...string)

 	return srv.runtime.repositories.Set(cmd.Arg(1), cmd.Arg(2), cmd.Arg(0), *force)

 }

-func (srv *Server) CmdRun(stdin io.ReadCloser, stdout io.Writer, args ...string) error {

+func (srv *Server) CmdRun(stdin io.ReadCloser, stdout rcli.DockerConn, args ...string) error {

 	config, err := ParseRun(args, stdout)

 	if err != nil {

 		return err

@@ -884,6 +892,13 @@ func (srv *Server) CmdRun(stdin io.ReadCloser, stdout io.Writer, args ...string)

 		return fmt.Errorf("Command not specified")

 	}

+	if config.Tty {

+		stdout.SetOptionRawTerminal()

+	}

+	// Flush the options to make sure the client sets the raw mode

+	// or tell the client there is no options

+	stdout.Flush()

+

 	// Create new container

 	container, err := srv.runtime.Create(config)

 	if err != nil {

@@ -2,8 +2,8 @@ package docker

 import (

 	"bufio"

-	"bytes"

 	"fmt"

+	"github.com/dotcloud/docker/rcli"

 	"io"

 	"io/ioutil"

 	"strings"

@@ -69,15 +69,27 @@ func TestRunHostname(t *testing.T) {

 	srv := &Server{runtime: runtime}

-	var stdin, stdout bytes.Buffer

-	setTimeout(t, "CmdRun timed out", 2*time.Second, func() {

-		if err := srv.CmdRun(ioutil.NopCloser(&stdin), &nopWriteCloser{&stdout}, "-h", "foobar", GetTestImage(runtime).Id, "hostname"); err != nil {

+	stdin, _ := io.Pipe()

+	stdout, stdoutPipe := io.Pipe()

+

+	c := make(chan struct{})

+	go func() {

+		if err := srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-h", "foobar", GetTestImage(runtime).Id, "hostname"); err != nil {

 			t.Fatal(err)

 		}

-	})

-	if output := string(stdout.Bytes()); output != "foobar\n" {

-		t.Fatalf("'hostname' should display '%s', not '%s'", "foobar\n", output)

+		close(c)

+	}()

+	cmdOutput, err := bufio.NewReader(stdout).ReadString('\n')

+	if err != nil {

+		t.Fatal(err)

+	}

+	if cmdOutput != "foobar\n" {

+		t.Fatalf("'hostname' should display '%s', not '%s'", "foobar\n", cmdOutput)

 	}

+

+	setTimeout(t, "CmdRun timed out", 2*time.Second, func() {

+		<-c

+	})

 }

 func TestRunExit(t *testing.T) {

@@ -93,7 +105,7 @@ func TestRunExit(t *testing.T) {

 	stdout, stdoutPipe := io.Pipe()

 	c1 := make(chan struct{})

 	go func() {

-		srv.CmdRun(stdin, stdoutPipe, "-i", GetTestImage(runtime).Id, "/bin/cat")

+		srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-i", GetTestImage(runtime).Id, "/bin/cat")

 		close(c1)

 	}()

@@ -147,7 +159,7 @@ func TestRunDisconnect(t *testing.T) {

 	go func() {

 		// We're simulating a disconnect so the return value doesn't matter. What matters is the

 		// fact that CmdRun returns.

-		srv.CmdRun(stdin, stdoutPipe, "-i", GetTestImage(runtime).Id, "/bin/cat")

+		srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-i", GetTestImage(runtime).Id, "/bin/cat")

 		close(c1)

 	}()

@@ -179,10 +191,56 @@ func TestRunDisconnect(t *testing.T) {

 	})

 }

+// Expected behaviour: the process dies when the client disconnects

+func TestRunDisconnectTty(t *testing.T) {

+	runtime, err := newTestRuntime()

+	if err != nil {

+		t.Fatal(err)

+	}

+	defer nuke(runtime)

+

+	srv := &Server{runtime: runtime}

+

+	stdin, stdinPipe := io.Pipe()

+	stdout, stdoutPipe := io.Pipe()

+	c1 := make(chan struct{})

+	go func() {

+		// We're simulating a disconnect so the return value doesn't matter. What matters is the

+		// fact that CmdRun returns.

+		srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-i", "-t", GetTestImage(runtime).Id, "/bin/cat")

+		close(c1)

+	}()

+

+	setTimeout(t, "Read/Write assertion timed out", 2*time.Second, func() {

+		if err := assertPipe("hello\n", "hello", stdout, stdinPipe, 15); err != nil {

+			t.Fatal(err)

+		}

+	})

+

+	// Close pipes (simulate disconnect)

+	if err := closeWrap(stdin, stdinPipe, stdout, stdoutPipe); err != nil {

+		t.Fatal(err)

+	}

+

+	// as the pipes are close, we expect the process to die,

+	// therefore CmdRun to unblock. Wait for CmdRun

+	setTimeout(t, "Waiting for CmdRun timed out", 2*time.Second, func() {

+		<-c1

+	})

+

+	// Client disconnect after run -i should keep stdin out in TTY mode

+	container := runtime.List()[0]

+	// Give some time to monitor to do his thing

+	container.WaitTimeout(500 * time.Millisecond)

+	if !container.State.Running {

+		t.Fatalf("/bin/cat should  still be running after closing stdin (tty mode)")

+	}

+}

+

 // TestAttachStdin checks attaching to stdin without stdout and stderr.

 // 'docker run -i -a stdin' should sends the client's stdin to the command,

 // then detach from it and print the container id.

-func TestAttachStdin(t *testing.T) {

+func TestRunAttachStdin(t *testing.T) {

 	runtime, err := newTestRuntime()

 	if err != nil {

 		t.Fatal(err)

@@ -190,31 +248,41 @@ func TestAttachStdin(t *testing.T) {

 	defer nuke(runtime)

 	srv := &Server{runtime: runtime}

-	stdinR, stdinW := io.Pipe()

-	var stdout bytes.Buffer

+	stdin, stdinPipe := io.Pipe()

+	stdout, stdoutPipe := io.Pipe()

 	ch := make(chan struct{})

 	go func() {

-		srv.CmdRun(stdinR, &stdout, "-i", "-a", "stdin", GetTestImage(runtime).Id, "sh", "-c", "echo hello; cat")

+		srv.CmdRun(stdin, rcli.NewDockerLocalConn(stdoutPipe), "-i", "-a", "stdin", GetTestImage(runtime).Id, "sh", "-c", "echo hello; cat")

 		close(ch)

 	}()

-	// Send input to the command, close stdin, wait for CmdRun to return

-	setTimeout(t, "Read/Write timed out", 2*time.Second, func() {

-		if _, err := stdinW.Write([]byte("hi there\n")); err != nil {

+	// Send input to the command, close stdin

+	setTimeout(t, "Write timed out", 2*time.Second, func() {

+		if _, err := stdinPipe.Write([]byte("hi there\n")); err != nil {

+			t.Fatal(err)

+		}

+		if err := stdinPipe.Close(); err != nil {

 			t.Fatal(err)

 		}

-		stdinW.Close()

-		<-ch

 	})

-	// Check output

-	cmdOutput := string(stdout.Bytes())

 	container := runtime.List()[0]

+

+	// Check output

+	cmdOutput, err := bufio.NewReader(stdout).ReadString('\n')

+	if err != nil {

+		t.Fatal(err)

+	}

 	if cmdOutput != container.ShortId()+"\n" {

 		t.Fatalf("Wrong output: should be '%s', not '%s'\n", container.ShortId()+"\n", cmdOutput)

 	}

+	// wait for CmdRun to return

+	setTimeout(t, "Waiting for CmdRun timed out", 2*time.Second, func() {

+		<-ch

+	})

+

 	setTimeout(t, "Waiting for command to exit timed out", 2*time.Second, func() {

 		container.Wait()

 	})

@@ -270,7 +338,7 @@ func TestAttachDisconnect(t *testing.T) {

 	go func() {

 		// We're simulating a disconnect so the return value doesn't matter. What matters is the

 		// fact that CmdAttach returns.

-		srv.CmdAttach(stdin, stdoutPipe, container.Id)

+		srv.CmdAttach(stdin, rcli.NewDockerLocalConn(stdoutPipe), container.Id)

 		close(c1)

 	}()

@@ -40,11 +40,11 @@ type Container struct {

 	stdin       io.ReadCloser

 	stdinPipe   io.WriteCloser

-	ptyStdinMaster  io.Closer

-	ptyStdoutMaster io.Closer

-	ptyStderrMaster io.Closer

+	ptyMaster io.Closer

 	runtime *Runtime

+

+	waitLock chan struct{}

 }

 type Config struct {

@@ -180,63 +180,37 @@ func (container *Container) generateLXCConfig() error {

 }

 func (container *Container) startPty() error {

-	stdoutMaster, stdoutSlave, err := pty.Open()

+	ptyMaster, ptySlave, err := pty.Open()

 	if err != nil {

 		return err

 	}

-	container.ptyStdoutMaster = stdoutMaster

-	container.cmd.Stdout = stdoutSlave

-

-	stderrMaster, stderrSlave, err := pty.Open()

-	if err != nil {

-		return err

-	}

-	container.ptyStderrMaster = stderrMaster

-	container.cmd.Stderr = stderrSlave

+	container.ptyMaster = ptyMaster

+	container.cmd.Stdout = ptySlave

+	container.cmd.Stderr = ptySlave

 	// Copy the PTYs to our broadcasters

 	go func() {

 		defer container.stdout.CloseWriters()

 		Debugf("[startPty] Begin of stdout pipe")

-		io.Copy(container.stdout, stdoutMaster)

+		io.Copy(container.stdout, ptyMaster)

 		Debugf("[startPty] End of stdout pipe")

 	}()

-	go func() {

-		defer container.stderr.CloseWriters()

-		Debugf("[startPty] Begin of stderr pipe")

-		io.Copy(container.stderr, stderrMaster)

-		Debugf("[startPty] End of stderr pipe")

-	}()

-

 	// stdin

-	var stdinSlave io.ReadCloser

 	if container.Config.OpenStdin {

-		var stdinMaster io.WriteCloser

-		stdinMaster, stdinSlave, err = pty.Open()

-		if err != nil {

-			return err

-		}

-		container.ptyStdinMaster = stdinMaster

-		container.cmd.Stdin = stdinSlave

-		// FIXME: The following appears to be broken.

-		// "cannot set terminal process group (-1): Inappropriate ioctl for device"

-		// container.cmd.SysProcAttr = &syscall.SysProcAttr{Setctty: true, Setsid: true}

+		container.cmd.Stdin = ptySlave

+		container.cmd.SysProcAttr = &syscall.SysProcAttr{Setctty: true, Setsid: true}

 		go func() {

 			defer container.stdin.Close()

 			Debugf("[startPty] Begin of stdin pipe")

-			io.Copy(stdinMaster, container.stdin)

+			io.Copy(ptyMaster, container.stdin)

 			Debugf("[startPty] End of stdin pipe")

 		}()

 	}

 	if err := container.cmd.Start(); err != nil {

 		return err

 	}

-	stdoutSlave.Close()

-	stderrSlave.Close()

-	if stdinSlave != nil {

-		stdinSlave.Close()

-	}

+	ptySlave.Close()

 	return nil

 }

@@ -278,10 +252,14 @@ func (container *Container) Attach(stdin io.ReadCloser, stdinCloser io.Closer, s

 				if cStderr != nil {

 					defer cStderr.Close()

 				}

-				if container.Config.StdinOnce {

+				if container.Config.StdinOnce && !container.Config.Tty {

 					defer cStdin.Close()

 				}

-				_, err := io.Copy(cStdin, stdin)

+				if container.Config.Tty {

+					_, err = CopyEscapable(cStdin, stdin)

+				} else {

+					_, err = io.Copy(cStdin, stdin)

+				}

 				if err != nil {

 					Debugf("[error] attach stdin: %s\n", err)

 				}

@@ -365,6 +343,9 @@ func (container *Container) Attach(stdin io.ReadCloser, stdinCloser io.Closer, s

 }

 func (container *Container) Start() error {

+	container.State.lock()

+	defer container.State.unlock()

+

 	if container.State.Running {

 		return fmt.Errorf("The container %s is already running.", container.Id)

 	}

@@ -431,6 +412,9 @@ func (container *Container) Start() 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)

+

+	// Init the lock

+	container.waitLock = make(chan struct{})

 	container.ToDisk()

 	go container.monitor()

 	return nil

@@ -530,19 +514,9 @@ func (container *Container) monitor() {

 		Debugf("%s: Error close stderr: %s", container.Id, err)

 	}

-	if container.ptyStdinMaster != nil {

-		if err := container.ptyStdinMaster.Close(); err != nil {

-			Debugf("%s: Error close pty stdin master: %s", container.Id, err)

-		}

-	}

-	if container.ptyStdoutMaster != nil {

-		if err := container.ptyStdoutMaster.Close(); err != nil {

-			Debugf("%s: Error close pty stdout master: %s", container.Id, err)

-		}

-	}

-	if container.ptyStderrMaster != nil {

-		if err := container.ptyStderrMaster.Close(); err != nil {

-			Debugf("%s: Error close pty stderr master: %s", container.Id, err)

+	if container.ptyMaster != nil {

+		if err := container.ptyMaster.Close(); err != nil {

+			Debugf("%s: Error closing Pty master: %s", container.Id, err)

 		}

 	}

@@ -557,6 +531,10 @@ func (container *Container) monitor() {

 	// Report status back

 	container.State.setStopped(exitCode)

+

+	// Release the lock

+	close(container.waitLock)

+

 	if err := container.ToDisk(); err != nil {

 		// FIXME: there is a race condition here which causes this to fail during the unit tests.

 		// If another goroutine was waiting for Wait() to return before removing the container's root

@@ -569,7 +547,7 @@ func (container *Container) monitor() {

 }

 func (container *Container) kill() error {

-	if container.cmd == nil {

+	if !container.State.Running || container.cmd == nil {

 		return nil

 	}

 	if err := container.cmd.Process.Kill(); err != nil {

@@ -581,13 +559,14 @@ func (container *Container) kill() error {

 }

 func (container *Container) Kill() error {

-	if !container.State.Running {

-		return nil

-	}

+	container.State.lock()

+	defer container.State.unlock()

 	return container.kill()

 }

 func (container *Container) Stop() error {

+	container.State.lock()

+	defer container.State.unlock()

 	if !container.State.Running {

 		return nil

 	}

@@ -596,7 +575,7 @@ func (container *Container) Stop() error {

 	if output, err := exec.Command("lxc-kill", "-n", container.Id, "15").CombinedOutput(); err != nil {

 		log.Print(string(output))

 		log.Print("Failed to send SIGTERM to the process, force killing")

-		if err := container.Kill(); err != nil {

+		if err := container.kill(); err != nil {

 			return err

 		}

 	}

@@ -604,7 +583,7 @@ func (container *Container) Stop() error {

 	// 2. Wait for the process to exit on its own

 	if err := container.WaitTimeout(10 * time.Second); err != nil {

 		log.Printf("Container %v failed to exit within 10 seconds of SIGTERM - using the force", container.Id)

-		if err := container.Kill(); err != nil {

+		if err := container.kill(); err != nil {

 			return err

 		}

 	}

@@ -623,10 +602,7 @@ func (container *Container) Restart() error {

 // Wait blocks until the container stops running, then returns its exit code.

 func (container *Container) Wait() int {

-

-	for container.State.Running {

-		container.State.wait()

-	}

+	<-container.waitLock

 	return container.State.ExitCode

 }

@@ -267,6 +267,7 @@ func TestStart(t *testing.T) {

 	// Try to avoid the timeoout in destroy. Best effort, don't check error

 	cStdin, _ := container.StdinPipe()

 	cStdin.Close()

+	container.WaitTimeout(2 * time.Second)

 }

 func TestRun(t *testing.T) {

@@ -8,7 +8,6 @@ import (

 	"io"

 	"log"

 	"os"

-	"os/signal"

 )

 var GIT_COMMIT string

@@ -57,29 +56,21 @@ func daemon() error {

 }

 func runCommand(args []string) error {

-	var oldState *term.State

-	var err error

-	if term.IsTerminal(int(os.Stdin.Fd())) && os.Getenv("NORAW") == "" {

-		oldState, err = term.MakeRaw(int(os.Stdin.Fd()))

-		if err != nil {

-			return err

-		}

-		defer term.Restore(int(os.Stdin.Fd()), oldState)

-		c := make(chan os.Signal, 1)

-		signal.Notify(c, os.Interrupt)

-		go func() {

-			for _ = range c {

-				term.Restore(int(os.Stdin.Fd()), oldState)

-				log.Printf("\nSIGINT received\n")

-				os.Exit(0)

-			}

-		}()

-	}

 	// FIXME: we want to use unix sockets here, but net.UnixConn doesn't expose

 	// CloseWrite(), which we need to cleanly signal that stdin is closed without

 	// closing the connection.

 	// See http://code.google.com/p/go/issues/detail?id=3345

 	if conn, err := rcli.Call("tcp", "127.0.0.1:4242", args...); err == nil {

+		options := conn.GetOptions()

+		if options.RawTerminal &&

+			term.IsTerminal(int(os.Stdin.Fd())) &&

+			os.Getenv("NORAW") == "" {

+			if oldState, err := rcli.SetRawTerminal(); err != nil {

+				return err

+			} else {

+				defer rcli.RestoreTerminal(oldState)

+			}

+		}

 		receiveStdout := docker.Go(func() error {

 			_, err := io.Copy(os.Stdout, conn)

 			return err

@@ -104,12 +95,11 @@ func runCommand(args []string) error {

 		if err != nil {

 			return err

 		}

-		if err := rcli.LocalCall(service, os.Stdin, os.Stdout, args...); err != nil {

+		dockerConn := rcli.NewDockerLocalConn(os.Stdout)

+		defer dockerConn.Close()

+		if err := rcli.LocalCall(service, os.Stdin, dockerConn, args...); err != nil {

 			return err

 		}

 	}

-	if oldState != nil {

-		term.Restore(int(os.Stdin.Fd()), oldState)

-	}

 	return nil

 }

@@ -39,4 +39,36 @@ Notes

 * The index.html and gettingstarted.html files are copied from the source dir to the output dir without modification.

 So changes to those pages should be made directly in html

 * For the template the css is compiled from less. When changes are needed they can be compiled using

-lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``

\ No newline at end of file

+lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``

+

+

+Guides on using sphinx

+----------------------

+* To make links to certain pages create a link target like so:

+

+  ```

+    .. _hello_world:

+

+    Hello world

+    ===========

+

+    This is.. (etc.)

+  ```

+

+  The ``_hello_world:`` will make it possible to link to this position (page and marker) from all other pages.

+

+* Notes, warnings and alarms

+

+  ```

+    # a note (use when something is important)

+    .. note::

+

+    # a warning (orange)

+    .. warning::

+

+    # danger (red, use sparsely)

+    .. danger::

+

+* Code examples

+

+  Start without $, so it's easy to copy and paste.

\ No newline at end of file

@@ -69,7 +69,8 @@ Expose a service on a TCP port

   # 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.

-  echo hello world | nc $(hostname) $PORT

+  IP=$(ifconfig eth0 | perl -n -e 'if (m/inet addr:([\d\.]+)/g) { print $1 }')

+  echo hello world | nc $IP $PORT

   # Verify that the network connection worked

   echo "Daemon received: $(docker logs $JOB)"

new file mode 100644

@@ -0,0 +1,4 @@

+

+.. note::

+    

+    This example assumes you have Docker running in daemon mode. For more information please see :ref:`running_examples`

@@ -6,8 +6,10 @@

 Hello World

 ===========

-This is the most basic example available for using Docker. The example assumes you have Docker installed.

+.. include:: example_header.inc

+

+This is the most basic example available for using Docker.

 Download the base container

@@ -6,6 +6,9 @@

 Hello World Daemon

 ==================

+

+.. include:: example_header.inc

+

 The most boring daemon ever written.

 This example assumes you have Docker installed and with the base image already imported ``docker pull base``.

@@ -18,7 +21,7 @@ out every second. It will continue to do this until we stop it.

     CONTAINER_ID=$(docker run -d base /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 busybox daemon.

+We are going to run a simple hello world daemon in a new container made from the base image.

 - **"docker run -d "** run a command in a new container. We pass "-d" so it runs as a daemon.

 - **"base"** is the image we want to run the command inside of.

@@ -12,6 +12,7 @@ Contents:

 .. toctree::

    :maxdepth: 1

+   running_examples

    hello_world

    hello_world_daemon

    python_web_app

@@ -6,6 +6,9 @@

 Building a 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 saving the results as a new image. We will do that by making a simple hello flask web application image.

 **Steps:**

@@ -45,6 +48,11 @@ Save the changed we just made in the container to a new image called "_/builds/g

     WEB_WORKER=$(docker run -d -p 5000 $BUILD_IMG /usr/local/bin/runapp)

+- **"docker run -d "** run a command in a new container. We pass "-d" so it runs as a daemon.

+  **"-p 5000"* the web app is going to listen on this port, so it must be mapped from the container to the host system.

+- **"$BUILD_IMG"** is the image we want to run the command inside of.

+- **/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.

 .. code-block:: bash

@@ -54,6 +62,18 @@ Use the new image we just created and create a new container with network port 5

 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=$(docker port $WEB_WORKER 5000)

+

+lookup the public-facing port which is NAT-ed store the private port used by the container and store it inside of the WEB_PORT variable.

+

+.. code-block:: bash

+

+    curl http://`hostname`:$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.

 **Video:**

new file mode 100644

@@ -0,0 +1,33 @@

+:title: Running the Examples

+:description: An overview on how to run the docker examples

+:keywords: docker, examples, how to

+

+.. _running_examples:

+

+Running The Examples

+--------------------

+

+There are two ways to run docker, daemon mode and standalone mode.

+

+When you run the docker command it will first check if there is a docker daemon running in the background it can connect to.

+

+* If it exists it will use that daemon to run all of the commands.

+* If it does not exist docker will run in standalone mode (docker will exit after each command).

+

+Docker needs to be run from a privileged account (root).

+

+1. The most common (and recommended) way is to run a docker daemon as root in the background, and then connect to it from the docker client from any account.

+

+   .. code-block:: bash

+

+      # starting docker daemon in the background

+      sudo docker -d &

+

+      # now you can run docker commands from any account.

+      docker <command>

+

+2. Standalone: You need to run every command as root, or using sudo

+

+   .. code-block:: bash

+

+       sudo docker <command>

@@ -7,7 +7,7 @@

 Create an ssh daemon service

 ============================

-

+.. include:: example_header.inc

 **Video:**

@@ -82,7 +82,7 @@ h4 {

 .btn-custom {

   background-color: #292929 !important;

   background-repeat: repeat-x;

-  filter: progid:dximagetransform.microsoft.gradient(startColorstr="#515151", endColorstr="#282828");

+  filter: progid:DXImageTransform.Microsoft.gradient(startColorstr="#515151", endColorstr="#282828");

   background-image: -khtml-gradient(linear, left top, left bottom, from(#515151), to(#282828));

   background-image: -moz-linear-gradient(top, #515151, #282828);

   background-image: -ms-linear-gradient(top, #515151, #282828);

@@ -131,6 +131,27 @@ section.header {

   margin: 15px 15px 15px 0;

   border: 2px solid gray;

 }

+.admonition {

+  padding: 10px;

+  border: 1px solid grey;

+  margin-bottom: 10px;

+  margin-top: 10px;

+  -webkit-border-radius: 4px;

+  -moz-border-radius: 4px;

+  border-radius: 4px;

+}

+.admonition .admonition-title {

+  font-weight: bold;

+}

+.admonition.note {

+  background-color: #f1ebba;

+}

+.admonition.warning {

+  background-color: #eed9af;

+}

+.admonition.danger {

+  background-color: #e9bcab;

+}

 /* ===================

 	left navigation

 ===================== */

@@ -179,7 +179,33 @@ section.header {

   border: 2px solid gray;

 }

+.admonition {

+  padding: 10px;

+  border: 1px solid grey;

+

+  margin-bottom: 10px;

+  margin-top: 10px;

+

+  -webkit-border-radius: 4px;

+  -moz-border-radius: 4px;

+  border-radius: 4px;

+}

+

+.admonition .admonition-title {

+  font-weight: bold;

+}

+

+.admonition.note {

+  background-color: rgb(241, 235, 186);

+}

+.admonition.warning {

+  background-color: rgb(238, 217, 175);

+}

+

+.admonition.danger {

+  background-color: rgb(233, 188, 171);

+}

 /* ===================

 	left navigation

@@ -111,6 +111,8 @@ func checkRouteOverlaps(dockerNetwork *net.IPNet) error {

 }

 func CreateBridgeIface(ifaceName string) error {

+	// FIXME: try more IP ranges

+	// FIXME: try bigger ranges! /24 is too small.

 	addrs := []string{"172.16.42.1/24", "10.0.42.1/24", "192.168.42.1/24"}

 	var ifaceAddr string

@@ -127,7 +129,7 @@ func CreateBridgeIface(ifaceName string) error {

 		}

 	}

 	if ifaceAddr == "" {

-		return fmt.Errorf("Impossible to create a bridge. Please create a bridge manually and restart docker with -br <bridgeName>")

+		return fmt.Errorf("Could not find a free IP address range for interface '%s'. Please configure its address manually and run 'docker -b %s'", ifaceName, ifaceName)

 	} else {

 		Debugf("Creating bridge %s with network %s", ifaceName, ifaceAddr)

 	}

deleted file mode 100644

@@ -1,38 +0,0 @@

-package rcli

-

-import (

-	"fmt"

-	"net/http"

-	"net/url"

-	"path"

-)

-

-// Use this key to encode an RPC call into an URL,

-// eg. domain.tld/path/to/method?q=get_user&q=gordon

-const ARG_URL_KEY = "q"

-