From ce35f5d89939a20c7e9a5466f837b1ac919609fc Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Wed, 15 May 2013 16:11:59 -0700 Subject: [PATCH 1/4] Updated the entire installation section text, checked everything, cleaned up rackspace installation. --- 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/docs/sources/installation/amazon.rst b/docs/sources/installation/amazon.rst index 012c78f401..64ff20f8be 100644 --- a/docs/sources/installation/amazon.rst +++ b/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/docs/sources/installation/binaries.rst b/docs/sources/installation/binaries.rst index 2607f3680f..6dd6dff3bd 100644 --- a/docs/sources/installation/binaries.rst +++ b/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/docs/sources/installation/index.rst b/docs/sources/installation/index.rst index aaa1cc1959..698d7f8ff1 100644 --- a/docs/sources/installation/index.rst +++ b/docs/sources/installation/index.rst @@ -14,9 +14,9 @@ Contents: ubuntulinux binaries - archlinux vagrant windows amazon rackspace + archlinux upgrading diff --git a/docs/sources/installation/rackspace.rst b/docs/sources/installation/rackspace.rst index 51f13f4732..dfb88aee84 100644 --- a/docs/sources/installation/rackspace.rst +++ b/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/docs/sources/installation/ubuntulinux.rst b/docs/sources/installation/ubuntulinux.rst index 972844cc18..de4a2bb9ca 100644 --- a/docs/sources/installation/ubuntulinux.rst +++ b/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/docs/sources/installation/upgrading.rst b/docs/sources/installation/upgrading.rst index a5172b6d76..8dfde73891 100644 --- a/docs/sources/installation/upgrading.rst +++ b/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/docs/sources/installation/vagrant.rst b/docs/sources/installation/vagrant.rst index 465a6c3388..d1a76b5a2b 100644 --- a/docs/sources/installation/vagrant.rst +++ b/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/docs/sources/installation/windows.rst b/docs/sources/installation/windows.rst index a89d3a9014..230ac78051 100644 --- a/docs/sources/installation/windows.rst +++ b/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 From 2ebbd2d6367e9bf83f2ea3f28f7a0f462260913d Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Wed, 15 May 2013 16:13:20 -0700 Subject: [PATCH 2/4] Clean up of unnecessary files. --- docs/sources/.nojekyll | 0 docs/sources/CNAME | 1 - docs/sources/dotcloud.yml | 2 - docs/sources/gettingstarted/index.html | 210 ----------------- docs/sources/index.html | 314 ------------------------- docs/sources/nginx.conf | 6 - 6 files changed, 533 deletions(-) delete mode 100644 docs/sources/.nojekyll delete mode 100644 docs/sources/CNAME delete mode 100644 docs/sources/dotcloud.yml delete mode 100644 docs/sources/gettingstarted/index.html delete mode 100644 docs/sources/index.html delete mode 100644 docs/sources/nginx.conf diff --git a/docs/sources/.nojekyll b/docs/sources/.nojekyll deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/sources/CNAME b/docs/sources/CNAME deleted file mode 100644 index 243e482261..0000000000 --- a/docs/sources/CNAME +++ /dev/null @@ -1 +0,0 @@ -docker.io diff --git a/docs/sources/dotcloud.yml b/docs/sources/dotcloud.yml deleted file mode 100644 index 5a8f50f9e9..0000000000 --- a/docs/sources/dotcloud.yml +++ /dev/null @@ -1,2 +0,0 @@ -www: - type: static \ No newline at end of file diff --git a/docs/sources/gettingstarted/index.html b/docs/sources/gettingstarted/index.html deleted file mode 100644 index 96175d6dec..0000000000 --- a/docs/sources/gettingstarted/index.html +++ /dev/null @@ -1,210 +0,0 @@ - - - - - - - - - - Docker - the Linux container runtime - - - - - - - - - - - - - - - - - - - - -
-
-
- -
- - - -
- -
- -
-
-
-
- - -
-
-

GETTING STARTED

-
-
- -
- -
-
- Docker is still under heavy development. It should not yet be used in production. Check the repo for recent progress. -
-
-
-
-

- - Installing on Ubuntu

- -

Requirements

-
    -
  • Ubuntu 12.04 (LTS) (64-bit)
    • -
  • or Ubuntu 12.10 (quantal) (64-bit)
    • -
