Merge pull request #3618 from shykes/docs-cleanup-install

Docs cleanup install

docs/sources/articles/index.rst

@@ -0,0 +1,12 @@
+:title: Docker articles
+:description: various articles related to Docker
+:keywords: docker, articles
+
+.. _articles_list:
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   security

docs/sources/index.rst

@@ -12,8 +12,7 @@ dependencies.
 
 ``docker`` runs three ways:
 
-* as a daemon to manage LXC containers on your :ref:`Linux host
-  <kernel>` (``sudo docker -d``)
+* as a daemon to manage LXC containers on your host machine (``sudo docker -d``)
 * as a :ref:`CLI <cli>` which talks to the daemon's `REST API
   <api/docker_remote_api>`_ (``docker run ...``)
 * as a client of :ref:`Repositories <working_with_the_repository>`

docs/sources/installation/binaries.rst

@@ -16,15 +16,29 @@ Before following these directions, you should really check if a packaged version
 of Docker is already available for your distribution.  We have packages for many
 distributions, and more keep showing up all the time!
 
-Check Your Kernel
------------------
 
-Your host's Linux kernel must meet the Docker :ref:`kernel`
-
-Check for User Space Tools
+Check runtime dependencies
 --------------------------
 
-You must have a working installation of the `lxc <http://linuxcontainers.org>`_ utilities and library.
+To run properly, docker needs the following software to be installed at runtime:
+
+- GNU Tar version 1.26 or later
+- iproute2 version 3.5 or later (build after 2012-05-21), and specifically the "ip" utility
+- iptables version 1.4 or later
+- The LXC utility scripts (http://lxc.sourceforge.net) version 0.8 or later
+- Git version 1.7 or later
+- XZ Utils 4.9 or later
+
+
+Check kernel dependencies
+-------------------------
+
+Docker in daemon mode has specific kernel requirements. For details, see
+http://docs.docker.io/en/latest/articles/kernel/
+
+Note that Docker also has a client mode, which can run on virtually any linux kernel (it even builds
+on OSX!).
+
 
 Get the docker binary:
 ----------------------
@@ -43,6 +57,17 @@ Run the docker daemon
     # start the docker in daemon mode from the directory you unpacked
     sudo ./docker -d &
 
+Upgrades
+--------
+
+To upgrade your manual installation of Docker, first kill the docker daemon:
+
+.. code-block:: bash
+
+   killall docker
+
+Then follow the regular installation steps.
+
 
 Run your first container!
 -------------------------

docs/sources/installation/index.rst

@@ -24,12 +24,9 @@ Contents:
    gentoolinux
    openSUSE
    frugalware
-   vagrant
+   mac
    windows
    amazon
    rackspace
    google
-   kernel
    binaries
-   security
-   upgrading

docs/sources/installation/kernel.rst

@@ -1,151 +0,0 @@
-:title: Kernel Requirements
-:description: Kernel supports
-:keywords: kernel requirements, kernel support, docker, installation, cgroups, namespaces
-
-.. _kernel:
-
-Kernel Requirements
-===================
-
-In short, Docker has the following kernel requirements:
-
-- Linux version 3.8 or above.
-
-- Cgroups and namespaces must be enabled.
-
-*Note: as of 0.7 docker no longer requires aufs. AUFS support is still available as an optional driver.*
-
-The officially supported kernel is the one recommended by the
-:ref:`ubuntu_linux` installation path. It is the one that most developers
-will use, and the one that receives the most attention from the core
-contributors. If you decide to go with a different kernel and hit a bug,
-please try to reproduce it with the official kernels first.
-
-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
---------------------------
-
-Kernel versions 3.2 to 3.5 are not stable when used with docker.
-In some circumstances, you will experience kernel "oopses", or even crashes.
-The symptoms include:
-
-- a container being killed in the middle of an operation (e.g. an ``apt-get``
-  command doesn't complete);
-- kernel messages including mentioning calls to ``mntput`` or
-  ``d_hash_and_lookup``;
-- 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.
-
-Docker checks the kernel version when it starts, and emits a warning if it
-detects something older than 3.8.
-
-See issue `#407 <https://github.com/dotcloud/docker/issues/407>`_ for details.
-
-
-Cgroups and namespaces
-----------------------
-
-You need to enable namespaces and cgroups, to the extent of what is needed
-to run LXC containers. Technically, while namespaces have been introduced
-in the early 2.6 kernels, we do not advise to try any kernel before 2.6.32
-to run LXC containers. Note that 2.6.32 has some documented issues regarding
-network namespace setup and teardown; those issues are not a risk if you
-run containers in a private environment, but can lead to denial-of-service
-attacks if you want to run untrusted code in your containers. For more details,
-see `LP#720095 <https://bugs.launchpad.net/ubuntu/+source/linux/+bug/720095>`_.
-
-Kernels 2.6.38, and every version since 3.2, have been deployed successfully
-to run containerized production workloads. Feature-wise, there is no huge
-improvement between 2.6.38 and up to 3.6 (as far as docker is concerned!).
-
-
-
-
-Extra Cgroup Controllers
-------------------------
-
-Most control groups can be enabled or disabled individually. For instance,
-you can decide that you do not want to compile support for the CPU or memory
-controller. In some cases, the feature can be enabled or disabled at boot
-time. It is worth mentioning that some distributions (like Debian) disable
-"expensive" features, like the memory controller, because they can have
-a significant performance impact.
-
-In the specific case of the memory cgroup, docker will detect if the cgroup
-is available or not. If it's not, it will print a warning, and it won't
-use the feature. If you want to enable that feature -- read on!
-
-
-Memory and Swap Accounting on Debian/Ubuntu
--------------------------------------------
-
-If you use Debian or Ubuntu kernels, and want to enable memory and swap
-accounting, you must add the following command-line parameters to your kernel::
-
-    cgroup_enable=memory swapaccount=1
-
-On Debian or Ubuntu systems, if you use the default GRUB bootloader, you can
-add those parameters by editing ``/etc/default/grub`` and extending
-``GRUB_CMDLINE_LINUX``. Look for the following line::
-
-    GRUB_CMDLINE_LINUX=""
-
-And replace it by the following one::
-
-    GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1"
-
-Then run ``update-grub``, and reboot.
-
-Details
--------
-
-To automatically check some of the requirements below, you can run `lxc-checkconfig`.
-
-Networking:
-
-- CONFIG_BRIDGE
-- CONFIG_NETFILTER_XT_MATCH_ADDRTYPE
-- CONFIG_NF_NAT
-- CONFIG_NF_NAT_IPV4
-- CONFIG_NF_NAT_NEEDED
-
-LVM:
-
-- CONFIG_BLK_DEV_DM
-- CONFIG_DM_THIN_PROVISIONING
-- CONFIG_EXT4_FS
-
-Namespaces:
-
-- CONFIG_NAMESPACES
-- CONFIG_UTS_NS
-- CONFIG_IPC_NS
-- CONFIG_PID_NS
-- CONFIG_NET_NS
-
-Cgroups:
-
-- CONFIG_CGROUPS
-
-Cgroup controllers (optional but highly recommended):
-
-- CONFIG_CGROUP_CPUACCT
-- CONFIG_BLK_CGROUP
-- CONFIG_MEMCG
-- CONFIG_MEMCG_SWAP

docs/sources/installation/vagrant.rst → docs/sources/installation/mac.rst

@@ -1,16 +1,14 @@
-:title: Using Vagrant (Mac, Linux)
-: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
+:title: Installing Docker on a Mac
+:description: Installing Docker on a Mac
+:keywords: Docker, Docker documentation, virtualbox, git, ssh
 
 .. _install_using_vagrant:
 
-Using Vagrant (Mac, Linux)
+Installing Docker on a Mac
 ==========================
 
-This guide will setup a new virtualbox virtual machine with docker
-installed on your computer. This works on most operating systems,
-including MacOSX, Windows, Linux, FreeBSD and others. If you can
-install these and have at least 400MB RAM to spare you should be good.
+This guide explains how to install a full Docker setup on your Mac,
+using Virtualbox and Vagrant.
 
 Install Vagrant and Virtualbox
 ------------------------------
@@ -67,8 +65,28 @@ To access the VM and use Docker, Run ``vagrant ssh`` from the same directory as
 
    vagrant ssh
 
+
+Upgrades
+--------
+
+Since your local VM is based on Ubuntu, you can upgrade docker by logging in to the
+VM and calling ``apt-get``:
+
+
+.. code-block:: bash
+
+   # Log into the VM
+   vagrant ssh
+
+   # update your sources list
+   sudo apt-get update
+
+   # install the latest
+   sudo apt-get install lxc-docker
+
+
 Run
------
+---
 
 Now you are in the VM, run docker
 

docs/sources/installation/ubuntulinux.rst

@@ -167,6 +167,21 @@ Type ``exit`` to exit
 
 **Done!**, now continue with the :ref:`hello_world` example.
 
+Upgrades
+--------
+
+To install the latest version of docker, use the standard ``apt-get`` method:
+
+
+.. code-block:: bash
+
+   # update your sources list
+   sudo apt-get update
+
+   # install the latest
+   sudo apt-get install lxc-docker
+
+
 .. _ufw:
 
 Docker and UFW

docs/sources/installation/upgrading.rst

@@ -1,73 +0,0 @@
-:title: Upgrading
-:description: These instructions are for upgrading Docker
-:keywords: Docker, Docker documentation, upgrading docker, upgrade
-
-.. _upgrading:
-
-Upgrading
-=========
-
-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 ``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 apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 36A1D7869245C8950F966E92D8576A8BA88D21E9
-
-   # 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
-
-   # install the latest
-   sudo apt-get install lxc-docker
-
-
-After manual installation
--------------------------
-
-If you installed the Docker :ref:`binaries` then follow these steps:
-
-
-.. code-block:: bash
-
-   # kill the running docker daemon
-   killall docker
-
-
-.. code-block:: bash
-
-   # get the latest binary
-   wget http://get.docker.io/builds/Linux/x86_64/docker-latest -O docker
-   
-   # make it executable
-   chmod +x docker
-
-
-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
-
-   # start the new version
-   sudo ./docker -d &
-
-
-Alternatively you can replace the docker binary in ``/usr/local/bin``.

docs/sources/installation/windows.rst

@@ -4,8 +4,8 @@
 
 .. _windows:
 
-Using Vagrant (Windows)
-=======================
+Installing Docker on Windows
+============================
 
 Docker can run on Windows using a VM like VirtualBox. You then run
 Linux within the VM.

docs/sources/toctree.rst

@@ -15,6 +15,8 @@ This documentation has the following resources:
    use/index
    examples/index
    reference/index
+   commandline/index
    contributing/index
    terms/index
    faq
+   articles/index