Updated the entire installation section text, checked everything, cleaned up rackspace installation.

docs/sources/installation/amazon.rst

@@ -68,7 +68,7 @@ Docker can now be installed on Amazon EC2 with a single vagrant command. Vagrant
    If it stalls indefinitely on ``[default] Waiting for SSH to become available...``, Double check your default security
    zone on AWS includes rights to SSH (port 22) to your container.
 
-   If you have an advanced AWS setup, you might want to have a look at the https://github.com/mitchellh/vagrant-aws
+   If you have an advanced AWS setup, you might want to have a look at https://github.com/mitchellh/vagrant-aws
 
 7. Connect to your machine
 

docs/sources/installation/binaries.rst

@@ -5,48 +5,58 @@ Binaries
 
   **Please note this project is currently under heavy development. It should not be used in production.**
 
+**This instruction set is meant for hackers who want to try out Docker on a variety of environments.**
 
-Right now, the officially supported distributions are:
+Right now, the officially supported distribution are:
 
-- Ubuntu 12.04 (precise LTS) (64-bit)
-- Ubuntu 12.10 (quantal) (64-bit)
+- :ref:`ubuntu_precise`
+- :ref:`ubuntu_raring`
 
 
-Install dependencies:
----------------------
+But we know people have had success running it under
+
+- Debian
+- Suse
+- :ref:`arch_linux`
+
 
-::
+Dependencies:
+-------------
 
-    sudo apt-get install lxc bsdtar
-    sudo apt-get install linux-image-extra-`uname -r`
+* 3.8 Kernel
+* AUFS filesystem support
+* lxc
+* bsdtar
 
-The linux-image-extra package is needed on standard Ubuntu EC2 AMIs in order to install the aufs kernel module.
 
-Install the docker binary:
+Get the docker binary:
+----------------------
 
-::
+.. code-block:: bash
 
     wget http://get.docker.io/builds/Linux/x86_64/docker-latest.tgz
     tar -xf docker-latest.tgz
-    sudo cp ./docker-latest/docker /usr/local/bin
-
-Note: docker currently only supports 64-bit Linux hosts.
 
 
 Run the docker daemon
 ---------------------
 
-::
+.. code-block:: bash
 
-    sudo docker -d &
+    # start the docker in daemon mode from the directory you unpacked
+    sudo ./docker -d &
 
 
 Run your first container!
 -------------------------
 
-::
+.. code-block:: bash
+
+    # check your docker version
+    ./docker version
 
-    docker run -i -t ubuntu /bin/bash
+    # run a container and open an interactive shell in the container
+    ./docker run -i -t ubuntu /bin/bash
 
 
 

docs/sources/installation/index.rst

@@ -14,9 +14,9 @@ Contents:
 
    ubuntulinux
    binaries
-   archlinux
    vagrant
    windows
    amazon
    rackspace
+   archlinux
    upgrading

docs/sources/installation/rackspace.rst

@@ -2,220 +2,90 @@
 Rackspace Cloud
 ===============
 
-.. contents:: Table of Contents
+  Please note this is a community contributed installation path. The only 'official' installation is using the
+  :ref:`ubuntu_linux` installation path. This version may sometimes be out of date.
 
-Ubuntu 12.04
-------------
 
-1. Build an Ubuntu 12.04 server using the "Next generation cloud servers", with your desired size. It will give you the password, keep that you will need it later.
-2. When the server is up and running ssh into the server.
+Installing Docker on Ubuntu proviced by Rackspace is pretty straightforward, and you should mostly be able to follow the
+:ref:`ubuntu_linux` installation guide.
 
-    .. code-block:: bash
+**However, there is one caveat:**
 
-        $ ssh root@<server-ip>
+If you are using any linux not already shipping with the 3.8 kernel you will need to install it. And this is a little
+more difficult on Rackspace.
 
-3. Once you are logged in you should check what kernel version you are running.
+Rackspace boots their servers using grub's menu.lst and does not like non 'virtual' packages (e.g. xen compatible)
+kernels there, although they do work. This makes ``update-grub`` to not have the expected result, and you need to
+set the kernel manually.
 