-
    -
  1. -

    Install dependencies

    - The linux-image-extra package is only needed on standard Ubuntu EC2 AMIs in order to install the aufs kernel module. - 
    sudo apt-get install linux-image-extra-`uname -r`
    - - -
    2. -
  2. -

    Install Docker

    -

    Add the Ubuntu PPA (Personal Package Archive) sources to your apt sources list, update and install.

    -

    You may see some warnings that the GPG keys cannot be verified.

    -
    - 
    sudo sh -c "echo 'deb http://ppa.launchpad.net/dotcloud/lxc-docker/ubuntu precise main' >> /etc/apt/sources.list"
    - 
    sudo apt-get update
    - 
    sudo apt-get install lxc-docker
    -
    - - -
    3. - -
  3. -

    Run!

    - -
    - 
    docker run -i -t ubuntu /bin/bash
    -
    -
    4. - Continue with the Hello world example. -
-
- -
-

Contributing to Docker

- -

Want to hack on Docker? Awesome! We have some instructions to get you started. They are probably not perfect, please let us know if anything feels wrong or incomplete.

-
- -
-
-
-

Quick install on other operating systems

-

For other operating systems we recommend and provide a streamlined install with virtualbox, - vagrant and an Ubuntu virtual machine.

- - - -
- -
-

More resources

- -
- - -
-
- Fill out my online form. -
- -
- -
-
-
- - -
-
-
- -
- -
-
- -
-
- -
-
- - - - - - - - - - - diff --git a/docs/sources/index.html b/docs/sources/index.html deleted file mode 100644 index 44a1cc737c..0000000000 --- a/docs/sources/index.html +++ /dev/null @@ -1,314 +0,0 @@ - - - - - - - - - - - Docker - the Linux container engine - - - - - - - - - - - - - - - - - - - - - - -
-
-
- -
- - - -
-
-
-
- - -
-
- -
-
- -
-
- - -

The Linux container engine

-
- -
- -
- Docker is an open-source engine which automates the deployment of applications as highly portable, self-sufficient containers which are independent of hardware, language, framework, packaging system and hosting provider. -
- -
- - - - -
- -
-
- -
-
- -
-
-
-
-
- -
-
- -
-
-

Heterogeneous payloads

-

Any combination of binaries, libraries, configuration files, scripts, virtualenvs, jars, gems, tarballs, you name it. No more juggling between domain-specific tools. Docker can deploy and run them all.

-

Any server

-

Docker can run on any x64 machine with a modern linux kernel - whether it's a laptop, a bare metal server or a VM. This makes it perfect for multi-cloud deployments.

-

Isolation

-

Docker isolates processes from each other and from the underlying host, using lightweight containers.

-

Repeatability

-

Because each container is isolated in its own filesystem, they behave the same regardless of where, when, and alongside what they run.

-
-
-
-
-

New! Docker Index

- On the Docker Index you can find and explore pre-made container images. It allows you to share your images and download them. - -

- -
- DOCKER index -
- -   - - -
-
-
- Fill out my online form. -
- -
-
-
- -
- - - - -
-
-
-
- - John Willis @botchagalupe: IMHO docker is to paas what chef was to Iaas 4 years ago -
-
-
-
- - John Feminella ‏@superninjarobot: So, @getdocker is pure excellence. If you've ever wished for arbitrary, PaaS-agnostic, lxc/aufs Linux containers, this is your jam! -
-
-
-
-
-
- - David Romulan ‏@destructuring: I haven't had this much fun since AWS -
-
-
-
- - Ricardo Gladwell ‏@rgladwell: wow @getdocker is either amazing or totally stupid -
-
- -
-
- -
-
-
- -
- -

Notable features

- -
    -
  • Filesystem isolation: each process container runs in a completely separate root filesystem.
    • -
  • Resource isolation: system resources like cpu and memory can be allocated differently to each process container, using cgroups.
    • -
  • Network isolation: each process container runs in its own network namespace, with a virtual interface and IP address of its own.
    • -
  • Copy-on-write: root filesystems are created using copy-on-write, which makes deployment extremeley fast, memory-cheap and disk-cheap.
    • -
  • Logging: the standard streams (stdout/stderr/stdin) of each process container is collected and logged for real-time or batch retrieval.
    • -
  • Change management: changes to a container's filesystem can be committed into a new image and re-used to create more containers. No templating or manual configuration required.
    • -
  • Interactive shell: docker can allocate a pseudo-tty and attach to the standard input of any container, for example to run a throwaway interactive shell.
    • -
