Fix #1685: Notes on production use. General installation cleanup.

docs/sources/installation/amazon.rst

@@ -5,18 +5,20 @@
 Using Vagrant (Amazon EC2)
 ==========================
 
-This page explains how to setup and run an Amazon EC2 instance from your local machine. 
-Vagrant is not necessary to run Docker on EC2. You can follow the :ref:`ubuntu_linux` instructions
-installing Docker on any EC2 instance running Ubuntu
+This page explains how to setup and run an Amazon EC2 instance from
+your local machine.  **Vagrant is not necessary to run Docker on
+EC2.** You can follow the :ref:`ubuntu_linux` instructions installing
+Docker on any EC2 instance running Ubuntu.
 
-  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.
-  
-  
 Installation
 ------------
 
-Docker can now be installed on Amazon EC2 with a single vagrant command. Vagrant 1.1 or higher is required.
+.. include:: install_header.inc
+
+.. include:: install_unofficial.inc
+  
+Docker can now be installed on Amazon EC2 with a single vagrant
+command. Vagrant 1.1 or higher is required.
 
 1. Install vagrant from http://www.vagrantup.com/ (or use your package manager)
 2. Install the vagrant aws plugin

docs/sources/installation/archlinux.rst

@@ -7,10 +7,6 @@
 Arch 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.
-
-
 Installing on Arch Linux is not officially supported but can be handled via 
 either of the following AUR packages:
 
@@ -36,6 +32,10 @@ either AUR package.
 Installation
 ------------
 
+.. include:: install_header.inc
+
+.. include:: install_unofficial.inc
+
 The instructions here assume **yaourt** is installed.  See 
 `Arch User Repository <https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages>`_
 for information on building and installing packages from the AUR if you have not

docs/sources/installation/binaries.rst

@@ -7,9 +7,10 @@
 Binaries
 ========
 
-  **Please note this project is currently under heavy development. It should not be used in production.**
+.. include:: install_header.inc
 
-**This instruction set is meant for hackers who want to try out Docker on a variety of environments.**
+**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:
 
@@ -23,14 +24,10 @@ But we know people have had success running it under
 - Suse
 - :ref:`arch_linux`
 
+Check Your Kernel
+-----------------
 
-Dependencies:
--------------
-
-* 3.8 Kernel (read more about :ref:`kernel`)
-* AUFS filesystem support
-* lxc
-* xz-utils
+Your host's Linux kernel must meet the Docker :ref:`kernel`
 
 Get the docker binary:
 ----------------------

docs/sources/installation/install_header.inc

@@ -0,0 +1,7 @@
+
+.. note::
+
+   Docker is still under heavy development! We don't recommend using
+   it in production yet, but we're getting closer with each
+   release. Please see our blog post, `"Getting to Docker 1.0"
+   <http://blog.docker.io/2013/08/getting-to-docker-1-0/>`_

docs/sources/installation/install_unofficial.inc

@@ -0,0 +1,7 @@
+
+.. 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

docs/sources/installation/rackspace.rst

@@ -6,21 +6,22 @@
 Rackspace Cloud
 ===============
 
-  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.
+.. include:: install_unofficial.inc
 
-
-Installing Docker on Ubuntu provided by Rackspace is pretty straightforward, and you should mostly be able to follow the
+Installing Docker on Ubuntu provided by Rackspace is pretty
+straightforward, and you should mostly be able to follow the
 :ref:`ubuntu_linux` installation guide.
 
 **However, there is one caveat:**
 
-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.
+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.
 
-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.
+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.
 
 **Do not attempt this on a production machine!**
 
@@ -33,7 +34,8 @@ set the kernel manually.
     apt-get install linux-generic-lts-raring
 
 
-Great, now you have kernel installed in /boot/, next is to make it boot next time.
+Great, now you have kernel installed in ``/boot/``, next is to make it
+boot next time.
 
 .. code-block:: bash
 
@@ -43,9 +45,10 @@ Great, now you have kernel installed in /boot/, next is to make it boot next tim
     # this should return some results
 
 
-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.
+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.
 
 Make special care to double check the kernel and initrd entries.
 
@@ -92,4 +95,4 @@ Verify the kernel was updated
     # nice! 3.8.
 
 
-Now you can finish with the :ref:`ubuntu_linux` instructions.
+Now you can finish with the :ref:`ubuntu_linux` instructions.

docs/sources/installation/ubuntulinux.rst

