2013-05-05 06:47:57 +04:00
|
|
|
Docker: the Linux container engine
|
|
|
|
==================================
|
2013-02-02 00:57:02 +04:00
|
|
|
|
2013-09-07 02:08:01 +04:00
|
|
|
Docker is an open source project to pack, ship and run any application
|
2015-04-08 01:22:52 +03:00
|
|
|
as a lightweight container.
|
2013-02-02 01:00:41 +04:00
|
|
|
|
2014-03-04 16:53:22 +04:00
|
|
|
Docker containers are both *hardware-agnostic* and *platform-agnostic*.
|
2014-12-29 23:42:20 +03:00
|
|
|
This means they can run anywhere, from your laptop to the largest
|
2014-03-04 16:53:22 +04:00
|
|
|
EC2 compute instance and everything in between - and they don't require
|
2014-12-29 23:42:20 +03:00
|
|
|
you to use a particular language, framework or packaging system. That
|
2014-03-04 16:53:22 +04:00
|
|
|
makes them great building blocks for deploying and scaling web apps,
|
2014-12-29 23:42:20 +03:00
|
|
|
databases, and backend services without depending on a particular stack
|
2014-03-04 16:53:22 +04:00
|
|
|
or provider.
|
2013-02-02 00:57:02 +04:00
|
|
|
|
2014-12-29 23:42:20 +03:00
|
|
|
Docker began as an open-source implementation of the deployment engine which
|
2015-04-11 20:18:57 +03:00
|
|
|
powers [dotCloud](https://dotcloud.com), a popular Platform-as-a-Service.
|
2014-03-04 16:53:22 +04:00
|
|
|
It benefits directly from the experience accumulated over several years
|
|
|
|
of large-scale operation and support of hundreds of thousands of
|
|
|
|
applications and databases.
|
2013-02-02 00:57:02 +04:00
|
|
|
|
2015-06-16 13:14:37 +03:00
|
|
|
![Docker L](docs/static_files/docker-logo-compressed.png "Docker")
|
2013-05-06 23:24:44 +04:00
|
|
|
|
2014-06-18 00:26:26 +04:00
|
|
|
## Security Disclosure
|
|
|
|
|
2014-12-29 23:42:20 +03:00
|
|
|
Security is very important to us. If you have any issue regarding security,
|
2014-06-18 21:15:51 +04:00
|
|
|
please disclose the information responsibly by sending an email to
|
|
|
|
security@docker.com and not by creating a github issue.
|
2014-06-18 00:26:26 +04:00
|
|
|
|
2013-05-05 06:47:57 +04:00
|
|
|
## Better than VMs
|
2013-02-02 00:57:02 +04:00
|
|
|
|
2014-01-26 10:30:27 +04:00
|
|
|
A common method for distributing applications and sandboxing their
|
2013-07-24 05:13:53 +04:00
|
|
|
execution is to use virtual machines, or VMs. Typical VM formats are
|
2015-06-27 05:14:07 +03:00
|
|
|
VMware's vmdk, Oracle VirtualBox's vdi, and Amazon EC2's ami. In theory
|
2014-03-04 16:53:22 +04:00
|
|
|
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:
|
2013-07-24 05:13:53 +04:00
|
|
|
|
|
|
|
* *Size*: VMs are very large which makes them impractical to store
|
|
|
|
and transfer.
|
|
|
|
* *Performance*: running VMs consumes significant CPU and memory,
|
|
|
|
which makes them impractical in many scenarios, for example local
|
|
|
|
development of multi-tier applications, and large-scale deployment
|
|
|
|
of cpu and memory-intensive applications on large numbers of
|
|
|
|
machines.
|
|
|
|
* *Portability*: competing VM environments don't play well with each
|
|
|
|
other. Although conversion tools do exist, they are limited and
|
|
|
|
add even more overhead.
|
|
|
|
* *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: building, testing
|
|
|
|
and running their software. For example, VMs offer no facilities
|
|
|
|
for application versioning, monitoring, configuration, logging or
|
|
|
|
service discovery.
|
|
|
|
|
|
|
|
By contrast, Docker relies on a different sandboxing method known as
|
2014-03-04 16:53:22 +04:00
|
|
|
*containerization*. Unlike traditional virtualization, containerization
|
|
|
|
takes place at the kernel level. Most modern operating system kernels
|
|
|
|
now support the primitives necessary for containerization, including
|
2015-04-11 20:18:57 +03:00
|
|
|
Linux with [openvz](https://openvz.org),
|
2013-07-24 05:13:53 +04:00
|
|
|
[vserver](http://linux-vserver.org) and more recently
|
2015-05-29 11:10:57 +03:00
|
|
|
[lxc](https://linuxcontainers.org/), Solaris with
|
2015-04-11 20:18:57 +03:00
|
|
|
[zones](https://docs.oracle.com/cd/E26502_01/html/E29024/preface-1.html#scrolltoc),
|
2013-07-24 05:13:53 +04:00
|
|
|
and FreeBSD with
|
2015-04-11 20:18:57 +03:00
|
|
|
[Jails](https://www.freebsd.org/doc/handbook/jails.html).
|
2013-07-24 05:13:53 +04:00
|
|
|
|
2014-03-04 16:53:22 +04:00
|
|
|
Docker builds on top of these low-level primitives to offer developers a
|
2014-12-29 23:42:20 +03:00
|
|
|
portable format and runtime environment that solves all four problems.
|
2014-03-04 16:53:22 +04:00
|
|
|
Docker containers are small (and their transfer can be optimized with
|
|
|
|
layers), they have basically zero memory and cpu overhead, they are
|
2014-12-29 23:42:20 +03:00
|
|
|
completely portable, and are designed from the ground up with an
|
2014-03-04 16:53:22 +04:00
|
|
|
application-centric design.
|
2013-07-24 05:13:53 +04:00
|
|
|
|
2014-12-29 23:42:20 +03:00
|
|
|
Perhaps best of all, because Docker operates at the OS level, it can still be
|
2014-03-04 16:53:22 +04:00
|
|
|
run inside a VM!
|
2013-02-14 02:58:32 +04:00
|
|
|
|
2013-05-05 06:47:57 +04:00
|
|
|
## Plays well with others
|
2013-02-14 02:58:32 +04:00
|
|
|
|
2014-12-29 23:42:20 +03:00
|
|
|
Docker does not require you to buy into a particular programming
|
|
|
|
language, framework, packaging system, or configuration language.
|
2013-02-14 02:58:32 +04:00
|
|
|
|
2014-03-04 16:53:22 +04:00
|
|
|
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.
|
2013-02-14 02:58:32 +04:00
|
|
|
|
2013-07-24 05:13:53 +04:00
|
|
|
Can your application's build be expressed as a sequence of such
|
2014-03-04 16:53:22 +04:00
|
|
|
commands? Then Docker can build it.
|
2013-02-14 02:58:32 +04:00
|
|
|
|
2013-05-05 06:47:57 +04:00
|
|
|
## Escape dependency hell
|
|
|
|
|
2013-07-24 05:13:53 +04:00
|
|
|
A common problem for developers is the difficulty of managing all
|
|
|
|
their application's dependencies in a simple and automated way.
|
2013-05-05 06:47:57 +04:00
|
|
|
|
|
|
|
This is usually difficult for several reasons:
|
|
|
|
|
2013-07-24 05:13:53 +04:00
|
|
|
* *Cross-platform dependencies*. Modern applications often depend on
|
|
|
|
a combination of system libraries and binaries, language-specific
|
|
|
|
packages, framework-specific modules, internal components
|
|
|
|
developed for another project, etc. These dependencies live in
|
|
|
|
different "worlds" and require different tools - these tools
|
|
|
|
typically don't work well with each other, requiring awkward
|
|
|
|
custom integrations.
|
|
|
|
|
2015-01-09 05:10:59 +03:00
|
|
|
* *Conflicting dependencies*. Different applications may depend on
|
2013-07-24 05:13:53 +04:00
|
|
|
different versions of the same dependency. Packaging tools handle
|
|
|
|
these situations with various degrees of ease - but they all
|
|
|
|
handle them in different and incompatible ways, which again forces
|
|
|
|
the developer to do extra work.
|
2015-04-08 01:22:52 +03:00
|
|
|
|
2015-01-09 05:10:59 +03:00
|
|
|
* *Custom dependencies*. A developer may need to prepare a custom
|
2013-07-24 05:13:53 +04:00
|
|
|
version of their application's dependency. Some packaging systems
|
|
|
|
can handle custom versions of a dependency, others can't - and all
|
|
|
|
of them handle it differently.
|
2013-05-05 06:47:57 +04:00
|
|
|
|
|
|
|
|
2014-12-29 23:42:20 +03:00
|
|
|
Docker solves the problem of dependency hell by giving the developer a simple
|
|
|
|
way to express *all* their application's dependencies in one place, while
|
|
|
|
streamlining the process of assembling them. If this makes you think of
|
2015-04-11 20:18:57 +03:00
|
|
|
[XKCD 927](https://xkcd.com/927/), don't worry. Docker doesn't
|
2013-07-24 05:13:53 +04:00
|
|
|
*replace* your favorite packaging systems. It simply orchestrates
|
|
|
|
their use in a simple and repeatable way. How does it do that? With
|
|
|
|
layers.
|
2013-05-05 06:47:57 +04:00
|
|
|
|
2013-07-24 05:13:53 +04:00
|
|
|
Docker defines a build as running a sequence of Unix commands, one
|
|
|
|
after the other, in the same container. Build commands modify the
|
|
|
|
contents of the container (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 commands, the
|
|
|
|
*order* in which the commands are executed expresses *dependencies*.
|
2013-05-05 06:47:57 +04:00
|
|
|
|
2013-07-24 05:13:53 +04:00
|
|
|
Here's a typical Docker build process:
|
2013-05-05 06:47:57 +04:00
|
|
|
|
|
|
|
```bash
|
2014-03-04 16:53:22 +04:00
|
|
|
FROM ubuntu:12.04
|
2014-07-07 22:06:34 +04:00
|
|
|
RUN apt-get update && apt-get install -y python python-pip curl
|
2014-07-07 20:35:38 +04:00
|
|
|
RUN curl -sSL https://github.com/shykes/helloflask/archive/master.tar.gz | tar -xzv
|
2014-03-04 16:53:22 +04:00
|
|
|
RUN cd helloflask-master && pip install -r requirements.txt
|
2013-05-05 06:47:57 +04:00
|
|
|
```
|
|
|
|
|
2013-07-24 05:13:53 +04:00
|
|
|
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.
|
2013-02-14 02:58:32 +04:00
|
|
|
|
|
|
|
|
2013-09-07 02:09:04 +04:00
|
|
|
Getting started
|
|
|
|
===============
|
2013-02-01 06:58:05 +04:00
|
|
|
|
2014-03-04 16:53:22 +04:00
|
|
|
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.
|
2013-03-26 01:48:46 +04:00
|
|
|
|
2015-04-11 20:18:57 +03:00
|
|
|
We also offer an [interactive tutorial](https://www.docker.com/tryit/)
|
2014-06-11 19:57:12 +04:00
|
|
|
for quickly learning the basics of using Docker.
|
2013-04-19 09:22:00 +04:00
|
|
|
|
2015-04-11 20:18:57 +03:00
|
|
|
For up-to-date install instructions, see the [Docs](https://docs.docker.com).
|
2013-04-19 09:22:00 +04:00
|
|
|
|
2013-09-07 02:09:04 +04:00
|
|
|
Usage examples
|
|
|
|
==============
|
2013-03-13 22:58:15 +04:00
|
|
|
|
2014-03-04 16:53:22 +04:00
|
|
|
Docker can be used to run short-lived commands, long-running daemons
|
2015-04-08 01:22:52 +03:00
|
|
|
(app servers, databases, etc.), interactive shell sessions, etc.
|
2013-03-13 22:58:15 +04:00
|
|
|
|
2014-03-04 16:53:22 +04:00
|
|
|
You can find a [list of real-world
|
2015-04-11 20:18:57 +03:00
|
|
|
examples](https://docs.docker.com/examples/) in the
|
2014-03-04 16:53:22 +04:00
|
|
|
documentation.
|
2013-03-13 22:58:15 +04:00
|
|
|
|
2013-04-21 04:33:02 +04:00
|
|
|
Under the hood
|
|
|
|
--------------
|
|
|
|
|
|
|
|
Under the hood, Docker is built on the following components:
|
|
|
|
|
2013-07-24 05:13:53 +04:00
|
|
|
* The
|
2015-07-01 02:48:07 +03:00
|
|
|
[cgroups](https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt)
|
2013-07-24 05:13:53 +04:00
|
|
|
and
|
2015-07-01 02:48:07 +03:00
|
|
|
[namespaces](http://man7.org/linux/man-pages/man7/namespaces.7.html)
|
2015-04-03 19:50:30 +03:00
|
|
|
capabilities of the Linux kernel
|
2015-04-11 20:18:57 +03:00
|
|
|
* The [Go](https://golang.org) programming language
|
2015-04-03 19:50:30 +03:00
|
|
|
* The [Docker Image Specification](https://github.com/docker/docker/blob/master/image/spec/v1.md)
|
|
|
|
* The [Libcontainer Specification](https://github.com/docker/libcontainer/blob/master/SPEC.md)
|
2013-04-21 04:33:02 +04:00
|
|
|
|
2013-03-18 06:32:06 +04:00
|
|
|
Contributing to Docker
|
|
|
|
======================
|
|
|
|
|
2015-04-22 13:45:29 +03:00
|
|
|
[![GoDoc](https://godoc.org/github.com/docker/docker?status.svg)](https://godoc.org/github.com/docker/docker)
|
2015-06-03 22:08:40 +03:00
|
|
|
[![Jenkins Build Status](https://jenkins.dockerproject.org/job/Docker%20Master/badge/icon)](https://jenkins.dockerproject.org/job/Docker%20Master/)
|
2014-08-19 03:08:47 +04:00
|
|
|
|
2014-12-29 23:42:20 +03:00
|
|
|
Want to hack on Docker? Awesome! We have [instructions to help you get
|
2015-07-15 03:50:19 +03:00
|
|
|
started contributing code or documentation](https://docs.docker.com/project/who-written-for/).
|
2013-03-18 06:32:06 +04:00
|
|
|
|
2014-11-11 04:50:12 +03:00
|
|
|
These instructions are probably not perfect, please let us know if anything
|
2014-12-29 23:42:20 +03:00
|
|
|
feels wrong or incomplete. Better yet, submit a PR and improve them yourself.
|
2013-03-18 06:32:06 +04:00
|
|
|
|
2015-03-09 21:31:32 +03:00
|
|
|
Getting the development builds
|
|
|
|
==============================
|
|
|
|
|
2014-12-19 05:09:41 +03:00
|
|
|
Want to run Docker from a master build? You can download
|
2015-06-03 22:08:40 +03:00
|
|
|
master builds at [master.dockerproject.org](https://master.dockerproject.org).
|
2014-12-12 23:14:26 +03:00
|
|
|
They are updated with each commit merged into the master branch.
|
|
|
|
|
2015-01-10 00:53:03 +03:00
|
|
|
Don't know how to use that super cool new feature in the master build? Check
|
|
|
|
out the master docs at
|
2015-06-03 22:08:40 +03:00
|
|
|
[docs.master.dockerproject.org](http://docs.master.dockerproject.org).
|
2015-01-10 00:53:03 +03:00
|
|
|
|
2014-11-09 22:59:57 +03:00
|
|
|
How the project is run
|
|
|
|
======================
|
|
|
|
|
|
|
|
Docker is a very, very active project. If you want to learn more about how it is run,
|
2015-01-31 18:09:45 +03:00
|
|
|
or want to get more involved, the best place to start is [the project directory](https://github.com/docker/docker/tree/master/project).
|
2014-11-09 22:59:57 +03:00
|
|
|
|
|
|
|
We are always open to suggestions on process improvements, and are always looking for more maintainers.
|
|
|
|
|
2015-05-14 06:45:33 +03:00
|
|
|
### Talking to other Docker users and contributors
|
|
|
|
|
|
|
|
<table class="tg">
|
|
|
|
<col width="45%">
|
|
|
|
<col width="65%">
|
|
|
|
<tr>
|
|
|
|
<td>Internet Relay Chat (IRC)</td>
|
|
|
|
<td>
|
|
|
|
<p>
|
|
|
|
IRC a direct line to our most knowledgeable Docker users; we have
|
|
|
|
both the <code>#docker</code> and <code>#docker-dev</code> group on
|
|
|
|
<strong>irc.freenode.net</strong>.
|
|
|
|
IRC is a rich chat protocol but it can overwhelm new users. You can search
|
|
|
|
<a href="https://botbot.me/freenode/docker/#" target="_blank">our chat archives</a>.
|
|
|
|
</p>
|
|
|
|
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.
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>Google Groups</td>
|
|
|
|
<td>
|
|
|
|
There are two groups.
|
|
|
|
<a href="https://groups.google.com/forum/#!forum/docker-user" target="_blank">Docker-user</a>
|
|
|
|
is for people using Docker containers.
|
|
|
|
The <a href="https://groups.google.com/forum/#!forum/docker-dev" target="_blank">docker-dev</a>
|
|
|
|
group is for contributors and other people contributing to the Docker
|
|
|
|
project.
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>Twitter</td>
|
|
|
|
<td>
|
|
|
|
You can follow <a href="https://twitter.com/docker/" target="_blank">Docker's Twitter feed</a>
|
|
|
|
to get updates on our products. You can also tweet us questions or just
|
|
|
|
share blogs or stories.
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>Stack Overflow</td>
|
|
|
|
<td>
|
|
|
|
Stack Overflow has over 7000K Docker questions listed. We regularly
|
|
|
|
monitor <a href="https://stackoverflow.com/search?tab=newest&q=docker" target="_blank">Docker questions</a>
|
|
|
|
and so do many other knowledgeable Docker users.
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
2013-06-06 21:09:11 +04:00
|
|
|
### Legal
|
|
|
|
|
2013-09-28 06:07:12 +04:00
|
|
|
*Brought to you courtesy of our legal counsel. For more context,
|
2015-04-04 02:36:49 +03:00
|
|
|
please see the [NOTICE](https://github.com/docker/docker/blob/master/NOTICE) document in this repo.*
|
2013-09-28 06:07:12 +04:00
|
|
|
|
2013-11-12 02:08:37 +04:00
|
|
|
Use and transfer of Docker may be subject to certain restrictions by the
|
2015-04-08 01:22:52 +03:00
|
|
|
United States and other governments.
|
|
|
|
|
2013-11-12 02:08:37 +04:00
|
|
|
It is your responsibility to ensure that your use and/or transfer does not
|
2015-04-08 01:22:52 +03:00
|
|
|
violate applicable laws.
|
2013-03-06 04:00:17 +04:00
|
|
|
|
2015-04-11 20:18:57 +03:00
|
|
|
For more information, please see https://www.bis.doc.gov
|
2014-05-02 22:13:50 +04:00
|
|
|
|
|
|
|
|
|
|
|
Licensing
|
|
|
|
=========
|
2014-12-05 14:04:46 +03:00
|
|
|
Docker is licensed under the Apache License, Version 2.0. See
|
|
|
|
[LICENSE](https://github.com/docker/docker/blob/master/LICENSE) for the full
|
|
|
|
license text.
|
2014-05-02 22:13:50 +04:00
|
|
|
|
2014-12-08 19:01:42 +03:00
|
|
|
Other Docker Related Projects
|
|
|
|
=============================
|
2015-01-02 22:18:26 +03:00
|
|
|
There are a number of projects under development that are based on Docker's
|
2015-01-02 22:00:27 +03:00
|
|
|
core technology. These projects expand the tooling built around the
|
2015-04-08 01:22:52 +03:00
|
|
|
Docker platform to broaden its application and utility.
|
2014-12-29 23:42:20 +03:00
|
|
|
|
2015-03-19 00:30:11 +03:00
|
|
|
* [Docker Registry](https://github.com/docker/distribution): Registry
|
|
|
|
server for Docker (hosting/delivery of repositories and images)
|
2014-12-08 19:01:42 +03:00
|
|
|
* [Docker Machine](https://github.com/docker/machine): Machine management
|
2015-04-08 01:22:52 +03:00
|
|
|
for a container-centric world
|
2014-12-08 19:01:42 +03:00
|
|
|
* [Docker Swarm](https://github.com/docker/swarm): A Docker-native clustering
|
2015-04-08 01:22:52 +03:00
|
|
|
system
|
2015-02-26 20:25:57 +03:00
|
|
|
* [Docker Compose](https://github.com/docker/compose) (formerly Fig):
|
|
|
|
Define and run multi-container apps
|
2015-04-02 00:38:49 +03:00
|
|
|
* [Kitematic](https://github.com/kitematic/kitematic): The easiest way to use
|
2015-06-26 07:24:15 +03:00
|
|
|
Docker on Mac and Windows
|
2014-12-08 19:01:42 +03:00
|
|
|
|
2015-04-02 00:38:49 +03:00
|
|
|
If you know of another project underway that should be listed here, please help
|
|
|
|
us keep this list up-to-date by submitting a PR.
|