- -

Under the hood

- -

Under the hood, Docker is built on the following components:

- -
    -
  • The cgroup and namespacing capabilities of the Linux kernel;
    • -
  • AUFS, a powerful union filesystem with copy-on-write capabilities;
    • -
  • The Go programming language;
    • -
  • lxc, a set of convenience scripts to simplify the creation of linux containers.
    • -
- -

Who started it

-

- Docker is an open-source implementation of the deployment engine which powers dotCloud, a popular Platform-as-a-Service.

- -

It benefits directly from the experience accumulated over several years of large-scale operation and support of hundreds of thousands - of applications and databases. -

- -
-
- -
- - -
-

Twitter

- - -
- -
-
- -
- - -
-
-
-
- - Docker is a project by dotCloud - -
-
- -
-
- -
-
- -
-
- - - - - - - - - - - - diff --git a/docs/sources/nginx.conf b/docs/sources/nginx.conf deleted file mode 100644 index 97ffd2c0e5..0000000000 --- a/docs/sources/nginx.conf +++ /dev/null @@ -1,6 +0,0 @@ - -# rule to redirect original links created when hosted on github pages -rewrite ^/documentation/(.*).html http://docs.docker.io/en/latest/$1/ permanent; - -# rewrite the stuff which was on the current page -rewrite ^/gettingstarted.html$ /gettingstarted/ permanent; From b5c1b17b50cf7d0fdc9c8894d10bb285d2e755b4 Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Wed, 15 May 2013 16:19:18 -0700 Subject: [PATCH 3/4] Updated getting started on website. --- docs/website/gettingstarted/index.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/website/gettingstarted/index.html b/docs/website/gettingstarted/index.html index c005cfc9f9..05745d966f 100644 --- a/docs/website/gettingstarted/index.html +++ b/docs/website/gettingstarted/index.html @@ -76,6 +76,7 @@
  • Ubuntu 12.04 (LTS) (64-bit)
  • or Ubuntu 12.10 (quantal) (64-bit)
    • +
  • The 3.8 Linux Kernel
  1. @@ -105,7 +106,8 @@ 
    docker run -i -t ubuntu /bin/bash
    2. - Continue with the Hello world example. + Continue with the Hello world example.
    + Or check more detailed installation instructions