@@ -2,15 +2,17 @@
 :description: Please note this project is currently under heavy development. It should not be used in production.
 :keywords: Docker, Docker documentation, requirements, virtualbox, vagrant, git, ssh, putty, cygwin, linux
 
-**These instructions have changed for 0.6. If you are upgrading from an earlier version, you will need to follow them again.**
-
 .. _ubuntu_linux:
 
 Ubuntu Linux
 ============
 
-   **Please note this project is currently under heavy development. It should not be used in production.**
+.. warning::
+
+   These instructions have changed for 0.6. If you are upgrading from
+   an earlier version, you will need to follow them again.
 
+.. include:: install_header.inc
 
 Right now, the officially supported distribution are:
 
@@ -22,7 +24,8 @@ Docker has the following dependencies
 * Linux kernel 3.8 (read more about :ref:`kernel`)
 * AUFS file system support (we are working on BTRFS support as an alternative)
 
-Please read :ref:`ufw`, if you plan to use `UFW (Uncomplicated Firewall) <https://help.ubuntu.com/community/UFW>`_
+Please read :ref:`ufw`, if you plan to use `UFW (Uncomplicated
+Firewall) <https://help.ubuntu.com/community/UFW>`_
 
 .. _ubuntu_precise:
 
@@ -38,12 +41,13 @@ Dependencies
 **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 you'll install when following these steps
-comes with AUFS built in. We also include the generic headers
-to enable packages that depend on them, like ZFS and the VirtualBox
-guest additions. If you didn't install the headers for your "precise"
-kernel, then you can skip these headers for the "raring" kernel. But
-it is safer to include them if you're not sure.
+comes with a 3.2 kernel, so we need to upgrade it. The kernel you'll
+install when following these steps comes with AUFS built in. We also
+include the generic headers to enable packages that depend on them,
+like ZFS and the VirtualBox guest additions. If you didn't install the
+headers for your "precise" kernel, then you can skip these headers for
+the "raring" kernel. But it is safer to include them if you're not
+sure.
 
 
 .. code-block:: bash
@@ -59,10 +63,13 @@ it is safer to include them if you're not sure.
 Installation
 ------------
 
+.. warning::
+
+   These instructions have changed for 0.6. If you are upgrading from
+   an earlier version, you will need to follow them again.
+
 Docker is available as a Debian package, which makes installation easy.
 
-*Please note that these instructions have changed for 0.6. If you are upgrading from an earlier version, you will need
-to follow them again.*
 
 .. code-block:: bash
 
@@ -136,7 +143,8 @@ Verify it worked
 
 .. code-block:: bash
 
-   # download the base 'ubuntu' container and run bash inside it while setting up an interactive shell
+   # download the base 'ubuntu' container
+   # and run bash inside it while setting up an interactive shell
    sudo docker run -i -t ubuntu /bin/bash
 
    # type exit to exit
@@ -150,7 +158,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 containers networking, by default UFW
+drop all `forwarding`, a first step is to enable forwarding:
 
 .. code-block:: bash
 
@@ -168,8 +177,9 @@ Then reload UFW:
    sudo ufw reload
 
 
-UFW's default set of rules denied all `incoming`, so if you want to be able to reach your containers from another host,
-you should allow incoming connections on the docker port (default 4243):
+UFW's default set of rules denied all `incoming`, so if you want to be
+able to reach your containers from another host, you should allow
+incoming connections on the docker port (default 4243):
 
 .. code-block:: bash
 

docs/sources/installation/upgrading.rst

@@ -5,18 +5,32 @@
 .. _upgrading:
 
 Upgrading
-============
+=========
 
-**These instructions are for upgrading Docker**
+The technique for upgrading ``docker`` to a newer version depends on
+how you installed ``docker``.
 
+.. versionadded:: 0.5.3
+   You may wish to add a ``docker`` group to your system to avoid using sudo with ``docker``. (see :ref:`dockergroup`)
 
-After normal installation
--------------------------
 
-If you installed Docker normally using apt-get or used Vagrant, use apt-get to upgrade.
+After ``apt-get``
+-----------------
+
+If you installed Docker using ``apt-get`` or Vagrant, then you should
+use ``apt-get`` to upgrade.
+
+.. versionadded:: 0.6
+   Add Docker repository information to your system first.
 
 .. code-block:: bash
 
+   # Add the Docker repository key to your local keychain
+   sudo sh -c "curl https://get.docker.io/gpg | apt-key add -"
+
+   # Add the Docker repository to your apt sources list.
+   sudo sh -c "echo deb https://get.docker.io/ubuntu docker main > /etc/apt/sources.list.d/docker.list"
+
    # update your sources list
    sudo apt-get update
 
