github.com/christopherobin/docker@v1.6.2/README.md (about) 1 Docker: the Linux container engine 2 ================================== 3 4 Docker is an open source project to pack, ship and run any application 5 as a lightweight container 6 7 Docker containers are both *hardware-agnostic* and *platform-agnostic*. 8 This means they can run anywhere, from your laptop to the largest 9 EC2 compute instance and everything in between - and they don't require 10 you to use a particular language, framework or packaging system. That 11 makes them great building blocks for deploying and scaling web apps, 12 databases, and backend services without depending on a particular stack 13 or provider. 14 15 Docker began as an open-source implementation of the deployment engine which 16 powers [dotCloud](http://dotcloud.com), a popular Platform-as-a-Service. 17 It benefits directly from the experience accumulated over several years 18 of large-scale operation and support of hundreds of thousands of 19 applications and databases. 20 21 ![Docker L](docs/sources/static_files/docker-logo-compressed.png "Docker") 22 23 ## Security Disclosure 24 25 Security is very important to us. If you have any issue regarding security, 26 please disclose the information responsibly by sending an email to 27 security@docker.com and not by creating a github issue. 28 29 ## Better than VMs 30 31 A common method for distributing applications and sandboxing their 32 execution is to use virtual machines, or VMs. Typical VM formats are 33 VMWare's vmdk, Oracle Virtualbox's vdi, and Amazon EC2's ami. In theory 34 these formats should allow every developer to automatically package 35 their application into a "machine" for easy distribution and deployment. 36 In practice, that almost never happens, for a few reasons: 37 38 * *Size*: VMs are very large which makes them impractical to store 39 and transfer. 40 * *Performance*: running VMs consumes significant CPU and memory, 41 which makes them impractical in many scenarios, for example local 42 development of multi-tier applications, and large-scale deployment 43 of cpu and memory-intensive applications on large numbers of 44 machines. 45 * *Portability*: competing VM environments don't play well with each 46 other. Although conversion tools do exist, they are limited and 47 add even more overhead. 48 * *Hardware-centric*: VMs were designed with machine operators in 49 mind, not software developers. As a result, they offer very 50 limited tooling for what developers need most: building, testing 51 and running their software. For example, VMs offer no facilities 52 for application versioning, monitoring, configuration, logging or 53 service discovery. 54 55 By contrast, Docker relies on a different sandboxing method known as 56 *containerization*. Unlike traditional virtualization, containerization 57 takes place at the kernel level. Most modern operating system kernels 58 now support the primitives necessary for containerization, including 59 Linux with [openvz](http://openvz.org), 60 [vserver](http://linux-vserver.org) and more recently 61 [lxc](http://lxc.sourceforge.net), Solaris with 62 [zones](http://docs.oracle.com/cd/E26502_01/html/E29024/preface-1.html#scrolltoc), 63 and FreeBSD with 64 [Jails](http://www.freebsd.org/doc/handbook/jails.html). 65 66 Docker builds on top of these low-level primitives to offer developers a 67 portable format and runtime environment that solves all four problems. 68 Docker containers are small (and their transfer can be optimized with 69 layers), they have basically zero memory and cpu overhead, they are 70 completely portable, and are designed from the ground up with an 71 application-centric design. 72 73 Perhaps best of all, because Docker operates at the OS level, it can still be 74 run inside a VM! 75 76 ## Plays well with others 77 78 Docker does not require you to buy into a particular programming 79 language, framework, packaging system, or configuration language. 80 81 Is your application a Unix process? Does it use files, tcp connections, 82 environment variables, standard Unix streams and command-line arguments 83 as inputs and outputs? Then Docker can run it. 84 85 Can your application's build be expressed as a sequence of such 86 commands? Then Docker can build it. 87 88 ## Escape dependency hell 89 90 A common problem for developers is the difficulty of managing all 91 their application's dependencies in a simple and automated way. 92 93 This is usually difficult for several reasons: 94 95 * *Cross-platform dependencies*. Modern applications often depend on 96 a combination of system libraries and binaries, language-specific 97 packages, framework-specific modules, internal components 98 developed for another project, etc. These dependencies live in 99 different "worlds" and require different tools - these tools 100 typically don't work well with each other, requiring awkward 101 custom integrations. 102 103 * *Conflicting dependencies*. Different applications may depend on 104 different versions of the same dependency. Packaging tools handle 105 these situations with various degrees of ease - but they all 106 handle them in different and incompatible ways, which again forces 107 the developer to do extra work. 108 109 * *Custom dependencies*. A developer may need to prepare a custom 110 version of their application's dependency. Some packaging systems 111 can handle custom versions of a dependency, others can't - and all 112 of them handle it differently. 113 114 115 Docker solves the problem of dependency hell by giving the developer a simple 116 way to express *all* their application's dependencies in one place, while 117 streamlining the process of assembling them. If this makes you think of 118 [XKCD 927](http://xkcd.com/927/), don't worry. Docker doesn't 119 *replace* your favorite packaging systems. It simply orchestrates 120 their use in a simple and repeatable way. How does it do that? With 121 layers. 122 123 Docker defines a build as running a sequence of Unix commands, one 124 after the other, in the same container. Build commands modify the 125 contents of the container (usually by installing new files on the 126 filesystem), the next command modifies it some more, etc. Since each 127 build command inherits the result of the previous commands, the 128 *order* in which the commands are executed expresses *dependencies*. 129 130 Here's a typical Docker build process: 131 132 ```bash 133 FROM ubuntu:12.04 134 RUN apt-get update && apt-get install -y python python-pip curl 135 RUN curl -sSL https://github.com/shykes/helloflask/archive/master.tar.gz | tar -xzv 136 RUN cd helloflask-master && pip install -r requirements.txt 137 ``` 138 139 Note that Docker doesn't care *how* dependencies are built - as long 140 as they can be built by running a Unix command in a container. 141 142 143 Getting started 144 =============== 145 146 Docker can be installed on your local machine as well as servers - both 147 bare metal and virtualized. It is available as a binary on most modern 148 Linux systems, or as a VM on Windows, Mac and other systems. 149 150 We also offer an [interactive tutorial](http://www.docker.com/tryit/) 151 for quickly learning the basics of using Docker. 152 153 For up-to-date install instructions, see the [Docs](http://docs.docker.com). 154 155 Usage examples 156 ============== 157 158 Docker can be used to run short-lived commands, long-running daemons 159 (app servers, databases etc.), interactive shell sessions, etc. 160 161 You can find a [list of real-world 162 examples](http://docs.docker.com/examples/) in the 163 documentation. 164 165 Under the hood 166 -------------- 167 168 Under the hood, Docker is built on the following components: 169 170 * The 171 [cgroup](http://blog.dotcloud.com/kernel-secrets-from-the-paas-garage-part-24-c) 172 and 173 [namespacing](http://blog.dotcloud.com/under-the-hood-linux-kernels-on-dotcloud-part) 174 capabilities of the Linux kernel; 175 * The [Go](http://golang.org) programming language. 176 * The [Docker Image Specification] (https://github.com/docker/docker/blob/master/image/spec/v1.md) 177 * The [Libcontainer Specification] (https://github.com/docker/libcontainer/blob/master/SPEC.md) 178 179 Contributing to Docker 180 ====================== 181 182 [![GoDoc](https://godoc.org/github.com/docker/docker?status.png)](https://godoc.org/github.com/docker/docker) 183 [![Jenkins Build Status](https://jenkins.dockerproject.com/job/Docker%20Master/badge/icon)](https://jenkins.dockerproject.com/job/Docker%20Master/) 184 185 Want to hack on Docker? Awesome! We have [instructions to help you get 186 started contributing code or documentation.](https://docs.docker.com/project/who-written-for/). 187 188 These instructions are probably not perfect, please let us know if anything 189 feels wrong or incomplete. Better yet, submit a PR and improve them yourself. 190 191 Getting the development builds 192 ============================== 193 194 Want to run Docker from a master build? You can download 195 master builds at [master.dockerproject.com](https://master.dockerproject.com). 196 They are updated with each commit merged into the master branch. 197 198 Don't know how to use that super cool new feature in the master build? Check 199 out the master docs at 200 [docs.master.dockerproject.com](http://docs.master.dockerproject.com). 201 202 How the project is run 203 ====================== 204 205 Docker is a very, very active project. If you want to learn more about how it is run, 206 or want to get more involved, the best place to start is [the project directory](https://github.com/docker/docker/tree/master/project). 207 208 We are always open to suggestions on process improvements, and are always looking for more maintainers. 209 210 ### Legal 211 212 *Brought to you courtesy of our legal counsel. For more context, 213 please see the "NOTICE" document in this repo.* 214 215 Use and transfer of Docker may be subject to certain restrictions by the 216 United States and other governments. 217 It is your responsibility to ensure that your use and/or transfer does not 218 violate applicable laws. 219 220 For more information, please see http://www.bis.doc.gov 221 222 223 Licensing 224 ========= 225 Docker is licensed under the Apache License, Version 2.0. See 226 [LICENSE](https://github.com/docker/docker/blob/master/LICENSE) for the full 227 license text. 228 229 Other Docker Related Projects 230 ============================= 231 There are a number of projects under development that are based on Docker's 232 core technology. These projects expand the tooling built around the 233 Docker platform to broaden its application and utility. 234 235 If you know of another project underway that should be listed here, please help 236 us keep this list up-to-date by submitting a PR. 237 238 * [Docker Registry](https://github.com/docker/distribution): Registry 239 server for Docker (hosting/delivery of repositories and images) 240 * [Docker Machine](https://github.com/docker/machine): Machine management 241 for a container-centric world 242 * [Docker Swarm](https://github.com/docker/swarm): A Docker-native clustering 243 system 244 * [Docker Compose](https://github.com/docker/compose) (formerly Fig): 245 Define and run multi-container apps 246