From 8454a86e9733b3eddc6dcd5583bef58785a550d7 Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Wed, 15 May 2013 20:00:20 -0700 Subject: [PATCH 4/4] Mostly changes to the html, moved pages, fixed links. * Moved the introduction page to the en/latest/index.html home of the documentation and pointed all links there * Fixed a broken link from+to homepage * Fixed the javascript of the documentation navigation to allow expand and collapse multiple times. * Fixed the one typo Andy pointed out --- docs/sources/commandline/index.rst | 2 +- docs/sources/concepts/index.rst | 2 +- docs/sources/concepts/introduction.rst | 2 - docs/sources/conf.py | 2 +- docs/sources/index.rst | 137 ++++++++++++++++++++++--- docs/sources/installation/binaries.rst | 2 +- docs/sources/toctree.rst | 22 ++++ docs/theme/docker/layout.html | 121 ++++++++++++---------- docs/website/gettingstarted/index.html | 2 +- docs/website/index.html | 4 +- 10 files changed, 219 insertions(+), 77 deletions(-) create mode 100644 docs/sources/toctree.rst diff --git a/docs/sources/commandline/index.rst b/docs/sources/commandline/index.rst index 179903f80d..fecf8e4885 100644 --- a/docs/sources/commandline/index.rst +++ b/docs/sources/commandline/index.rst @@ -9,7 +9,7 @@ Commands Contents: .. toctree:: - :maxdepth: 3 + :maxdepth: 1 cli attach diff --git a/docs/sources/concepts/index.rst b/docs/sources/concepts/index.rst index 9156524999..d8e1af5770 100644 --- a/docs/sources/concepts/index.rst +++ b/docs/sources/concepts/index.rst @@ -12,6 +12,6 @@ Contents: .. toctree:: :maxdepth: 1 - introduction + ../index buildingblocks diff --git a/docs/sources/concepts/introduction.rst b/docs/sources/concepts/introduction.rst index 9c953d8582..fcdd37a791 100644 --- a/docs/sources/concepts/introduction.rst +++ b/docs/sources/concepts/introduction.rst @@ -2,8 +2,6 @@ :description: An introduction to docker and standard containers? :keywords: containers, lxc, concepts, explanation -.. _introduction: - Introduction ============ diff --git a/docs/sources/conf.py b/docs/sources/conf.py index 4c54d8bb62..d443d34052 100644 --- a/docs/sources/conf.py +++ b/docs/sources/conf.py @@ -41,7 +41,7 @@ html_add_permalinks = None # The master toctree document. -master_doc = 'index' +master_doc = 'toctree' # General information about the project. project = u'Docker' diff --git a/docs/sources/index.rst b/docs/sources/index.rst index fc46ca8255..172f82083c 100644 --- a/docs/sources/index.rst +++ b/docs/sources/index.rst @@ -1,22 +1,127 @@ -:title: docker documentation -:description: docker documentation -:keywords: +:title: Introduction +:description: An introduction to docker and standard containers? +:keywords: containers, lxc, concepts, explanation -Documentation -============= +.. _introduction: -This documentation has the following resources: +Introduction +============ -.. toctree:: - :maxdepth: 1 +Docker - The Linux container runtime +------------------------------------ - concepts/index - installation/index - use/index - examples/index - commandline/index - contributing/index - api/index - faq +Docker complements LXC with a high-level API which operates at the process level. It runs unix processes with strong guarantees of isolation and repeatability across servers. + +Docker is a great building block for automating distributed systems: large-scale web deployments, database clusters, continuous deployment systems, private PaaS, service-oriented architectures, etc. + + +- **Heterogeneous payloads** Any combination of binaries, libraries, configuration files, scripts, virtualenvs, jars, gems, tarballs, you name it. No more juggling between domain-specific tools. Docker can deploy and run them all. +- **Any server** Docker can run on any x64 machine with a modern linux kernel - whether it's a laptop, a bare metal server or a VM. This makes it perfect for multi-cloud deployments. +- **Isolation** docker isolates processes from each other and from the underlying host, using lightweight containers. +- **Repeatability** Because containers are isolated in their own filesystem, they behave the same regardless of where, when, and alongside what they run. .. image:: concepts/images/lego_docker.jpg + + +What is a Standard Container? +----------------------------- + +Docker defines a unit of software delivery called a Standard Container. The goal of a Standard Container is to encapsulate a software component and all its dependencies in +a format that is self-describing and portable, so that any compliant runtime can run it without extra dependency, regardless of the underlying machine and the contents of the container. + +The spec for Standard Containers is currently work in progress, but it is very straightforward. It mostly defines 1) an image format, 2) a set of standard operations, and 3) an execution environment. + +A great analogy for this is the shipping container. Just like Standard Containers are a fundamental unit of software delivery, shipping containers (http://bricks.argz.com/ins/7823-1/12) are a fundamental unit of physical delivery. + +Standard operations +~~~~~~~~~~~~~~~~~~~ + +Just like shipping containers, Standard Containers define a set of STANDARD OPERATIONS. Shipping containers can be lifted, stacked, locked, loaded, unloaded and labelled. Similarly, standard containers can be started, stopped, copied, snapshotted, downloaded, uploaded and tagged. + + +Content-agnostic +~~~~~~~~~~~~~~~~~~~ + +Just like shipping containers, Standard Containers are CONTENT-AGNOSTIC: all standard operations have the same effect regardless of the contents. A shipping container will be stacked in exactly the same way whether it contains Vietnamese powder coffee or spare Maserati parts. Similarly, Standard Containers are started or uploaded in the same way whether they contain a postgres database, a php application with its dependencies and application server, or Java build artifacts. + + +Infrastructure-agnostic +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Both types of containers are INFRASTRUCTURE-AGNOSTIC: they can be transported to thousands of facilities around the world, and manipulated by a wide variety of equipment. A shipping container can be packed in a factory in Ukraine, transported by truck to the nearest routing center, stacked onto a train, loaded into a German boat by an Australian-built crane, stored in a warehouse at a US facility, etc. Similarly, a standard container can be bundled on my laptop, uploaded to S3, downloaded, run and snapshotted by a build server at Equinix in Virginia, uploaded to 10 staging servers in a home-made Openstack cluster, then sent to 30 production instances across 3 EC2 regions. + + +Designed for automation +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Because they offer the same standard operations regardless of content and infrastructure, Standard Containers, just like their physical counterpart, are extremely well-suited for automation. In fact, you could say automation is their secret weapon. + +Many things that once required time-consuming and error-prone human effort can now be programmed. Before shipping containers, a bag of powder coffee was hauled, dragged, dropped, rolled and stacked by 10 different people in 10 different locations by the time it reached its destination. 1 out of 50 disappeared. 1 out of 20 was damaged. The process was slow, inefficient and cost a fortune - and was entirely different depending on the facility and the type of goods. + +Similarly, before Standard Containers, by the time a software component ran in production, it had been individually built, configured, bundled, documented, patched, vendored, templated, tweaked and instrumented by 10 different people on 10 different computers. Builds failed, libraries conflicted, mirrors crashed, post-it notes were lost, logs were misplaced, cluster updates were half-broken. The process was slow, inefficient and cost a fortune - and was entirely different depending on the language and infrastructure provider. + + +Industrial-grade delivery +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are 17 million shipping containers in existence, packed with every physical good imaginable. Every single one of them can be loaded on the same boats, by the same cranes, in the same facilities, and sent anywhere in the World with incredible efficiency. It is embarrassing to think that a 30 ton shipment of coffee can safely travel half-way across the World in *less time* than it takes a software team to deliver its code from one datacenter to another sitting 10 miles away. + +With Standard Containers we can put an end to that embarrassment, by making INDUSTRIAL-GRADE DELIVERY of software a reality. + + +Standard Container Specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(TODO) + +Image format +~~~~~~~~~~~~ + +Standard operations +~~~~~~~~~~~~~~~~~~~ + +- Copy +- Run +- Stop +- Wait +- Commit +- Attach standard streams +- List filesystem changes +- ... + +Execution environment +~~~~~~~~~~~~~~~~~~~~~ + +Root filesystem +^^^^^^^^^^^^^^^ + +Environment variables +^^^^^^^^^^^^^^^^^^^^^ + +Process arguments +^^^^^^^^^^^^^^^^^ + +Networking +^^^^^^^^^^ + +Process namespacing +^^^^^^^^^^^^^^^^^^^ + +Resource limits +^^^^^^^^^^^^^^^ + +Process monitoring +^^^^^^^^^^^^^^^^^^ + +Logging +^^^^^^^ + +Signals +^^^^^^^ + +Pseudo-terminal allocation +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Security +^^^^^^^^ + diff --git a/docs/sources/installation/binaries.rst b/docs/sources/installation/binaries.rst index 6dd6dff3bd..25d13ab68e 100644 --- a/docs/sources/installation/binaries.rst +++ b/docs/sources/installation/binaries.rst @@ -7,7 +7,7 @@ Binaries **This instruction set is meant for hackers who want to try out Docker on a variety of environments.** -Right now, the officially supported distribution are: +Right now, the officially supported distributions are: - :ref:`ubuntu_precise` - :ref:`ubuntu_raring` diff --git a/docs/sources/toctree.rst b/docs/sources/toctree.rst new file mode 100644 index 0000000000..09f2a7af5b --- /dev/null +++ b/docs/sources/toctree.rst @@ -0,0 +1,22 @@ +:title: docker documentation +:description: docker documentation +:keywords: + +Documentation +============= + +This documentation has the following resources: + +.. toctree:: + :titlesonly: + + concepts/index + installation/index + use/index + examples/index + commandline/index + contributing/index + api/index + faq + +.. image:: concepts/images/lego_docker.jpg diff --git a/docs/theme/docker/layout.html b/docs/theme/docker/layout.html index 1189ceb14b..aa5a24d496 100755 --- a/docs/theme/docker/layout.html +++ b/docs/theme/docker/layout.html @@ -66,7 +66,7 @@