From 68ac829d176e74a74bbad9fc71ec749aa5114513 Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Wed, 15 May 2013 16:11:59 -0700 Subject: [PATCH] Updated the entire installation section text, checked everything, cleaned up rackspace installation. Upstream-commit: ce35f5d89939a20c7e9a5466f837b1ac919609fc Component: engine --- .../docs/sources/installation/amazon.rst | 2 +- .../docs/sources/installation/binaries.rst | 46 ++-- .../docs/sources/installation/index.rst | 2 +- .../docs/sources/installation/rackspace.rst | 246 +++++------------- .../docs/sources/installation/ubuntulinux.rst | 107 ++++++-- .../docs/sources/installation/upgrading.rst | 51 ++-- .../docs/sources/installation/vagrant.rst | 10 +- .../docs/sources/installation/windows.rst | 4 +- 8 files changed, 211 insertions(+), 257 deletions(-) diff --git a/components/engine/docs/sources/installation/amazon.rst b/components/engine/docs/sources/installation/amazon.rst index 012c78f401..64ff20f8be 100644 --- a/components/engine/docs/sources/installation/amazon.rst +++ b/components/engine/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 diff --git a/components/engine/docs/sources/installation/binaries.rst b/components/engine/docs/sources/installation/binaries.rst index 2607f3680f..6dd6dff3bd 100644 --- a/components/engine/docs/sources/installation/binaries.rst +++ b/components/engine/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` - sudo apt-get install lxc bsdtar - sudo apt-get install linux-image-extra-`uname -r` -The linux-image-extra package is needed on standard Ubuntu EC2 AMIs in order to install the aufs kernel module. +Dependencies: +------------- -Install the docker binary: +* 3.8 Kernel +* AUFS filesystem support +* lxc +* bsdtar -:: + +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 - docker run -i -t ubuntu /bin/bash + # check your docker version + ./docker version + + # run a container and open an interactive shell in the container + ./docker run -i -t ubuntu /bin/bash diff --git a/components/engine/docs/sources/installation/index.rst b/components/engine/docs/sources/installation/index.rst index aaa1cc1959..698d7f8ff1 100644 --- a/components/engine/docs/sources/installation/index.rst +++ b/components/engine/docs/sources/installation/index.rst @@ -14,9 +14,9 @@ Contents: ubuntulinux binaries - archlinux vagrant windows amazon rackspace + archlinux upgrading diff --git a/components/engine/docs/sources/installation/rackspace.rst b/components/engine/docs/sources/installation/rackspace.rst index 51f13f4732..dfb88aee84 100644 --- a/components/engine/docs/sources/installation/rackspace.rst +++ b/components/engine/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@ +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@ - $ 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" + # update apt + apt-get update + + # install the new kernel + apt-get install linux-generic-lts-raring -2. Update your sources. You will see a warning that GPG signatures cannot be verified. +Great, now you have kernel installed in /boot/, next is to make it boot next time. .. code-block:: bash - $ sudo apt-get update + # find the exact names + find /boot/ -name '*3.8*' + + # this should return some results -3. Now install it, you will see another warning that the package cannot be authenticated. Confirm install. +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. .. code-block:: bash - $ apt-get install lxc-docker + # now edit /boot/grub/menu.lst + vi /boot/grub/menu.lst + +It will probably look something like this: + +:: + + ## ## End Default Options ## + + 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 + + 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 + + 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 -Ubuntu 12.10 ------------- +Reboot server (either via command line or console) -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 - .. code-block:: bash + # reboot - $ ssh root@ +Verify the kernel was updated -3. Once you are logged in you should check what kernel version you are running. +.. 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 - $ 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 + # nice! 3.8. -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 - - # 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@ - $ 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. - -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 - -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. - - .. code-block:: bash - - $ ssh root@ - -3. Once you are logged in you should check what kernel version you are running. - - .. 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 - -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. 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 - \ No newline at end of file +Now you can finish with the :ref:`ubuntu_linux` instructions. \ No newline at end of file diff --git a/components/engine/docs/sources/installation/ubuntulinux.rst b/components/engine/docs/sources/installation/ubuntulinux.rst index 972844cc18..de4a2bb9ca 100644 --- a/components/engine/docs/sources/installation/ubuntulinux.rst +++ b/components/engine/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 `_ which makes installing Docker on Ubuntu very easy. - - -Add the custom package sources to your apt sources list. Copy and paste the following lines at once. - .. code-block:: bash - sudo sh -c "echo 'deb http://ppa.launchpad.net/dotcloud/lxc-docker/ubuntu precise main' >> /etc/apt/sources.list" - - -Update your sources. You will see a warning that GPG signatures cannot be verified. - -.. 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" + # Update your sources, you will see a warning. sudo apt-get update - -Now install it, you will see another warning that the package cannot be authenticated. Confirm install. - -.. code-block:: bash - - apt-get install lxc-docker + # 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 - 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. + +.. _ubuntu_raring: + +Ubuntu Raring 13.04 (64 bit) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dependencies +------------ + +**AUFS filesystem support** + +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 `_ +which makes installing Docker on Ubuntu very easy. + + +Add the custom package sources to your apt sources list. + +.. code-block:: bash + + # 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 + + # 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. diff --git a/components/engine/docs/sources/installation/upgrading.rst b/components/engine/docs/sources/installation/upgrading.rst index a5172b6d76..8dfde73891 100644 --- a/components/engine/docs/sources/installation/upgrading.rst +++ b/components/engine/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 +After manual installation +------------------------- -Unpack it to your current dir +If you installed the Docker binary -:: +.. 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.tgz + + +.. code-block:: bash + + # Unpack it to your current dir tar -xf docker-latest.tgz -Stop your current daemon. How you stop your daemon depends on how you started it. +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. -- 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 - - -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. - -Now start the daemon - -:: +.. code-block:: bash + # start the new version sudo ./docker -d & diff --git a/components/engine/docs/sources/installation/vagrant.rst b/components/engine/docs/sources/installation/vagrant.rst index 465a6c3388..d1a76b5a2b 100644 --- a/components/engine/docs/sources/installation/vagrant.rst +++ b/components/engine/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. diff --git a/components/engine/docs/sources/installation/windows.rst b/components/engine/docs/sources/installation/windows.rst index a89d3a9014..230ac78051 100644 --- a/components/engine/docs/sources/installation/windows.rst +++ b/components/engine/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