From 046e6604e56ec93647550630fcf729c7e5ab3280 Mon Sep 17 00:00:00 2001 From: James Turnbull Date: Tue, 4 Mar 2014 07:53:22 -0500 Subject: [PATCH] Some updates to the README.md * Updated pre-reqs for 0.9. * Fixed a couple of docker to Docker. * Fixed the Docker build example to be correct. * Reformatted a bunch of paragraphs Docker-DCO-1.1-Signed-off-by: James Turnbull (github: jamtur01) --- README.md | 107 +++++++++++++++++++++++++----------------------------- 1 file changed, 49 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index b6b77d6e61..1922be5d8a 100644 --- a/README.md +++ b/README.md @@ -4,19 +4,19 @@ Docker: the Linux container engine Docker is an open source project to pack, ship and run any application as a lightweight container -Docker containers are both *hardware-agnostic* and -*platform-agnostic*. This means that they can run anywhere, from your -laptop to the largest EC2 compute instance and everything in between - -and they don't require that you use a particular language, framework -or packaging system. That makes them great building blocks for -deploying and scaling web apps, databases and backend services without -depending on a particular stack or provider. +Docker containers are both *hardware-agnostic* and *platform-agnostic*. +This means that they can run anywhere, from your laptop to the largest +EC2 compute instance and everything in between - and they don't require +that you use a particular language, framework or packaging system. That +makes them great building blocks for deploying and scaling web apps, +databases and backend services without depending on a particular stack +or provider. Docker is an open-source implementation of the deployment engine which -powers [dotCloud](http://dotcloud.com), 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. +powers [dotCloud](http://dotcloud.com), 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. ![Docker L](docs/theme/docker/static/img/dockerlogo-h.png "Docker") @@ -24,10 +24,10 @@ hundreds of thousands of applications and databases. A common method for distributing applications and sandboxing their execution is to use virtual machines, or VMs. Typical VM formats are -VMWare's vmdk, Oracle Virtualbox's vdi, and Amazon EC2's ami. In -theory these formats should allow every developer to automatically -package their application into a "machine" for easy distribution and -deployment. In practice, that almost never happens, for a few reasons: +VMWare's vmdk, Oracle Virtualbox's vdi, and Amazon EC2's ami. In theory +these formats should allow every developer to automatically package +their application into a "machine" for easy distribution and deployment. +In practice, that almost never happens, for a few reasons: * *Size*: VMs are very large which makes them impractical to store and transfer. @@ -47,39 +47,37 @@ deployment. In practice, that almost never happens, for a few reasons: service discovery. By contrast, Docker relies on a different sandboxing method known as -*containerization*. Unlike traditional virtualization, -containerization takes place at the kernel level. Most modern -operating system kernels now support the primitives necessary for -containerization, including Linux with [openvz](http://openvz.org), +*containerization*. Unlike traditional virtualization, containerization +takes place at the kernel level. Most modern operating system kernels +now support the primitives necessary for containerization, including +Linux with [openvz](http://openvz.org), [vserver](http://linux-vserver.org) and more recently [lxc](http://lxc.sourceforge.net), Solaris with [zones](http://docs.oracle.com/cd/E26502_01/html/E29024/preface-1.html#scrolltoc) and FreeBSD with [Jails](http://www.freebsd.org/doc/handbook/jails.html). -Docker builds on top of these low-level primitives to offer developers -a portable format and runtime environment that solves all 4 -problems. Docker containers are small (and their transfer can be -optimized with layers), they have basically zero memory and cpu -overhead, they are completely portable and are designed from the -ground up with an application-centric design. +Docker builds on top of these low-level primitives to offer developers a +portable format and runtime environment that solves all 4 problems. +Docker containers are small (and their transfer can be optimized with +layers), they have basically zero memory and cpu overhead, they are +completely portable and are designed from the ground up with an +application-centric design. -The best part: because ``docker`` operates at the OS level, it can -still be run inside a VM! +The best part: because Docker operates at the OS level, it can still be +run inside a VM! ## Plays well with others Docker does not require that you buy into a particular programming language, framework, packaging system or configuration language. -Is your application a Unix process? Does it use files, tcp -connections, environment variables, standard Unix streams and -command-line arguments as inputs and outputs? Then ``docker`` can run -it. +Is your application a Unix process? Does it use files, tcp connections, +environment variables, standard Unix streams and command-line arguments +as inputs and outputs? Then Docker can run it. Can your application's build be expressed as a sequence of such -commands? Then ``docker`` can build it. - +commands? Then Docker can build it. ## Escape dependency hell @@ -126,14 +124,11 @@ build command inherits the result of the previous commands, the Here's a typical Docker build process: ```bash -from ubuntu:12.10 -run apt-get update -run DEBIAN_FRONTEND=noninteractive apt-get install -q -y python -run DEBIAN_FRONTEND=noninteractive apt-get install -q -y python-pip -run pip install django -run DEBIAN_FRONTEND=noninteractive apt-get install -q -y curl -run curl -L https://github.com/shykes/helloflask/archive/master.tar.gz | tar -xzv -run cd helloflask-master && pip install -r requirements.txt +FROM ubuntu:12.04 +RUN apt-get update +RUN apt-get install -q -y python python-pip curl +RUN curl -L https://github.com/shykes/helloflask/archive/master.tar.gz | tar -xzv +RUN cd helloflask-master && pip install -r requirements.txt ``` Note that Docker doesn't care *how* dependencies are built - as long @@ -143,22 +138,25 @@ as they can be built by running a Unix command in a container. Getting started =============== -Docker can be installed on your local machine as well as servers - both bare metal and virtualized. -It is available as a binary on most modern Linux systems, or as a VM on Windows, Mac and other systems. +Docker can be installed on your local machine as well as servers - both +bare metal and virtualized. It is available as a binary on most modern +Linux systems, or as a VM on Windows, Mac and other systems. -We also offer an interactive tutorial for quickly learning the basics of using Docker. - - -For up-to-date install instructions and online tutorials, see the [Getting Started page](http://www.docker.io/gettingstarted/). +We also offer an interactive tutorial for quickly learning the basics of +using Docker. +For up-to-date install instructions and online tutorials, see the +[Getting Started page](http://www.docker.io/gettingstarted/). Usage examples ============== -Docker can be used to run short-lived commands, long-running daemons (app servers, databases etc.), -interactive shell sessions, etc. +Docker can be used to run short-lived commands, long-running daemons +(app servers, databases etc.), interactive shell sessions, etc. -You can find a [list of real-world examples](http://docs.docker.io/en/latest/examples/) in the documentation. +You can find a [list of real-world +examples](http://docs.docker.io/en/latest/examples/) in the +documentation. Under the hood -------------- @@ -170,13 +168,7 @@ Under the hood, Docker is built on the following components: and [namespacing](http://blog.dotcloud.com/under-the-hood-linux-kernels-on-dotcloud-part) capabilities of the Linux kernel; -* [AUFS](http://aufs.sourceforge.net/aufs.html), a powerful union - filesystem with copy-on-write capabilities; -* The [Go](http://golang.org) programming language; -* [lxc](http://lxc.sourceforge.net/), a set of convenience scripts to - simplify the creation of Linux containers. - - +* The [Go](http://golang.org) programming language. Contributing to Docker ====================== @@ -187,7 +179,6 @@ started [here](CONTRIBUTING.md). They are probably not perfect, please let us know if anything feels wrong or incomplete. - ### Legal *Brought to you courtesy of our legal counsel. For more context,