@@ -27,7 +41,7 @@ If you installed Docker normally using apt-get or used Vagrant, use apt-get to u
 After manual installation
 -------------------------
 
-If you installed the Docker binary
+If you installed the Docker :ref:`binaries` then follow these steps:
 
 
 .. code-block:: bash
@@ -48,8 +62,10 @@ If you installed the Docker binary
    tar -xf docker-latest.tgz
 
 
-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.
+Start docker in daemon mode (``-d``) and disconnect, running the
+daemon in the background (``&``). Starting as ``./docker`` guarantees
+to run the version in your current directory rather than a version
+which might reside in your path.
 
 .. code-block:: bash
 

docs/sources/installation/vagrant.rst

@@ -2,31 +2,36 @@
 :description: This guide will setup a new virtualbox virtual machine with docker installed on your computer.
 :keywords: Docker, Docker documentation, virtualbox, vagrant, git, ssh, putty, cygwin
 
-**Vagrant installation is temporarily out of date, it will be updated for 0.6 soon.**
-
 .. _install_using_vagrant:
 
 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 install these and have at least 400Mb RAM
-to spare you should be good.
-
+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.
 
 Install Vagrant and Virtualbox
 ------------------------------
 
-1. Install virtualbox from https://www.virtualbox.org/ (or use your package manager)
-2. Install vagrant from http://www.vagrantup.com/ (or use your package manager)
-3. Install git if you had not installed it before, check if it is installed by running
-   ``git`` in a terminal window
+.. include:: install_header.inc
+
+.. include:: install_unofficial.inc
+
+#. Install virtualbox from https://www.virtualbox.org/ (or use your
+   package manager)
+#. Install vagrant from http://www.vagrantup.com/ (or use your package
+   manager)
+#. Install git if you had not installed it before, check if it is
+   installed by running ``git`` in a terminal window
 
 
 Spin it up
 ----------
 
-1. Fetch the docker sources (this includes the Vagrantfile for machine setup).
+1. Fetch the docker sources (this includes the ``Vagrantfile`` for
+   machine setup).
 
    .. code-block:: bash
 

docs/sources/installation/windows.rst

@@ -2,20 +2,20 @@
 :description: Docker's tutorial to run docker on Windows
 :keywords: Docker, Docker documentation, Windows, requirements, virtualbox, vagrant, git, ssh, putty, cygwin
 
-**Vagrant installation is temporarily out of date, it will be updated for 0.6 soon.**
-
 .. _windows:
 
 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
+Docker can run on Windows using a VM like VirtualBox. You then run
+Linux within the VM.
 
+Installation
+------------
 
+.. include:: install_header.inc
 
-Requirements
-------------
+.. include:: install_unofficial.inc
 
 1. Install virtualbox from https://www.virtualbox.org - or follow this tutorial__
 
@@ -35,7 +35,10 @@ We recommend having at least 2Gb of free disk space and 2Gb of RAM (or more).
 Opening a command prompt
 ------------------------
 
-First open a cmd prompt. Press Windows key and then press “R” key. This will open the RUN dialog box for you. Type “cmd” and press Enter. Or you can click on Start, type “cmd” in the “Search programs and files” field, and click on cmd.exe.
+First open a cmd prompt. Press Windows key and then press “R”
+key. This will open the RUN dialog box for you. Type “cmd” and press
+Enter. Or you can click on Start, type “cmd” in the “Search programs
+and files” field, and click on cmd.exe.
 
 .. image:: images/win/_01.gif
    :alt: Git install
@@ -47,14 +50,17 @@ This should open a cmd prompt window.
    :alt: run docker
    :align: center
 
-Alternatively, you can also use a Cygwin terminal, or Git Bash (or any other command line program you are usually using). The next steps would be the same.
+Alternatively, you can also use a Cygwin terminal, or Git Bash (or any
+other command line program you are usually using). The next steps
+would be the same.
 
 .. _launch_ubuntu:
 
 Launch an Ubuntu virtual server
 -------------------------------
 
-Let’s download and run an Ubuntu image with docker binaries already installed.
+Let’s download and run an Ubuntu image with docker binaries already
+installed.
 
 .. code-block:: bash
 
@@ -66,7 +72,9 @@ Let’s download and run an Ubuntu image with docker binaries already installed.
    :alt: run docker
    :align: center
 