-    .. code-block:: bash
-
-        $ uname -a
-        Linux docker-12-04 3.2.0-38-virtual #61-Ubuntu SMP Tue Feb 19 12:37:47 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux
-
-4. Let's update the server package list
-
-    .. code-block:: bash
-
-        $ apt-get update
-
-5. Now lets install Docker and it's dependencies. To keep things simple, we will use the Docker install script. It will take a couple of minutes.
-
-    .. code-block:: bash
-
-        $ curl get.docker.io | sudo sh -x
-
-6. Docker runs best with a new kernel, so lets use 3.8.x
-
-    .. code-block:: bash
-        
-        # install the new kernel
-        $ apt-get install linux-generic-lts-raring
-        
-        # update grub so it will use the new kernel after we reboot
-        $ update-grub
-        
-        # update-grub doesn't always work so lets make sure. ``/boot/grub/menu.lst`` was updated.
-        $ grep 3.8.0- /boot/grub/menu.lst
-        
-        # nope it wasn't lets manually update ``/boot/grub/menu.lst``  (make sure you are searching for correct kernel version, look at initial uname -a results.)
-        $ sed -i s/3.2.0-38-virtual/3.8.0-19-generic/ /boot/grub/menu.lst
-        
-        # once again lets make sure it worked.
-        $ grep 3.8.0- /boot/grub/menu.lst
-        title          Ubuntu 12.04.2 LTS, kernel 3.8.0-19-generic
-        kernel          /boot/vmlinuz-3.8.0-19-generic root=/dev/xvda1 ro quiet splash console=hvc0
-        initrd          /boot/initrd.img-3.8.0-19-generic
-        title          Ubuntu 12.04.2 LTS, kernel 3.8.0-19-generic (recovery mode)
-        kernel          /boot/vmlinuz-3.8.0-19-generic root=/dev/xvda1 ro quiet splash  single
-        initrd          /boot/initrd.img-3.8.0-19-generic
-        
-        # much better.
-
-7. Reboot server (either via command line or console)
-8. login again and check to make sure the kernel was updated
-
-    .. code-block:: bash
-        
-        $ ssh root@<server_ip>
-        $ uname -a
-        Linux docker-12-04 3.8.0-19-generic #30~precise1-Ubuntu SMP Wed May 1 22:26:36 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux
-        
-        # nice 3.8.
-
-9. Make sure docker is running and test it out.
-
-    .. code-block:: bash
-        
-        $ start dockerd
-        $ docker pull busybox
-        $ docker run busybox /bin/echo hello world
-        hello world
-
-Alternate install
-^^^^^^^^^^^^^^^^^
-If you don't want to run the get.docker.io script and want to use packages instead, you can use the docker PPA. Here is how you use it. Replace step 5 with the following 3 steps.
-
-1. Add the custom package sources to your apt sources list. Copy and paste the following lines at once.
+**Do not attempt this on a production machine!**
 
 .. code-block:: bash
 
-   $ sudo sh -c "echo 'deb http://ppa.launchpad.net/dotcloud/lxc-docker/ubuntu precise main' >> /etc/apt/sources.list"
-
-
-2. Update your sources. You will see a warning that GPG signatures cannot be verified.
-
-.. code-block:: bash
+    # update apt
+    apt-get update
 
-   $ sudo apt-get update
+    # install the new kernel
+    apt-get install linux-generic-lts-raring
 
 
-3. Now install it, you will see another warning that the package cannot be authenticated. Confirm install.
+Great, now you have kernel installed in /boot/, next is to make it boot next time.
 
 .. code-block:: bash
 
-    $ apt-get install lxc-docker
-
-
-Ubuntu 12.10
-------------
-
-1. Build an Ubuntu 12.10 server using the "Next generation cloud servers", with your desired size. It will give you the password, keep that you will need it later.
-2. When the server is up and running ssh into the server.
-
-    .. code-block:: bash
-
-        $ ssh root@<server-ip>
-
-3. Once you are logged in you should check what kernel version you are running.
-
-    .. code-block:: bash
-
-        $ uname -a
-        Linux docker-12-10 3.5.0-25-generic #39-Ubuntu SMP Mon Feb 25 18:26:58 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux
+    # find the exact names
+    find /boot/ -name '*3.8*'
 
