diff --git a/components/engine/docs/sources/articles/index.rst b/components/engine/docs/sources/articles/index.rst new file mode 100644 index 0000000000..be01a7af32 --- /dev/null +++ b/components/engine/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 diff --git a/components/engine/docs/sources/installation/security.rst b/components/engine/docs/sources/articles/security.rst similarity index 100% rename from components/engine/docs/sources/installation/security.rst rename to components/engine/docs/sources/articles/security.rst diff --git a/components/engine/docs/sources/index.rst b/components/engine/docs/sources/index.rst index 1fb82f3bec..c10ed2abf9 100644 --- a/components/engine/docs/sources/index.rst +++ b/components/engine/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 - ` (``sudo docker -d``) +* as a daemon to manage LXC containers on your host machine (``sudo docker -d``) * as a :ref:`CLI ` which talks to the daemon's `REST API `_ (``docker run ...``) * as a client of :ref:`Repositories ` diff --git a/components/engine/docs/sources/installation/binaries.rst b/components/engine/docs/sources/installation/binaries.rst index f06a8d6c5f..611429f84a 100644 --- a/components/engine/docs/sources/installation/binaries.rst +++ b/components/engine/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 `_ 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! ------------------------- diff --git a/components/engine/docs/sources/installation/index.rst b/components/engine/docs/sources/installation/index.rst index 9ebe484f6e..04c155d885 100644 --- a/components/engine/docs/sources/installation/index.rst +++ b/components/engine/docs/sources/installation/index.rst @@ -24,12 +24,9 @@ Contents: gentoolinux openSUSE frugalware - vagrant + mac windows amazon rackspace google - kernel binaries - security - upgrading diff --git a/components/engine/docs/sources/installation/kernel.rst b/components/engine/docs/sources/installation/kernel.rst deleted file mode 100644 index 88822ad37d..0000000000 --- a/components/engine/docs/sources/installation/kernel.rst +++ /dev/null @@ -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 `_ 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 `_. - -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 diff --git a/components/engine/docs/sources/installation/vagrant.rst b/components/engine/docs/sources/installation/mac.rst similarity index 71% rename from components/engine/docs/sources/installation/vagrant.rst rename to components/engine/docs/sources/installation/mac.rst index 81acf76f5e..569fa1f838 100644 --- a/components/engine/docs/sources/installation/vagrant.rst +++ b/components/engine/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 diff --git a/components/engine/docs/sources/installation/ubuntulinux.rst b/components/engine/docs/sources/installation/ubuntulinux.rst index 8480979099..17eee15e9a 100644 --- a/components/engine/docs/sources/installation/ubuntulinux.rst +++ b/components/engine/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 diff --git a/components/engine/docs/sources/installation/upgrading.rst b/components/engine/docs/sources/installation/upgrading.rst deleted file mode 100644 index c760115545..0000000000 --- a/components/engine/docs/sources/installation/upgrading.rst +++ /dev/null @@ -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``. diff --git a/components/engine/docs/sources/installation/windows.rst b/components/engine/docs/sources/installation/windows.rst index b487606a48..c980a32df9 100644 --- a/components/engine/docs/sources/installation/windows.rst +++ b/components/engine/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. diff --git a/components/engine/docs/sources/toctree.rst b/components/engine/docs/sources/toctree.rst index 2807ea5932..89d63b933f 100644 --- a/components/engine/docs/sources/toctree.rst +++ b/components/engine/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