0ct0pu5/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
Docs cleanup install
This commit is contained in:
Andy Rothfusz 2014-01-20 17:10:02 -08:00
commit acf43b4da7
11 changed files with 91 additions and 247 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/sources/articles/index.rst Normal file
View file

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

0
docs/sources/installation/security.rst → docs/sources/articles/security.rst
View file

3
docs/sources/index.rst
View file

@ -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>`

37
docs/sources/installation/binaries.rst
View file

@ -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!
-------------------------

5
docs/sources/installation/index.rst
View file

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

151
docs/sources/installation/kernel.rst
View file

@ -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

36
docs/sources/installation/vagrant.rst → docs/sources/installation/mac.rst
View file

@ -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

15
docs/sources/installation/ubuntulinux.rst
View file

@ -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

73
docs/sources/installation/upgrading.rst
View file

@ -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``.

4
docs/sources/installation/windows.rst
View file

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

2
docs/sources/toctree.rst
View file

@ -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