-4. Let's update the server package list
+    # this should return some results
 
-    .. code-block:: bash
 
-        $ apt-get update
+Now you need to manually edit /boot/grub/menu.lst, you will find a section at the bottom with the existing options.
+Copy the top one and substitute the new kernel into that. Make sure the new kernel is on top, and double check kernel
+and initrd point to the right files.
 
-5. Now lets install Docker and it's dependencies. To keep things simple, we will use the Docker install script. It will take a couple of minutes.
+Make special care to double check the kernel and initrd entries.
 
-    .. code-block:: bash
-
-        $ curl get.docker.io | sudo sh -x
-
-6. Docker runs best with a new kernel, so lets use 3.8.x
-
-    .. code-block:: bash
-        
-        # add the ppa to get the right kernel package
-        $ echo deb http://ppa.launchpad.net/ubuntu-x-swat/q-lts-backport/ubuntu quantal main > /etc/apt/sources.list.d/xswat.list
-        
-        # add the key for the ppa
-        $ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 3B22AB97AF1CDFA9
-        
-        # update packages again
-        $ apt-get update
-        
-        # install the new kernel
-        $ apt-get install linux-image-3.8.0-19-generic
-
-        # make sure grub has been updated.
-        $ grep 3.8.0- /boot/grub/menu.lst
-        title   Ubuntu 12.10, kernel 3.8.0-19-generic
-        kernel  /boot/vmlinuz-3.8.0-19-generic root=/dev/xvda1 ro quiet splash console=hvc0
-        initrd  /boot/initrd.img-3.8.0-19-generic
-        title   Ubuntu 12.10, kernel 3.8.0-19-generic (recovery mode)
-        kernel  /boot/vmlinuz-3.8.0-19-generic root=/dev/xvda1 ro quiet splash  single
-        initrd  /boot/initrd.img-3.8.0-19-generic
-        
-        # looks good. If it doesn't work for you, look at the notes for 12.04 to fix.
-
-7. Reboot server (either via command line or console)
-8. login again and check to make sure the kernel was updated
-
-    .. code-block:: bash
-        
-        $ ssh root@<server_ip>
-        $ uname -a
-        Linux docker-12-10 3.8.0-19-generic #29~precise2-Ubuntu SMP Fri Apr 19 16:15:35 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux
-        
-        # nice 3.8.
+.. code-block:: bash
 
-9. Make sure docker is running and test it out.
+    # now edit /boot/grub/menu.lst
+    vi /boot/grub/menu.lst
 
-    .. code-block:: bash
-        
-        $ start dockerd
-        $ docker pull busybox
-        $ docker run busybox /bin/echo hello world
-        hello world
+It will probably look something like this:
 
-Ubuntu 13.04
-------------
+::
 
-1. Build an Ubuntu 13.04 server using the "Next generation cloud servers", with your desired size. It will give you the password, keep that you will need it later.
-2. When the server is up and running ssh into the server.
+     ## ## End Default Options ##
 
-    .. code-block:: bash
+     title		Ubuntu 12.04.2 LTS, kernel 3.8.x generic
+     root		(hd0)
+     kernel		/boot/vmlinuz-3.8.0-19-generic root=/dev/xvda1 ro quiet splash console=hvc0
+     initrd		/boot/initrd.img-3.8.0-19-generic
 
-        $ ssh root@<server-ip>
+     title		Ubuntu 12.04.2 LTS, kernel 3.2.0-38-virtual
+     root		(hd0)
+     kernel		/boot/vmlinuz-3.2.0-38-virtual root=/dev/xvda1 ro quiet splash console=hvc0
+     initrd		/boot/initrd.img-3.2.0-38-virtual
 
-3. Once you are logged in you should check what kernel version you are running.
+     title		Ubuntu 12.04.2 LTS, kernel 3.2.0-38-virtual (recovery mode)
+     root		(hd0)
+     kernel		/boot/vmlinuz-3.2.0-38-virtual root=/dev/xvda1 ro quiet splash  single
+     initrd		/boot/initrd.img-3.2.0-38-virtual
 
-    .. code-block:: bash
 
