1. docker
  2. Commit 156123226119f14070ce0e675466d231fe19189c
Browse code

First draft of new README. Feedback and contributions welcome!

Solomon Hykes authored on 2013/05/05 11:47:57
Showing 1 changed files
README.md
History View file @ 1561232
... ... 
@@ -1,37 +1,92 @@
1 
-Docker: the Linux container runtime
2 
-===================================
1 
+Docker: the Linux container engine
2 
+==================================
3 3
4 
-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.
4 
+Docker is an open-source engine which automates the deployment of applications as highly portable, self-sufficient containers.
5 5
6 
-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.
6 
+Docker containers are both *hardware-agnostic* and *platform-agnostic*. This means that they can run anywhere, from your
7 
+laptop to the largest EC2 compute instance and everything in between - and they don't require that you use a particular
8 
+language, framework or packaging system. That makes them great building blocks for deploying and scaling web apps, databases
9 
+and backend services without depending on a particular stack or provider.
7 10
8 
-![Docker L](docs/sources/static_files/lego_docker.jpg "Docker")
11 
+Docker is an open-source implementation of the deployment engine which powers [dotCloud](http://dotcloud.com), a popular Platform-as-a-Service.
12 
+It benefits directly from the experience accumulated over several years of large-scale operation and support of hundreds of thousands
13 
+of applications and databases.
9 14
10 
-* *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.
15 
+## Better than VMs
11 16
12 
-* *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.
17 
+A common method for distributing applications and sandbox their execution is to use virtual machines, or VMs. Typical VM formats
18 
+are VMWare's vmdk, Oracle Virtualbox's vdi, and Amazon EC2's ami. In theory these formats should allow every developer to
19 
+automatically package their application into a "machine" for easy distribution and deployment. In practice, that almost never
20 
+happens, for a few reasons:
13 21
14 
-* *Isolation*: docker isolates processes from each other and from the underlying host, using lightweight containers.
22 
+	* *Size*: VMs are very large which makes them impractical to store and transfer.
23 
+	* *Performance*: running VMs consumes significant CPU and memory, which makes them impractical in many scenarios, for example local development of multi-tier applications, and
24 
+		large-scale deployment of cpu and memory-intensive applications on large numbers of machines.
25 
+	* *Portability*: competing VM environments don't play well with each other. Although conversion tools do exist, they are limited and add even more overhead.
26 
+	* *Hardware-centric*: VMs were designed with machine operators in mind, not software developers. As a result, they offer very limited tooling for what developers need most:
27 
+		building, testing and running their software. For example, VMs offer no facilities for application versioning, monitoring, configuration, logging or service discovery.
15 28
16 
-* *Repeatability*: because containers are isolated in their own filesystem, they behave the same regardless of where, when, and alongside what they run.
29 
+By contrast, Docker relies on a different sandboxing method known as *containerization*. Unlike traditional virtualization,
30 
+containerization takes place at the kernel level. Most modern operating system kernels now support the primitives necessary
31 
+for containerization, including Linux with [openvz](http://openvz.org), [vserver](http://linux-vserver.org) and more recently [lxc](http://lxc.sourceforge.net),
32 
+	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).
17 33
34 
+Docker builds on top of these low-level primitives to offer developers a portable format and runtime environment that solves
35 
+all 4 problems. Docker containers are small (and their transfer can be optimized with layers), they have basically zero memory and cpu overhead,
36 
+the are completely portable and are designed from the ground up with an application-centric design.
18 37
19 
-Notable features
38 
+The best part: because docker operates at the OS level, it can still be run inside a VM!
20 39
21 
-* Filesystem isolation: each process container runs in a completely separate root filesystem.
40 
+## Plays well with others
22 41
23 
-* Resource isolation: system resources like cpu and memory can be allocated differently to each process container, using cgroups.
42 
+Docker does not require that you buy into a particular programming language, framework, packaging system or configuration language.
24 43
25 
-* Network isolation: each process container runs in its own network namespace, with a virtual interface and IP address of its own.
44 
+Is your application a unix process? Does it use files, tcp connections, environment variables, standard unix streams and command-line
45 
+arguments as inputs and outputs? Then docker can run it.
26 46
27 
-* Copy-on-write: root filesystems are created using copy-on-write, which makes deployment extremely fast, memory-cheap and disk-cheap.
47 
+Can your application's build be expressed a sequence of such commands? Then docker can build it.
28 48
29 
-* Logging: the standard streams (stdout/stderr/stdin) of each process container are collected and logged for real-time or batch retrieval.
30 49
31 
-* 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.
50 
+## Escape dependency hell
51 
+
52 
+A common problem for developers is the difficulty of managing all their application's dependencies in a simple and automated way.
53 
+
54 
+This is usually difficult for several reasons:
55 
+
56 
+  * *Cross-platform dependencies*. Modern applications often depend on a combination of system libraries and binaries, language-specific packages, framework-specific modules,
57 
+  	internal components developed for another project, etc. These dependencies live in different "worlds" and require different tools - these tools typically don't work
58 
+	well with each other, requiring awkward custom integrations.
59 
+
60 
+  * Conflicting dependencies. Different applications may depend on different versions of the same dependency. Packaging tools handle these situations with various degrees of ease -
61 
+  	but they all handle them in different and incompatible ways, which again forces the developer to do extra work.
62 
+
63 
+  * Custom dependencies. A developer may need to prepare a custom version of his application's dependency. Some packaging systems can handle custom versions of a dependency,
64 
+  	others can't - and all of them handle it differently.
65 
+
66 
+
67 
+Docker solves dependency hell by giving the developer a simple way to express *all* his application's dependencies in one place,
68 
+and streamline the process of assembling them. If this makes you think of [XKCD 927](http://xkcd.com/927/), don't worry. Docker doesn't
69 
+*replace* your favorite packaging systems. It simply orchestrates their use in a simple and repeatable way. How does it do that? With layers.
70 
+
71 
+Docker defines a build as running a sequence unix commands, one after the other, in the same container. Build commands modify the contents of the container
72 
+(usually by installing new files on the filesystem), the next command modifies it some more, etc. Since each build command inherits the result of the previous
73 
+commands, the *order* in which the commands are executed expresses *dependencies*.
74 
+
75 
+Here's a typical docker build process:
76 
+
77 
+```bash
78 
+from	ubuntu:12.10
79 
+run	apt-get update
80 
+run	apt-get install python
81 
+run	apt-get install python-pip
82 
+run	pip install django
83 
+run	apt-get install curl
84 
+run	curl http://github.com/shykes/helloflask/helloflask/master.tar.gz | tar -zxv
85 
+run	cd master && pip install -r requirements.txt
86 
+```
87 
+
88 
+Note that Docker doesn't care *how* dependencies are built - as long as they can be built by running a unix command in a container.
32 89
33 
-* 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.
34 90
35 91 
 Install instructions
36 92 
 ==================