-Congratulations! You are running an Ubuntu server with docker installed on it. You do not see it though, because it is running in the background.
+Congratulations! You are running an Ubuntu server with docker
+installed on it. You do not see it though, because it is running in
+the background.
 
 Log onto your Ubuntu server
 ---------------------------
@@ -85,7 +93,12 @@ Run the following command
 
 	vagrant ssh
 
-You may see an error message starting with “`ssh` executable not found”. In this case it means that you do not have SSH in your PATH. If you do not have SSH in your PATH you can set it up with the “set” command. For instance, if your ssh.exe is in the folder named “C:\Program Files (x86)\Git\bin”, then you can run the following command:
+You may see an error message starting with “`ssh` executable not
+found”. In this case it means that you do not have SSH in your
+PATH. If you do not have SSH in your PATH you can set it up with the
+“set” command. For instance, if your ssh.exe is in the folder named
+“C:\Program Files (x86)\Git\bin”, then you can run the following
+command:
 
 .. code-block:: bash
 
@@ -104,13 +117,16 @@ First step is to get the IP and port of your Ubuntu server. Simply run:
 
 	vagrant ssh-config 
 
-You should see an output with HostName and Port information. In this example, HostName is 127.0.0.1 and port is 2222. And the User is “vagrant”. The password is not shown, but it is also “vagrant”.
+You should see an output with HostName and Port information. In this
+example, HostName is 127.0.0.1 and port is 2222. And the User is
+“vagrant”. The password is not shown, but it is also “vagrant”.
 
 .. image:: images/win/ssh-config.gif
    :alt: run docker
    :align: center
 
-You can now use this information for connecting via SSH to your server. To do so you can:
+You can now use this information for connecting via SSH to your
+server. To do so you can:
 
 - Use putty.exe OR
 - Use SSH from a terminal
@@ -118,8 +134,9 @@ You can now use this information for connecting via SSH to your server. To do so
 Use putty.exe
 '''''''''''''
 
-You can download putty.exe from this page http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
-Launch putty.exe and simply enter the information you got from last step.
+You can download putty.exe from this page
+http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Launch
+putty.exe and simply enter the information you got from last step.
 
 .. image:: images/win/putty.gif
    :alt: run docker
@@ -134,7 +151,9 @@ Open, and enter user = vagrant and password = vagrant.
 SSH from a terminal
 '''''''''''''''''''
 
-You can also run this command on your favorite terminal (windows prompt, cygwin, git-bash, …). Make sure to adapt the IP and port from what you got from the vagrant ssh-config command.
+You can also run this command on your favorite terminal (windows
+prompt, cygwin, git-bash, …). Make sure to adapt the IP and port from
+what you got from the vagrant ssh-config command.
 
 .. code-block:: bash
 
@@ -146,12 +165,14 @@ Enter user = vagrant and password = vagrant.
    :alt: run docker
    :align: center
 
-Congratulations, you are now logged onto your Ubuntu Server, running on top of your Windows machine !
+Congratulations, you are now logged onto your Ubuntu Server, running
+on top of your Windows machine !
 
 Running Docker
 --------------
 
-First you have to be root in order to run docker. Simply run the following command:
+First you have to be root in order to run docker. Simply run the
+following command:
 
 .. code-block:: bash
 
@@ -179,10 +200,11 @@ VM does not boot
 
 .. image:: images/win/ts_go_bios.JPG
 
-If you run into this error message "The VM failed to remain in the 'running'
-state while attempting to boot", please check that your computer has virtualization
-technology available and activated by going to the BIOS. Here's an example for an HP
-computer (System configuration / Device configuration)
+If you run into this error message "The VM failed to remain in the
+'running' state while attempting to boot", please check that your
+computer has virtualization technology available and activated by
+going to the BIOS. Here's an example for an HP computer (System
+configuration / Device configuration)
 
 .. image:: images/win/hp_bios_vm.JPG
 
@@ -192,5 +214,6 @@ Docker is not installed
 
 .. image:: images/win/ts_no_docker.JPG
 
-If you run into this error message "The program 'docker' is currently not installed",
-try deleting the docker folder and restart from :ref:`launch_ubuntu`
+If you run into this error message "The program 'docker' is currently
+not installed", try deleting the docker folder and restart from
+:ref:`launch_ubuntu`

docs/sources/use/basics.rst

@@ -37,6 +37,8 @@ Running an interactive shell
   # use the escape sequence Ctrl-p + Ctrl-q
   sudo docker run -i -t ubuntu /bin/bash
 
+.. _dockergroup:
+
 Why ``sudo``?
 -------------