-        $ uname -a
-        Linux docker-1304 3.8.0-19-generic #29-Ubuntu SMP Wed Apr 17 18:16:28 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux
+Reboot server (either via command line or console)
 
-4. Let's update the server package list
+.. code-block:: bash
 
-    .. code-block:: bash
+   # reboot
 
-        $ apt-get update
+Verify the kernel was updated
 
-5. Now lets install Docker and it's dependencies. To keep things simple, we will use the Docker install script. It will take a couple of minutes.
+.. code-block:: bash
 
-    .. code-block:: bash
+    uname -a
+    # Linux docker-12-04 3.8.0-19-generic #30~precise1-Ubuntu SMP Wed May 1 22:26:36 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux
 
-        $ curl get.docker.io | sudo sh -x
+    # nice! 3.8.
 
-6. Make sure docker is running and test it out.
 
-    .. code-block:: bash
-        
-        $ start dockerd
-        $ docker pull busybox
-        $ docker run busybox /bin/echo hello world
-        hello world
- 
+Now you can finish with the :ref:`ubuntu_linux` instructions.

docs/sources/installation/ubuntulinux.rst

@@ -5,20 +5,39 @@ Ubuntu Linux
 
   **Please note this project is currently under heavy development. It should not be used in production.**
 
+Right now, the officially supported distribution are:
 
-Right now, the officially supported distributions are:
+- :ref:`ubuntu_precise`
+- :ref:`ubuntu_raring`
+
+Docker has the following dependencies
+
+* Linux kernel 3.8
+* AUFS file system support (we are working on BTRFS support as an alternative)
+
+.. _ubuntu_precise:
+
+Ubuntu Precise 12.04 (LTS) (64-bit)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This installation path should work at all times.
 
-- Ubuntu 12.04 (precise LTS) (64-bit)
-- Ubuntu 12.10 (quantal) (64-bit)
 
 Dependencies
 ------------
 
-The linux-image-extra package is only needed on standard Ubuntu EC2 AMIs in order to install the aufs kernel module.
+**Linux kernel 3.8**
+
+Due to a bug in LXC docker works best on the 3.8 kernel. Precise comes with a 3.2 kernel, so we need to upgrade it. The kernel we install comes with AUFS built in.
+
 
 .. code-block:: bash
 
-   sudo apt-get install linux-image-extra-`uname -r` lxc bsdtar
+   # install the backported kernel
+   sudo apt-get update && sudo apt-get install linux-image-3.8.0-19-generic
+
+   # reboot
+   sudo reboot
 
 
 Installation
@@ -28,33 +47,77 @@ Docker is available as a Ubuntu PPA (Personal Package Archive),
 `hosted on launchpad  <https://launchpad.net/~dotcloud/+archive/lxc-docker>`_
 which makes installing Docker on Ubuntu very easy.
 
+.. code-block:: bash
 
+   # Add the PPA sources to your apt sources list.
+   sudo sh -c "echo 'deb http://ppa.launchpad.net/dotcloud/lxc-docker/ubuntu precise main' > /etc/apt/sources.list.d/lxc-docker.list"
 
-Add the custom package sources to your apt sources list. Copy and paste the following lines at once.
+   # Update your sources, you will see a warning.
+   sudo apt-get update
+
+   # Install, you will see another warning that the package cannot be authenticated. Confirm install.
+   sudo apt-get install lxc-docker
+
+Verify it worked
 
 .. code-block:: bash
 
-   sudo sh -c "echo 'deb http://ppa.launchpad.net/dotcloud/lxc-docker/ubuntu precise main' >> /etc/apt/sources.list"
+   # download the base 'ubuntu' container and run bash inside it while setting up an interactive shell
+   docker run -i -t ubuntu /bin/bash
+
+   # type 'exit' to exit
+
+
+**Done!**, now continue with the :ref:`hello_world` example.
+
+.. _ubuntu_raring:
+
+Ubuntu Raring 13.04 (64 bit)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dependencies
+------------
 
+**AUFS filesystem support**
 
-Update your sources. You will see a warning that GPG signatures cannot be verified.
+Ubuntu Raring already comes with the 3.8 kernel, so we don't need to install it. However, not all systems
+have AUFS filesystem support enabled, so we need to install it.
 
 .. code-block:: bash
 
    sudo apt-get update
