|
1 | | -Docker: the container engine [](https://github.com/docker/docker/releases/latest) |
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 | | -cloud 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 | | -powered [dotCloud](http://web.archive.org/web/20130530031104/https://www.dotcloud.com/), |
17 | | -a popular Platform-as-a-Service. It benefits directly from the experience |
18 | | -accumulated over several years of large-scale operation and support of hundreds |
19 | | -of thousands of applications and databases. |
20 | | - |
21 | | - |
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 | | -[email protected] 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](https://openvz.org), |
60 | | -[vserver](http://linux-vserver.org) and more recently |
61 | | -[lxc](https://linuxcontainers.org/), Solaris with |
62 | | -[zones](https://docs.oracle.com/cd/E26502_01/html/E29024/preface-1.html#scrolltoc), |
63 | | -and FreeBSD with |
64 | | -[Jails](https://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](https://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 either on your computer for building applications or |
147 | | -on servers for running them. To get started, [check out the installation |
148 | | -instructions in the |
149 | | -documentation](https://docs.docker.com/engine/installation/). |
150 | | - |
151 | | -Usage examples |
152 | | -============== |
153 | | - |
154 | | -Docker can be used to run short-lived commands, long-running daemons |
155 | | -(app servers, databases, etc.), interactive shell sessions, etc. |
156 | | - |
157 | | -You can find a [list of real-world |
158 | | -examples](https://docs.docker.com/engine/examples/) in the |
159 | | -documentation. |
160 | | - |
161 | | -Under the hood |
162 | | --------------- |
163 | | - |
164 | | -Under the hood, Docker is built on the following components: |
165 | | - |
166 | | -* The |
167 | | - [cgroups](https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt) |
168 | | - and |
169 | | - [namespaces](http://man7.org/linux/man-pages/man7/namespaces.7.html) |
170 | | - capabilities of the Linux kernel |
171 | | -* The [Go](https://golang.org) programming language |
172 | | -* The [Docker Image Specification](https://github.com/docker/docker/blob/master/image/spec/v1.md) |
173 | | -* The [Libcontainer Specification](https://github.com/opencontainers/runc/blob/master/libcontainer/SPEC.md) |
174 | | - |
175 | | -Contributing to Docker [](https://godoc.org/github.com/docker/docker) |
176 | | -====================== |
177 | | - |
178 | | -| **Master** (Linux) | **Experimental** (Linux) | **Windows** | **FreeBSD** | |
179 | | -|------------------|----------------------|---------|---------| |
180 | | -| [](https://jenkins.dockerproject.org/view/Docker/job/Docker%20Master/) | [](https://jenkins.dockerproject.org/view/Docker/job/Docker%20Master%20%28experimental%29/) | [/badge/icon)](http://jenkins.dockerproject.org/job/Docker%20Master%20(windows)/) | [/badge/icon)](http://jenkins.dockerproject.org/job/Docker%20Master%20(freebsd)/) | |
181 | | - |
182 | | -Want to hack on Docker? Awesome! We have [instructions to help you get |
183 | | -started contributing code or documentation](https://docs.docker.com/opensource/project/who-written-for/). |
184 | | - |
185 | | -These instructions are probably not perfect, please let us know if anything |
186 | | -feels wrong or incomplete. Better yet, submit a PR and improve them yourself. |
187 | | - |
188 | | -Getting the development builds |
189 | | -============================== |
190 | | - |
191 | | -Want to run Docker from a master build? You can download |
192 | | -master builds at [master.dockerproject.org](https://master.dockerproject.org). |
193 | | -They are updated with each commit merged into the master branch. |
194 | | - |
195 | | -Don't know how to use that super cool new feature in the master build? Check |
196 | | -out the master docs at |
197 | | -[docs.master.dockerproject.org](http://docs.master.dockerproject.org). |
198 | | - |
199 | | -How the project is run |
200 | | -====================== |
201 | | - |
202 | | -Docker is a very, very active project. If you want to learn more about how it is run, |
203 | | -or want to get more involved, the best place to start is [the project directory](https://github.com/docker/docker/tree/master/project). |
204 | | - |
205 | | -We are always open to suggestions on process improvements, and are always looking for more maintainers. |
206 | | - |
207 | | -### Talking to other Docker users and contributors |
208 | | - |
209 | | -<table class="tg"> |
210 | | - <col width="45%"> |
211 | | - <col width="65%"> |
212 | | - <tr> |
213 | | - <td>Internet Relay Chat (IRC)</td> |
214 | | - <td> |
215 | | - <p> |
216 | | - IRC is a direct line to our most knowledgeable Docker users; we have |
217 | | - both the <code>#docker</code> and <code>#docker-dev</code> group on |
218 | | - <strong>irc.freenode.net</strong>. |
219 | | - IRC is a rich chat protocol but it can overwhelm new users. You can search |
220 | | - <a href="https://botbot.me/freenode/docker/#" target="_blank">our chat archives</a>. |
221 | | - </p> |
222 | | - Read our <a href="https://docs.docker.com/project/get-help/#irc-quickstart" target="_blank">IRC quickstart guide</a> for an easy way to get started. |
223 | | - </td> |
224 | | - </tr> |
225 | | - <tr> |
226 | | - <td>Docker Community Forums</td> |
227 | | - <td> |
228 | | - The <a href="https://forums.docker.com/c/open-source-projects/de" target="_blank">Docker Engine</a> |
229 | | - group is for users of the Docker Engine project. |
230 | | - </td> |
231 | | - </tr> |
232 | | - <tr> |
233 | | - <td>Google Groups</td> |
234 | | - <td> |
235 | | - The <a href="https://groups.google.com/forum/#!forum/docker-dev" |
236 | | - target="_blank">docker-dev</a> group is for contributors and other people |
237 | | - contributing to the Docker project. You can join this group without a |
238 | | - Google account by sending an email to <a |
239 | | - |
240 | | - You'll receive a join-request message; simply reply to the message to |
241 | | - confirm your subscription. |
242 | | - </td> |
243 | | - </tr> |
244 | | - <tr> |
245 | | - <td>Twitter</td> |
246 | | - <td> |
247 | | - You can follow <a href="https://twitter.com/docker/" target="_blank">Docker's Twitter feed</a> |
248 | | - to get updates on our products. You can also tweet us questions or just |
249 | | - share blogs or stories. |
250 | | - </td> |
251 | | - </tr> |
252 | | - <tr> |
253 | | - <td>Stack Overflow</td> |
254 | | - <td> |
255 | | - Stack Overflow has over 7000 Docker questions listed. We regularly |
256 | | - monitor <a href="https://stackoverflow.com/search?tab=newest&q=docker" target="_blank">Docker questions</a> |
257 | | - and so do many other knowledgeable Docker users. |
258 | | - </td> |
259 | | - </tr> |
260 | | -</table> |
261 | | - |
262 | | -### Legal |
263 | | - |
264 | | -*Brought to you courtesy of our legal counsel. For more context, |
265 | | -please see the [NOTICE](https://github.com/docker/docker/blob/master/NOTICE) document in this repo.* |
266 | | - |
267 | | -Use and transfer of Docker may be subject to certain restrictions by the |
268 | | -United States and other governments. |
269 | | - |
270 | | -It is your responsibility to ensure that your use and/or transfer does not |
271 | | -violate applicable laws. |
272 | | - |
273 | | -For more information, please see https://www.bis.doc.gov |
274 | | - |
275 | | - |
276 | | -Licensing |
277 | | -========= |
278 | | -Docker is licensed under the Apache License, Version 2.0. See |
279 | | -[LICENSE](https://github.com/docker/docker/blob/master/LICENSE) for the full |
280 | | -license text. |
281 | | - |
282 | | -Other Docker Related Projects |
283 | | -============================= |
284 | | -There are a number of projects under development that are based on Docker's |
285 | | -core technology. These projects expand the tooling built around the |
286 | | -Docker platform to broaden its application and utility. |
287 | | - |
288 | | -* [Docker Registry](https://github.com/docker/distribution): Registry |
289 | | -server for Docker (hosting/delivery of repositories and images) |
290 | | -* [Docker Machine](https://github.com/docker/machine): Machine management |
291 | | -for a container-centric world |
292 | | -* [Docker Swarm](https://github.com/docker/swarm): A Docker-native clustering |
293 | | -system |
294 | | -* [Docker Compose](https://github.com/docker/compose) (formerly Fig): |
295 | | -Define and run multi-container apps |
296 | | -* [Kitematic](https://github.com/docker/kitematic): The easiest way to use |
297 | | -Docker on Mac and Windows |
298 | | - |
299 | | -If you know of another project underway that should be listed here, please help |
300 | | -us keep this list up-to-date by submitting a PR. |
301 | | - |
302 | | -Awesome-Docker |
303 | | -============== |
304 | | -You can find more projects, tools and articles related to Docker on the [awesome-docker list](https://github.com/veggiemonk/awesome-docker). Add your project there. |
| 1 | +This repository contains code originally under the Docker repository (now [moby](https://github.com/moby/moby)) + patches. |
0 commit comments