+   sudo apt-get install linux-image-extra-`uname -r`
 
+Installation
+------------
+
+Docker is available as a Ubuntu PPA (Personal Package Archive),
+`hosted on launchpad  <https://launchpad.net/~dotcloud/+archive/lxc-docker>`_
+which makes installing Docker on Ubuntu very easy.
 
-Now install it, you will see another warning that the package cannot be authenticated. Confirm install.
+
+Add the custom package sources to your apt sources list.
 
 .. code-block:: bash
 
-    apt-get install lxc-docker
+   # add the sources to your apt
+   sudo add-apt-repository ppa:dotcloud/lxc-docker
+
+   # update
+   sudo apt-get update
+
+   # install
+   sudo apt-get install lxc-docker
+
 
 Verify it worked
 
 .. code-block:: bash
 
-   docker
+   # download the base 'ubuntu' container and run bash inside it while setting up an interactive shell
+   docker run -i -t ubuntu /bin/bash
+
+   # type exit to exit
 
 
 **Done!**, now continue with the :ref:`hello_world` example.

docs/sources/installation/upgrading.rst

@@ -3,38 +3,53 @@
 Upgrading
 ============
 
-These instructions are for upgrading your Docker binary for when you had a custom (non package manager) installation.
-If you istalled docker using apt-get, use that to upgrade.
+**These instructions are for upgrading Docker**
 
 
-Get the latest docker binary:
+After normal installation
+-------------------------
 
-::
+If you installed Docker normally using apt-get or used Vagrant, use apt-get to upgrade.
 
-  wget http://get.docker.io/builds/$(uname -s)/$(uname -m)/docker-latest.tgz
+.. code-block:: bash
 
+   # update your sources list
+   sudo apt-get update
 
+   # install the latest
+   sudo apt-get install lxc-docker
 
-Unpack it to your current dir
 
-::
+After manual installation
+-------------------------
 
-   tar -xf docker-latest.tgz
+If you installed the Docker binary
+
+
+.. code-block:: bash
+
+   # kill the running docker daemon
+   killall docker
 
 
-Stop your current daemon. How you stop your daemon depends on how you started it.
+.. code-block:: bash
 
-- If you started the daemon manually (``sudo docker -d``), you can just kill the process: ``killall docker``
-- If the process was started using upstart (the ubuntu startup daemon), you may need to use that to stop it
+   # get the latest binary
+   wget http://get.docker.io/builds/Linux/x86_64/docker-latest.tgz
 
 
-Start docker in daemon mode (-d) and disconnect (&) starting ./docker will start the version in your current dir rather
-than the one in your PATH.
+.. code-block:: bash
+
+   # Unpack it to your current dir
+   tar -xf docker-latest.tgz
+
 
-Now start the daemon
+Start docker in daemon mode (-d) and disconnect (&) starting ./docker will start the version in your current dir rather than a version which
+might reside in your path.
 
-::
+.. code-block:: bash
 
+   # start the new version
    sudo ./docker -d &
 
 

docs/sources/installation/vagrant.rst

@@ -1,14 +1,10 @@
 
 .. _install_using_vagrant:
 
-Using Vagrant
-=============
+Using Vagrant (Mac, Linux)
+==========================
 
-  Please note this is a community contributed installation path. The only 'official' installation is using the
-  :ref:`ubuntu_linux` installation path. This version may sometimes be out of date.
-
-**Requirements:**
-This guide will setup a new virtual machine with docker installed on your computer. This works on most operating
+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 install these and have at least 400Mb RAM
 to spare you should be good.
 

docs/sources/installation/windows.rst

@@ -3,8 +3,8 @@
 :keywords: Docker, Docker documentation, Windows, requirements, virtualbox, vagrant, git, ssh, putty, cygwin
 
 
-Windows (with Vagrant)
-======================
+Using Vagrant (Windows)
+=======================
 
   Please note this is a community contributed installation path. The only 'official' installation is using the :ref:`ubuntu_linux` installation path. This version
   may be out of date because it depends on some binaries to be updated and published