mirror of
https://github.com/docker/docs.git
synced 2026-04-03 01:38:58 +07:00
2534 lines
126 KiB
XML
2534 lines
126 KiB
XML
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
|
||
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
|
||
<channel>
|
||
<title>Dockers on Docker Docs</title>
|
||
<link>http://localhost/docker/</link>
|
||
<description>Recent content in Dockers on Docker Docs</description>
|
||
<generator>Hugo -- gohugo.io</generator>
|
||
<language>en-us</language>
|
||
<atom:link href="http://localhost/docker/index.xml" rel="self" type="application/rss+xml" />
|
||
|
||
<item>
|
||
<title></title>
|
||
<link>http://localhost/docker/articles/https/README/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/articles/https/README/</guid>
|
||
<description><p>This is an initial attempt to make it easier to test the examples in the https.md
|
||
doc</p>
|
||
|
||
<p>at this point, it has to be a manual thing, and I&rsquo;ve been running it in boot2docker</p>
|
||
|
||
<p>so my process is</p>
|
||
|
||
<p>$ boot2docker ssh
|
||
$$ git clone <a href="https://github.com/docker/docker">https://github.com/docker/docker</a>
|
||
$$ cd docker/docs/articles/https
|
||
$$ make cert
|
||
lots of things to see and manually answer, as openssl wants to be interactive
|
||
<strong>NOTE:</strong> make sure you enter the hostname (<code>boot2docker</code> in my case) when prompted for <code>Computer Name</code>)
|
||
$$ sudo make run</p>
|
||
|
||
<p>start another terminal</p>
|
||
|
||
<p>$ boot2docker ssh
|
||
$$ cd docker/docs/articles/https
|
||
$$ make client</p>
|
||
|
||
<p>the last will connect first with <code>--tls</code> and then with <code>--tlsverify</code></p>
|
||
|
||
<p>both should succeed</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title></title>
|
||
<link>http://localhost/docker/reference/api/README/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/reference/api/README/</guid>
|
||
<description><p>This directory holds the authoritative specifications of APIs defined and implemented by Docker. Currently this includes:</p>
|
||
|
||
<ul>
|
||
<li>The remote API by which a docker node can be queried over HTTP</li>
|
||
<li>The registry API by which a docker node can download and upload
|
||
images for storage and sharing</li>
|
||
<li>The index search API by which a docker node can search the public
|
||
index for images to download</li>
|
||
<li>The docker.io OAuth and accounts API which 3rd party services can
|
||
use to access account information</li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title></title>
|
||
<link>http://localhost/docker/reference/logging/journald/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/reference/logging/journald/</guid>
|
||
<description>
|
||
|
||
<h1 id="journald-logging-driver">Journald logging driver</h1>
|
||
|
||
<p>The <code>journald</code> logging driver sends container logs to the <a href="http://www.freedesktop.org/software/systemd/man/systemd-journald.service.html">systemd
|
||
journal</a>. Log entries can be retrieved using the <code>journalctl</code>
|
||
command or through use of the journal API.</p>
|
||
|
||
<p>In addition to the text of the log message itself, the <code>journald</code> log
|
||
driver stores the following metadata in the journal with each message:</p>
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<tr>
|
||
<td><code>CONTAINER_ID</code></td>
|
||
<td>The container ID truncated to 12 characters.</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td><code>CONTAINER_ID_FULL</code></td>
|
||
<td>The full 64-character container ID.</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td><code>CONTAINER_NAME</code></td>
|
||
<td>The container name at the time it was started. If you use <code>docker rename</code> to rename a container, the new name is not reflected in the journal entries.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h2 id="usage">Usage</h2>
|
||
|
||
<p>You can configure the default logging driver by passing the
|
||
<code>--log-driver</code> option to the Docker daemon:</p>
|
||
|
||
<pre><code>docker --log-driver=journald
|
||
</code></pre>
|
||
|
||
<p>You can set the logging driver for a specific container by using the
|
||
<code>--log-driver</code> option to <code>docker run</code>:</p>
|
||
|
||
<pre><code>docker run --log-driver=journald ...
|
||
</code></pre>
|
||
|
||
<h2 id="note-regarding-container-names">Note regarding container names</h2>
|
||
|
||
<p>The value logged in the <code>CONTAINER_NAME</code> field is the container name
|
||
that was set at startup. If you use <code>docker rename</code> to rename a
|
||
container, the new name will not be reflected in the journal entries.
|
||
Journal entries will continue to use the original name.</p>
|
||
|
||
<h2 id="retrieving-log-messages-with-journalctl">Retrieving log messages with journalctl</h2>
|
||
|
||
<p>You can use the <code>journalctl</code> command to retrieve log messages. You
|
||
can apply filter expressions to limit the retrieved messages to a
|
||
specific container. For example, to retrieve all log messages from a
|
||
container referenced by name:</p>
|
||
|
||
<pre><code># journalctl CONTAINER_NAME=webserver
|
||
</code></pre>
|
||
|
||
<p>You can make use of additional filters to further limit the messages
|
||
retrieved. For example, to see just those messages generated since
|
||
the system last booted:</p>
|
||
|
||
<pre><code># journalctl -b CONTAINER_NAME=webserver
|
||
</code></pre>
|
||
|
||
<p>Or to retrieve log messages in JSON format with complete metadata:</p>
|
||
|
||
<pre><code># journalctl -o json CONTAINER_NAME=webserver
|
||
</code></pre>
|
||
|
||
<h2 id="retrieving-log-messages-with-the-journal-api">Retrieving log messages with the journal API</h2>
|
||
|
||
<p>This example uses the <code>systemd</code> Python module to retrieve container
|
||
logs:</p>
|
||
|
||
<pre><code>import systemd.journal
|
||
|
||
reader = systemd.journal.Reader()
|
||
reader.add_match('CONTAINER_NAME=web')
|
||
|
||
for msg in reader:
|
||
print '{CONTAINER_ID_FULL}: {MESSAGE}'.format(**msg)
|
||
</code></pre>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title></title>
|
||
<link>http://localhost/docker/static_files/README/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/static_files/README/</guid>
|
||
<description>
|
||
|
||
<h1 id="static-files-dir">Static files dir</h1>
|
||
|
||
<p>Files you put in /static_files/ will be copied to the web visible /_static/</p>
|
||
|
||
<p>Be careful not to override pre-existing static files from the template.</p>
|
||
|
||
<p>Generally, layout related files should go in the /theme directory.</p>
|
||
|
||
<p>If you want to add images to your particular documentation page. Just put them next to
|
||
your .rst source file and reference them relatively.</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>About Docker</title>
|
||
<link>http://localhost/docker/misc/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/misc/</guid>
|
||
<description>
|
||
|
||
<h1 id="about-docker">About Docker</h1>
|
||
|
||
<p><strong>Develop, Ship and Run Any Application, Anywhere</strong></p>
|
||
|
||
<p><a href="https://www.docker.com"><strong>Docker</strong></a> is a platform for developers and sysadmins
|
||
to develop, ship, and run applications. Docker lets you quickly assemble
|
||
applications from components and eliminates the friction that can come when
|
||
shipping code. Docker lets you get your code tested and deployed into production
|
||
as fast as possible.</p>
|
||
|
||
<p>Docker consists of:</p>
|
||
|
||
<ul>
|
||
<li>The Docker Engine - our lightweight and powerful open source container
|
||
virtualization technology combined with a work flow for building
|
||
and containerizing your applications.</li>
|
||
<li><a href="https://hub.docker.com">Docker Hub</a> - our SaaS service for
|
||
sharing and managing your application stacks.</li>
|
||
</ul>
|
||
|
||
<h2 id="why-docker">Why Docker?</h2>
|
||
|
||
<p><em>Faster delivery of your applications</em></p>
|
||
|
||
<ul>
|
||
<li>We want your environment to work better. Docker containers,
|
||
and the work flow that comes with them, help your developers,
|
||
sysadmins, QA folks, and release engineers work together to get your code
|
||
into production and make it useful. We&rsquo;ve created a standard
|
||
container format that lets developers care about their applications
|
||
inside containers while sysadmins and operators can work on running the
|
||
container in your deployment. This separation of duties streamlines and
|
||
simplifies the management and deployment of code.</li>
|
||
<li>We make it easy to build new containers, enable rapid iteration of
|
||
your applications, and increase the visibility of changes. This
|
||
helps everyone in your organization understand how an application works
|
||
and how it is built.</li>
|
||
<li>Docker containers are lightweight and fast! Containers have
|
||
sub-second launch times, reducing the cycle
|
||
time of development, testing, and deployment.</li>
|
||
</ul>
|
||
|
||
<p><em>Deploy and scale more easily</em></p>
|
||
|
||
<ul>
|
||
<li>Docker containers run (almost) everywhere. You can deploy
|
||
containers on desktops, physical servers, virtual machines, into
|
||
data centers, and up to public and private clouds.</li>
|
||
<li>Since Docker runs on so many platforms, it&rsquo;s easy to move your
|
||
applications around. You can easily move an application from a
|
||
testing environment into the cloud and back whenever you need.</li>
|
||
<li>Docker&rsquo;s lightweight containers also make scaling up and
|
||
down fast and easy. You can quickly launch more containers when
|
||
needed and then shut them down easily when they&rsquo;re no longer needed.</li>
|
||
</ul>
|
||
|
||
<p><em>Get higher density and run more workloads</em></p>
|
||
|
||
<ul>
|
||
<li>Docker containers don&rsquo;t need a hypervisor, so you can pack more of
|
||
them onto your hosts. This means you get more value out of every
|
||
server and can potentially reduce what you spend on equipment and
|
||
licenses.</li>
|
||
</ul>
|
||
|
||
<p><em>Faster deployment makes for easier management</em></p>
|
||
|
||
<ul>
|
||
<li>As Docker speeds up your work flow, it gets easier to make lots
|
||
of small changes instead of huge, big bang updates. Smaller
|
||
changes mean reduced risk and more uptime.</li>
|
||
</ul>
|
||
|
||
<h2 id="about-this-guide">About this guide</h2>
|
||
|
||
<p>The <a href="introduction/understanding-docker.md">Understanding Docker section</a> will help you:</p>
|
||
|
||
<ul>
|
||
<li>See how Docker works at a high level</li>
|
||
<li>Understand the architecture of Docker</li>
|
||
<li>Discover Docker&rsquo;s features;</li>
|
||
<li>See how Docker compares to virtual machines</li>
|
||
<li>See some common use cases.</li>
|
||
</ul>
|
||
|
||
<h3 id="installation-guides">Installation guides</h3>
|
||
|
||
<p>The <a href="http://localhost/installation/#installation">installation section</a> will show you how to
|
||
install Docker on a variety of platforms.</p>
|
||
|
||
<h3 id="docker-user-guide">Docker user guide</h3>
|
||
|
||
<p>To learn about Docker in more detail and to answer questions about usage and
|
||
implementation, check out the <a href="http://localhost/userguide/">Docker User Guide</a>.</p>
|
||
|
||
<h2 id="release-notes">Release notes</h2>
|
||
|
||
<p>A summary of the changes in each release in the current series can now be found
|
||
on the separate <a href="http://localhost/release-notes/">Release Notes page</a></p>
|
||
|
||
<h2 id="licensing">Licensing</h2>
|
||
|
||
<p>Docker is licensed under the Apache License, Version 2.0. See
|
||
<a href="https://github.com/docker/docker/blob/master/LICENSE">LICENSE</a> for the full
|
||
license text.</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Accounts on Docker Hub</title>
|
||
<link>http://localhost/docker/docker-hub/accounts/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/docker-hub/accounts/</guid>
|
||
<description>
|
||
|
||
<h1 id="accounts-on-docker-hub">Accounts on Docker Hub</h1>
|
||
|
||
<h2 id="docker-hub-accounts">Docker Hub accounts</h2>
|
||
|
||
<p>You can <code>search</code> for Docker images and <code>pull</code> them from <a href="https://hub.docker.com">Docker
|
||
Hub</a> without signing in or even having an
|
||
account. However, in order to <code>push</code> images, leave comments or to <em>star</em>
|
||
a repository, you are going to need a <a href="https://hub.docker.com">Docker
|
||
Hub</a> account.</p>
|
||
|
||
<h3 id="registration-for-a-docker-hub-account">Registration for a Docker Hub account</h3>
|
||
|
||
<p>You can get a <a href="https://hub.docker.com">Docker Hub</a> account by
|
||
<a href="https://hub.docker.com/account/signup/">signing up for one here</a>. A valid
|
||
email address is required to register, which you will need to verify for
|
||
account activation.</p>
|
||
|
||
<h3 id="email-activation-process">Email activation process</h3>
|
||
|
||
<p>You need to have at least one verified email address to be able to use your
|
||
<a href="https://hub.docker.com">Docker Hub</a> account. If you can&rsquo;t find the validation email,
|
||
you can request another by visiting the <a href="https://hub.docker.com/account/resend-email-confirmation/">Resend Email Confirmation</a> page.</p>
|
||
|
||
<h3 id="password-reset-process">Password reset process</h3>
|
||
|
||
<p>If you can&rsquo;t access your account for some reason, you can reset your password
|
||
from the <a href="https://hub.docker.com/account/forgot-password/"><em>Password Reset</em></a>
|
||
page.</p>
|
||
|
||
<h2 id="organizations-and-groups">Organizations and groups</h2>
|
||
|
||
<p>A Docker Hub organization contains public and private repositories just like
|
||
a user account. Access to push, pull or create these organisation owned repositories
|
||
is allocated by defining groups of users and then assigning group rights to
|
||
specific repositories. This allows you to distribute limited access
|
||
Docker images, and to select which Docker Hub users can publish new images.</p>
|
||
|
||
<h3 id="creating-and-viewing-organizations">Creating and viewing organizations</h3>
|
||
|
||
<p>You can see what organizations <a href="https://hub.docker.com/account/organizations/">you belong to and add new organizations</a> from the Account Settings
|
||
tab. They are also listed below your user name on your repositories page
|
||
and in your account profile.</p>
|
||
|
||
<p><img src="http://localhost/docker-hub/hub-images/orgs.png" alt="organizations" />
|
||
</p>
|
||
|
||
<h3 id="organization-groups">Organization groups</h3>
|
||
|
||
<p>Users in the <code>Owners</code> group of an organization can create and modify the
|
||
membership of groups.</p>
|
||
|
||
<p>Unless they are the organization&rsquo;s <code>Owner</code>, users can only see groups of which they
|
||
are members.</p>
|
||
|
||
<p><img src="http://localhost/docker-hub/hub-images/groups.png" alt="groups" />
|
||
</p>
|
||
|
||
<h3 id="repository-group-permissions">Repository group permissions</h3>
|
||
|
||
<p>Use organization groups to manage the users that can interact with your repositories.</p>
|
||
|
||
<p>You must be in an organization&rsquo;s <code>Owners</code> group to create a new group, Hub
|
||
repository, or automated build. As an <code>Owner</code>, you then delegate the following
|
||
repository access rights to groups:</p>
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Access Right</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<tr>
|
||
<td><code>Read</code></td>
|
||
<td>Users with this right can view, search, and pull a private repository.</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td><code>Write</code></td>
|
||
<td>Users with this right can push to non-automated repositories on the Docker Hub.</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td><code>Admin</code></td>
|
||
<td>Users with this right can modify a repository&rsquo;s &ldquo;Description&rdquo;, &ldquo;Collaborators&rdquo; rights. They can also mark a repository as unlisted, change its &ldquo;Public/Private&rdquo; status and &ldquo;Delete&rdquo; the repository. Finally, <code>Admin</code> rights are required to read the build log on a repo.</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td></td>
|
||
<td></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>Regardless of their actual access rights, users with unverified email addresses
|
||
have <code>Read</code> access to the repository. Once they have verified their address,
|
||
they have their full access rights as granted on the organization.</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Advanced contributing</title>
|
||
<link>http://localhost/docker/project/advanced-contributing/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/project/advanced-contributing/</guid>
|
||
<description>
|
||
|
||
<h1 id="advanced-contributing">Advanced contributing</h1>
|
||
|
||
<p>In this section, you learn about the more advanced contributions you can make.
|
||
They are advanced because they have a more involved workflow or require greater
|
||
programming experience. Don&rsquo;t be scared off though, if you like to stretch and
|
||
challenge yourself, this is the place for you.</p>
|
||
|
||
<p>This section gives generalized instructions for advanced contributions. You&rsquo;ll
|
||
read about the workflow but there are not specific descriptions of commands.
|
||
Your goal should be to understand the processes described.</p>
|
||
|
||
<p>At this point, you should have read and worked through the earlier parts of
|
||
the project contributor guide. You should also have
|
||
<a href="../make-a-contribution/" target="_blank"> made at least one project contribution</a>.</p>
|
||
|
||
<h2 id="refactor-or-cleanup-proposal">Refactor or cleanup proposal</h2>
|
||
|
||
<p>A refactor or cleanup proposal changes Docker&rsquo;s internal structure without
|
||
altering the external behavior. To make this type of proposal:</p>
|
||
|
||
<ol>
|
||
<li><p>Fork <code>docker/docker</code>.</p></li>
|
||
|
||
<li><p>Make your changes in a feature branch.</p></li>
|
||
|
||
<li><p>Sync and rebase with <code>master</code> as you work.</p></li>
|
||
|
||
<li><p>Run the full test suite.</p></li>
|
||
|
||
<li><p>Submit your code through a pull request (PR).</p>
|
||
|
||
<p>The PR&rsquo;s title should have the format:</p>
|
||
|
||
<p><strong>Cleanup:</strong> <em>short title</em></p>
|
||
|
||
<p>If your changes required logic changes, note that in your request.</p></li>
|
||
|
||
<li><p>Work through Docker&rsquo;s review process until merge.</p></li>
|
||
</ol>
|
||
|
||
<h2 id="design-proposal">Design proposal</h2>
|
||
|
||
<p>A design proposal solves a problem or adds a feature to the Docker software.
|
||
The process for submitting design proposals requires two pull requests, one
|
||
for the design and one for the implementation.</p>
|
||
|
||
<p><img src="http://localhost/project/images/proposal.png" alt="Simple process" />
|
||
</p>
|
||
|
||
<p>The important thing to notice is that both the design pull request and the
|
||
implementation pull request go through a review. In other words, there is
|
||
considerable time commitment in a design proposal; so, you might want to pair
|
||
with someone on design work.</p>
|
||
|
||
<p>The following provides greater detail on the process:</p>
|
||
|
||
<ol>
|
||
<li><p>Come up with an idea.</p>
|
||
|
||
<p>Ideas usually come from limitations users feel working with a product. So,
|
||
take some time to really use Docker. Try it on different platforms; explore
|
||
how it works with different web applications. Go to some community events
|
||
and find out what other users want.</p></li>
|
||
|
||
<li><p>Review existing issues and proposals to make sure no other user is proposing a similar idea.</p>
|
||
|
||
<p>The design proposals are <a
|
||
href="https://github.com/docker/docker/pulls?q=is%3Aopen+is%3Apr+label%
|
||
3Akind%2Fproposal" target="_blank">all online in our GitHub pull requests</a>.</p></li>
|
||
|
||
<li><p>Talk to the community about your idea.</p>
|
||
|
||
<p>We have lots of <a href="../get-help/" target="_blank">community forums</a>
|
||
where you can get feedback on your idea. Float your idea in a forum or two
|
||
to get some commentary going on it.</p></li>
|
||
|
||
<li><p>Fork <code>docker/docker</code> and clone the repo to your local host.</p></li>
|
||
|
||
<li><p>Create a new Markdown file in the area you wish to change.</p>
|
||
|
||
<p>For example, if you want to redesign our daemon create a new file under the
|
||
<code>daemon/</code> folder.</p></li>
|
||
|
||
<li><p>Name the file descriptively, for example <code>redesign-daemon-proposal.md</code>.</p></li>
|
||
|
||
<li><p>Write a proposal for your change into the file.</p>
|
||
|
||
<p>This is a Markdown file that describes your idea. Your proposal
|
||
should include information like:</p>
|
||
|
||
<ul>
|
||
<li>Why is this change needed or what are the use cases?</li>
|
||
<li>What are the requirements this change should meet?</li>
|
||
<li>What are some ways to design/implement this feature?</li>
|
||
<li>Which design/implementation do you think is best and why?</li>
|
||
<li>What are the risks or limitations of your proposal?</li>
|
||
</ul>
|
||
|
||
<p>This is your chance to convince people your idea is sound.</p></li>
|
||
|
||
<li><p>Submit your proposal in a pull request to <code>docker/docker</code>.</p>
|
||
|
||
<p>The title should have the format:</p>
|
||
|
||
<p><strong>Proposal:</strong> <em>short title</em></p>
|
||
|
||
<p>The body of the pull request should include a brief summary of your change
|
||
and then say something like &ldquo;<em>See the file for a complete description</em>&rdquo;.</p></li>
|
||
|
||
<li><p>Refine your proposal through review.</p>
|
||
|
||
<p>The maintainers and the community review your proposal. You&rsquo;ll need to
|
||
answer questions and sometimes explain or defend your approach. This is
|
||
chance for everyone to both teach and learn.</p></li>
|
||
|
||
<li><p>Pull request accepted.</p>
|
||
|
||
<p>Your request may also be rejected. Not every idea is a good fit for Docker.
|
||
Let&rsquo;s assume though your proposal succeeded.</p></li>
|
||
|
||
<li><p>Implement your idea.</p>
|
||
|
||
<p>Implementation uses all the standard practices of any contribution.</p>
|
||
|
||
<ul>
|
||
<li>fork <code>docker/docker</code></li>
|
||
<li>create a feature branch</li>
|
||
<li>sync frequently back to master</li>
|
||
<li>test as you go and full test before a PR</li>
|
||
</ul>
|
||
|
||
<p>If you run into issues, the community is there to help.</p></li>
|
||
|
||
<li><p>When you have a complete implementation, submit a pull request back to <code>docker/docker</code>.</p></li>
|
||
|
||
<li><p>Review and iterate on your code.</p>
|
||
|
||
<p>If you are making a large code change, you can expect greater scrutiny
|
||
during this phase.</p></li>
|
||
|
||
<li><p>Acceptance and merge!</p></li>
|
||
</ol>
|
||
|
||
<h2 id="about-the-advanced-process">About the advanced process</h2>
|
||
|
||
<p>Docker is a large project. Our core team gets a great many design proposals.
|
||
Design proposal discussions can span days, weeks, and longer. The number of comments can reach the 100s.
|
||
In that situation, following the discussion flow and the decisions reached is crucial.</p>
|
||
|
||
<p>Making a pull request with a design proposal simplifies this process:
|
||
* you can leave comments on specific design proposal line
|
||
* replies around line are easy to track
|
||
* as a proposal changes and is updated, pages reset as line items resolve
|
||
* Github maintains the entire history</p>
|
||
|
||
<p>While proposals in pull requests do not end up merged into a master repository, they provide a convenient tool for managing the design process.</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Amazon EC2 Installation</title>
|
||
<link>http://localhost/docker/installation/amazon/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/installation/amazon/</guid>
|
||
<description>
|
||
|
||
<h2 id="amazon-ec2">Amazon EC2</h2>
|
||
|
||
<p>You can install Docker on any AWS EC2 Amazon Machine Image (AMI) which runs an
|
||
operating system that Docker supports. Amazon&rsquo;s website includes specific
|
||
instructions for <a href="http://docs.aws.amazon.com/AmazonECS/latest/developerguide/docker-basics.html#install_docker">installing on Amazon
|
||
Linux</a>. To install on
|
||
another AMI, follow the instructions for its specific operating
|
||
system in this installation guide.</p>
|
||
|
||
<p>For detailed information on Amazon AWS support for Docker, refer to <a href="http://docs.aws.amazon.com/AmazonECS/latest/developerguide/docker-basics.html">Amazon&rsquo;s
|
||
documentation</a>.</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Apply custom metadata</title>
|
||
<link>http://localhost/docker/userguide/labels-custom-metadata/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/userguide/labels-custom-metadata/</guid>
|
||
<description>
|
||
|
||
<h1 id="apply-custom-metadata">Apply custom metadata</h1>
|
||
|
||
<p>You can apply metadata to your images, containers, or daemons via
|
||
labels. Metadata can serve a wide range of uses. Use labels to add notes or
|
||
licensing information to an image or to identify a host.</p>
|
||
|
||
<p>A label is a <code>&lt;key&gt;</code> / <code>&lt;value&gt;</code> pair. Docker stores the label values as
|
||
<em>strings</em>. You can specify multiple labels but each <code>&lt;key&gt;</code> / <code>&lt;value&gt;</code> must be
|
||
unique to avoid overwriting. If you specify the same <code>key</code> several times but with
|
||
different values, newer labels overwrite previous labels. Docker uses
|
||
the last <code>key=value</code> you supply.</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong> Support for daemon-labels was added in Docker 1.4.1. Labels on
|
||
containers and images are new in Docker 1.6.0</p>
|
||
</blockquote>
|
||
|
||
<h2 id="label-keys-namespaces">Label keys (namespaces)</h2>
|
||
|
||
<p>Docker puts no hard restrictions on the label <code>key</code> you. However, labels with
|
||
simple keys can conflict. For example, you can categorize your images by using a
|
||
chip &ldquo;architecture&rdquo; label:</p>
|
||
|
||
<pre><code>LABEL architecture=&quot;amd64&quot;
|
||
|
||
LABEL architecture=&quot;ARMv7&quot;
|
||
</code></pre>
|
||
|
||
<p>But a user can label images by building architectural style:</p>
|
||
|
||
<pre><code>LABEL architecture=&quot;Art Nouveau&quot;
|
||
</code></pre>
|
||
|
||
<p>To prevent naming conflicts, Docker namespaces label keys using a reverse domain
|
||
notation. Use the following guidelines to name your keys:</p>
|
||
|
||
<ul>
|
||
<li><p>All (third-party) tools should prefix their keys with the
|
||
reverse DNS notation of a domain controlled by the author. For
|
||
example, <code>com.example.some-label</code>.</p></li>
|
||
|
||
<li><p>The <code>com.docker.*</code>, <code>io.docker.*</code> and <code>org.dockerproject.*</code> namespaces are
|
||
reserved for Docker&rsquo;s internal use.</p></li>
|
||
|
||
<li><p>Keys should only consist of lower-cased alphanumeric characters,
|
||
dots and dashes (for example, <code>[a-z0-9-.]</code>)</p></li>
|
||
|
||
<li><p>Keys should start <em>and</em> end with an alpha numeric character</p></li>
|
||
|
||
<li><p>Keys may not contain consecutive dots or dashes.</p></li>
|
||
|
||
<li><p>Keys <em>without</em> namespace (dots) are reserved for CLI use. This allows end-
|
||
users to add metadata to their containers and images without having to type
|
||
cumbersome namespaces on the command-line.</p></li>
|
||
</ul>
|
||
|
||
<p>These are guidelines and Docker does not <em>enforce</em> them. Failing following these
|
||
guidelines can result in conflicting labels. If you&rsquo;re building a tool that uses
|
||
labels, you <em>should</em> use namespaces for your label keys.</p>
|
||
|
||
<h2 id="store-structured-data-in-labels">Store structured data in labels</h2>
|
||
|
||
<p>Label values can contain any data type that can be stored as a string. For
|
||
example, consider this JSON:</p>
|
||
|
||
<pre><code>{
|
||
&quot;Description&quot;: &quot;A containerized foobar&quot;,
|
||
&quot;Usage&quot;: &quot;docker run --rm example/foobar [args]&quot;,
|
||
&quot;License&quot;: &quot;GPL&quot;,
|
||
&quot;Version&quot;: &quot;0.0.1-beta&quot;,
|
||
&quot;aBoolean&quot;: true,
|
||
&quot;aNumber&quot; : 0.01234,
|
||
&quot;aNestedArray&quot;: [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;]
|
||
}
|
||
</code></pre>
|
||
|
||
<p>You can store this struct in a label by serializing it to a string first:</p>
|
||
|
||
<pre><code>LABEL com.example.image-specs=&quot;{\&quot;Description\&quot;:\&quot;A containerized foobar\&quot;,\&quot;Usage\&quot;:\&quot;docker run --rm example\\/foobar [args]\&quot;,\&quot;License\&quot;:\&quot;GPL\&quot;,\&quot;Version\&quot;:\&quot;0.0.1-beta\&quot;,\&quot;aBoolean\&quot;:true,\&quot;aNumber\&quot;:0.01234,\&quot;aNestedArray\&quot;:[\&quot;a\&quot;,\&quot;b\&quot;,\&quot;c\&quot;]}&quot;
|
||
</code></pre>
|
||
|
||
<p>While it is <em>possible</em> to store structured data in label values, Docker treats
|
||
this data as a &lsquo;regular&rsquo; string. This means that Docker doesn&rsquo;t offer ways to
|
||
query (filter) based on nested properties. If your tool needs to filter on
|
||
nested properties, the tool itself should implement this.</p>
|
||
|
||
<h2 id="add-labels-to-images-the-label-instruction">Add labels to images; the <code>LABEL</code> instruction</h2>
|
||
|
||
<p>Adding labels to an image:</p>
|
||
|
||
<pre><code>LABEL [&lt;namespace&gt;.]&lt;key&gt;[=&lt;value&gt;] ...
|
||
</code></pre>
|
||
|
||
<p>The <code>LABEL</code> instruction adds a label to your image, optionally setting its value.
|
||
Use surrounding quotes or backslashes for labels that contain
|
||
white space character:</p>
|
||
|
||
<pre><code>LABEL vendor=ACME\ Incorporated
|
||
LABEL com.example.version.is-beta
|
||
LABEL com.example.version=&quot;0.0.1-beta&quot;
|
||
LABEL com.example.release-date=&quot;2015-02-12&quot;
|
||
</code></pre>
|
||
|
||
<p>The <code>LABEL</code> instruction supports setting multiple labels in a single instruction
|
||
using this notation:</p>
|
||
|
||
<pre><code>LABEL com.example.version=&quot;0.0.1-beta&quot; com.example.release-date=&quot;2015-02-12&quot;
|
||
</code></pre>
|
||
|
||
<p>Wrapping is allowed by using a backslash (<code>\</code>) as continuation marker:</p>
|
||
|
||
<pre><code>LABEL vendor=ACME\ Incorporated \
|
||
com.example.is-beta \
|
||
com.example.version=&quot;0.0.1-beta&quot; \
|
||
com.example.release-date=&quot;2015-02-12&quot;
|
||
</code></pre>
|
||
|
||
<p>Docker recommends you add multiple labels in a single <code>LABEL</code> instruction. Using
|
||
individual instructions for each label can result in an inefficient image. This
|
||
is because each <code>LABEL</code> instruction in a Dockerfile produces a new IMAGE layer.</p>
|
||
|
||
<p>You can view the labels via the <code>docker inspect</code> command:</p>
|
||
|
||
<pre><code>$ docker inspect 4fa6e0f0c678
|
||
|
||
...
|
||
&quot;Labels&quot;: {
|
||
&quot;vendor&quot;: &quot;ACME Incorporated&quot;,
|
||
&quot;com.example.is-beta&quot;: &quot;&quot;,
|
||
&quot;com.example.version&quot;: &quot;0.0.1-beta&quot;,
|
||
&quot;com.example.release-date&quot;: &quot;2015-02-12&quot;
|
||
}
|
||
...
|
||
|
||
# Inspect labels on container
|
||
$ docker inspect -f &quot;{{json .Config.Labels }}&quot; 4fa6e0f0c678
|
||
|
||
{&quot;Vendor&quot;:&quot;ACME Incorporated&quot;,&quot;com.example.is-beta&quot;:&quot;&quot;,&quot;com.example.version&quot;:&quot;0.0.1-beta&quot;,&quot;com.example.release-date&quot;:&quot;2015-02-12&quot;}
|
||
|
||
# Inspect labels on images
|
||
$ docker inspect -f &quot;{{json .ContainerConfig.Labels }}&quot; myimage
|
||
</code></pre>
|
||
|
||
<h2 id="query-labels">Query labels</h2>
|
||
|
||
<p>Besides storing metadata, you can filter images and containers by label. To list all
|
||
running containers that the <code>com.example.is-beta</code> label:</p>
|
||
|
||
<pre><code># List all running containers that have a `com.example.is-beta` label
|
||
$ docker ps --filter &quot;label=com.example.is-beta&quot;
|
||
</code></pre>
|
||
|
||
<p>List all running containers with a <code>color</code> label of <code>blue</code>:</p>
|
||
|
||
<pre><code>$ docker ps --filter &quot;label=color=blue&quot;
|
||
</code></pre>
|
||
|
||
<p>List all images with <code>vendor</code> <code>ACME</code>:</p>
|
||
|
||
<pre><code>$ docker images --filter &quot;label=vendor=ACME&quot;
|
||
</code></pre>
|
||
|
||
<h2 id="daemon-labels">Daemon labels</h2>
|
||
|
||
<pre><code>docker -d \
|
||
--dns 8.8.8.8 \
|
||
--dns 8.8.4.4 \
|
||
-H unix:///var/run/docker.sock \
|
||
--label com.example.environment=&quot;production&quot; \
|
||
--label com.example.storage=&quot;ssd&quot;
|
||
</code></pre>
|
||
|
||
<p>These labels appear as part of the <code>docker info</code> output for the daemon:</p>
|
||
|
||
<pre><code>docker -D info
|
||
Containers: 12
|
||
Images: 672
|
||
Storage Driver: aufs
|
||
Root Dir: /var/lib/docker/aufs
|
||
Backing Filesystem: extfs
|
||
Dirs: 697
|
||
Execution Driver: native-0.2
|
||
Logging Driver: json-file
|
||
Kernel Version: 3.13.0-32-generic
|
||
Operating System: Ubuntu 14.04.1 LTS
|
||
CPUs: 1
|
||
Total Memory: 994.1 MiB
|
||
Name: docker.example.com
|
||
ID: RC3P:JTCT:32YS:XYSB:YUBG:VFED:AAJZ:W3YW:76XO:D7NN:TEVU:UCRW
|
||
Debug mode (server): false
|
||
Debug mode (client): true
|
||
File Descriptors: 11
|
||
Goroutines: 14
|
||
EventsListeners: 0
|
||
Init Path: /usr/bin/docker
|
||
Docker Root Dir: /var/lib/docker
|
||
WARNING: No swap limit support
|
||
Labels:
|
||
com.example.environment=production
|
||
com.example.storage=ssd
|
||
</code></pre>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Automated Builds on Docker Hub</title>
|
||
<link>http://localhost/docker/docker-hub/builds/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/docker-hub/builds/</guid>
|
||
<description>
|
||
|
||
<h1 id="automated-builds-on-docker-hub">Automated Builds on Docker Hub</h1>
|
||
|
||
<h2 id="about-automated-builds">About Automated Builds</h2>
|
||
|
||
<p><em>Automated Builds</em> are a special feature of Docker Hub which allow you to
|
||
use <a href="https://hub.docker.com">Docker Hub&rsquo;s</a> build clusters to automatically
|
||
create images from a GitHub or Bitbucket repository containing a <code>Dockerfile</code>
|
||
The system will clone your repository and build the image described by the
|
||
<code>Dockerfile</code> using the directory the <code>Dockerfile</code> is in (and subdirectories)
|
||
as the build context. The resulting automated image will then be uploaded
|
||
to the Docker Hub registry and marked as an <em>Automated Build</em>.</p>
|
||
|
||
<p>Automated Builds have several advantages:</p>
|
||
|
||
<ul>
|
||
<li>Users of <em>your</em> Automated Build can trust that the resulting
|
||
image was built exactly as specified.</li>
|
||
<li>The <code>Dockerfile</code> will be available to anyone with access to
|
||
your repository on the Docker Hub registry.</li>
|
||
<li>Because the process is automated, Automated Builds help to
|
||
make sure that your repository is always up to date.</li>
|
||
</ul>
|
||
|
||
<p>Automated Builds are supported for both public and private repositories
|
||
on both <a href="http://github.com">GitHub</a> and <a href="https://bitbucket.org/">Bitbucket</a>.</p>
|
||
|
||
<p>To use Automated Builds, you must have an <a href="https://docs.docker.com/userguide/dockerhub/#creating-a-docker-hub-account">account on Docker Hub</a>
|
||
and on GitHub and/or Bitbucket. In either case, the account needs
|
||
to be properly validated and activated before you can link to it.</p>
|
||
|
||
<p>The first time you to set up an Automated Build, your
|
||
<a href="https://hub.docker.com">Docker Hub</a> account will need to be linked to
|
||
a GitHub or Bitbucket account.
|
||
This will allow the registry to see your repositories.</p>
|
||
|
||
<p>If you have previously linked your Docker Hub account, and want to view or modify
|
||
that link, click on the &ldquo;Manage - Settings&rdquo; link in the sidebar, and then
|
||
&ldquo;Linked Accounts&rdquo; in your Settings sidebar.</p>
|
||
|
||
<h2 id="automated-builds-from-github">Automated Builds from GitHub</h2>
|
||
|
||
<p>If you&rsquo;ve previously linked your Docker Hub account to your GitHub account,
|
||
you&rsquo;ll be able to skip to the <a href="#creating-an-automated-build">Creating an Automated Build</a>.</p>
|
||
|
||
<h3 id="linking-your-docker-hub-account-to-a-github-account">Linking your Docker Hub account to a GitHub account</h3>
|
||
|
||
<blockquote>
|
||
<p><em>Note:</em>
|
||
Automated Builds currently require <em>read</em> and <em>write</em> access since
|
||
<a href="https://hub.docker.com">Docker Hub</a> needs to setup a GitHub service
|
||
hook. We have no choice here, this is how GitHub manages permissions, sorry!
|
||
We do guarantee nothing else will be touched in your account.</p>
|
||
</blockquote>
|
||
|
||
<p>To get started, log into your Docker Hub account and click the
|
||
&ldquo;+ Add Repository&rdquo; button at the upper right of the screen. Then select
|
||
<a href="https://registry.hub.docker.com/builds/add/">Automated Build</a>.</p>
|
||
|
||
<p>Select the <a href="https://registry.hub.docker.com/associate/github/">GitHub service</a>.</p>
|
||
|
||
<p>When linking to GitHub, you&rsquo;ll need to select either &ldquo;Public and Private&rdquo;,
|
||
or &ldquo;Limited&rdquo; linking.</p>
|
||
|
||
<p>The &ldquo;Public and Private&rdquo; option is the easiest to use,
|
||
as it grants the Docker Hub full access to all of your repositories. GitHub
|
||
also allows you to grant access to repositories belonging to your GitHub
|
||
organizations.</p>
|
||
|
||
<p>By choosing the &ldquo;Limited&rdquo; linking, your Docker Hub account only gets permission
|
||
to access your public data and public repositories.</p>
|
||
|
||
<p>Follow the onscreen instructions to authorize and link your
|
||
GitHub account to Docker Hub. Once it is linked, you&rsquo;ll be able to
|
||
choose a source repository from which to create the Automatic Build.</p>
|
||
|
||
<p>You will be able to review and revoke Docker Hub&rsquo;s access by visiting the
|
||
<a href="https://github.com/settings/applications">GitHub User&rsquo;s Applications settings</a>.</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Note</strong>: If you delete the GitHub account linkage that is used for one of your
|
||
automated build repositories, the previously built images will still be available.
|
||
If you re-link to that GitHub account later, the automated build can be started
|
||
using the &ldquo;Start Build&rdquo; button on the Hub, or if the webhook on the GitHub repository
|
||
still exists, will be triggered by any subsequent commits.</p>
|
||
</blockquote>
|
||
|
||
<h3 id="auto-builds-and-limited-linked-github-accounts">Auto builds and limited linked GitHub accounts.</h3>
|
||
|
||
<p>If you selected to link your GitHub account with only a &ldquo;Limited&rdquo; link, then
|
||
after creating your automated build, you will need to either manually trigger a
|
||
Docker Hub build using the &ldquo;Start a Build&rdquo; button, or add the GitHub webhook
|
||
manually, as described in <a href="#github-service-hooks">GitHub Service Hooks</a>.</p>
|
||
|
||
<h3 id="changing-the-github-user-link">Changing the GitHub user link</h3>
|
||
|
||
<p>If you want to remove, or change the level of linking between your GitHub account
|
||
and the Docker Hub, you need to do this in two places.</p>
|
||
|
||
<p>First, remove the &ldquo;Linked Account&rdquo; from your Docker Hub &ldquo;Settings&rdquo;.
|
||
Then go to your GitHub account&rsquo;s Personal settings, and in the &ldquo;Applications&rdquo;
|
||
section, &ldquo;Revoke access&rdquo;.</p>
|
||
|
||
<p>You can now re-link your account at any time.</p>
|
||
|
||
<h3 id="github-organizations">GitHub organizations</h3>
|
||
|
||
<p>GitHub organizations and private repositories forked from organizations will be
|
||
made available to auto build using the &ldquo;Docker Hub Registry&rdquo; application, which
|
||
needs to be added to the organization - and then will apply to all users.</p>
|
||
|
||
<p>To check, or request access, go to your GitHub user&rsquo;s &ldquo;Setting&rdquo; page, select the
|
||
&ldquo;Applications&rdquo; section from the left side bar, then click the &ldquo;View&rdquo; button for
|
||
&ldquo;Docker Hub Registry&rdquo;.</p>
|
||
|
||
<p><img src="http://localhost/docker-hub/hub-images/gh-check-user-org-dh-app-access.png" alt="Check User access to GitHub" />
|
||
</p>
|
||
|
||
<p>The organization&rsquo;s administrators may need to go to the Organization&rsquo;s &ldquo;Third
|
||
party access&rdquo; screen in &ldquo;Settings&rdquo; to Grant or Deny access to the Docker Hub
|
||
Registry application. This change will apply to all organization members.</p>
|
||
|
||
<p><img src="http://localhost/docker-hub/hub-images/gh-check-admin-org-dh-app-access.png" alt="Check Docker Hub application access to Organization" />
|
||
</p>
|
||
|
||
<p>More detailed access controls to specific users and GitHub repositories would be
|
||
managed using the GitHub People and Teams interfaces.</p>
|
||
|
||
<h3 id="creating-an-automated-build">Creating an Automated Build</h3>
|
||
|
||
<p>You can <a href="https://registry.hub.docker.com/builds/github/select/">create an Automated Build</a> from any of your
|
||
public or private GitHub repositories that have a <code>Dockerfile</code>.</p>
|
||
|
||
<p>Once you&rsquo;ve selected the source repository, you can then configure:</p>
|
||
|
||
<ul>
|
||
<li>The Hub user/org the repository is built to - either your Hub account name,
|
||
or the name of any Hub organizations your account is in</li>
|
||
<li>The Docker repository name the image is built to</li>
|
||
<li>If the Docker repository should be &ldquo;Public&rdquo; or &ldquo;Private&rdquo;
|
||
You can change the accessibility options after the repository has been created.
|
||
If you add a Private repository to a Hub user, then you can only add other users
|
||
as collaborators, and those users will be able to view and pull all images in that
|
||
repository. To configure more granular access permissions, such as using groups of
|
||
users or allow different users access to different image tags, then you need
|
||
to add the Private repository to a Hub organization that your user has Administrator
|
||
privilege on.</li>
|
||
<li>If you want the GitHub to notify the Docker Hub when a commit is made, and thus trigger
|
||
a rebuild of all the images in this automated build.</li>
|
||
</ul>
|
||
|
||
<p>You can also select one or more
|
||
- The git branch/tag, which repository sub-directory to use as the context
|
||
- The Docker image tag name</p>
|
||
|
||
<p>You can set a description for the repository by clicking &ldquo;Description&rdquo; link in the righthand side bar after the automated build - note that the &ldquo;Full Description&rdquo; will be over-written next build from the README.md file.
|
||
has been created.</p>
|
||
|
||
<h3 id="github-private-submodules">GitHub private submodules</h3>
|
||
|
||
<p>If your GitHub repository contains links to private submodules, you&rsquo;ll get an
|
||
error message in your build.</p>
|
||
|
||
<p>Normally, the Docker Hub sets up a deploy key in your GitHub repository.
|
||
Unfortunately, GitHub only allows a repository deploy key to access a single repository.</p>
|
||
|
||
<p>To work around this, you need to create a dedicated user account in GitHub and attach
|
||
the automated build&rsquo;s deploy key that account. This dedicated build account
|
||
can be limited to read-only access to just the repositories required to build.</p>
|
||
|
||
<table class="table table-bordered">
|
||
<thead>
|
||
<tr>
|
||
<th>Step</th>
|
||
<th>Screenshot</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>1.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/gh_org_members.png"></td>
|
||
<td>First, create the new account in GitHub. It should be given read-only
|
||
access to the main repository and all submodules that are needed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>2.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/gh_team_members.png"></td>
|
||
<td>This can be accomplished by adding the account to a read-only team in
|
||
the organization(s) where the main GitHub repository and all submodule
|
||
repositories are kept.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>3.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/gh_repo_deploy_key.png"></td>
|
||
<td>Next, remove the deploy key from the main GitHub repository. This can be done in the GitHub repository's "Deploy keys" Settings section.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>4.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/deploy_key.png"></td>
|
||
<td>Your automated build's deploy key is in the "Build Details" menu
|
||
under "Deploy keys".</td>
|
||
</tr>
|
||
<tr>
|
||
<td>5.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/gh_add_ssh_user_key.png"></td>
|
||
<td>In your dedicated GitHub User account, add the deploy key from your
|
||
Docker Hub Automated Build.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3 id="github-service-hooks">GitHub service hooks</h3>
|
||
|
||
<p>The GitHub Service hook allows GitHub to notify the Docker Hub when something has
|
||
been committed to that git repository. You will need to add the Service Hook manually
|
||
if your GitHub account is &ldquo;Limited&rdquo; linked to the Docker Hub.</p>
|
||
|
||
<p>Follow the steps below to configure the GitHub Service hooks for your Automated Build:</p>
|
||
|
||
<table class="table table-bordered">
|
||
<thead>
|
||
<tr>
|
||
<th>Step</th>
|
||
<th>Screenshot</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>1.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/gh_settings.png"></td>
|
||
<td>Log in to Github.com, and go to your Repository page. Click on "Settings" on
|
||
the right side of the page. You must have admin privileges to the repository in order to do this.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>2.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/gh_menu.png" alt="Webhooks & Services"></td>
|
||
<td>Click on "Webhooks & Services" on the left side of the page.</td></tr>
|
||
<tr><td>3.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/gh_service_hook.png" alt="Find the service labeled Docker"></td>
|
||
<td>Find the service labeled "Docker" (or click on "Add service") and click on it.</td></tr>
|
||
<tr><td>4.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/gh_docker-service.png" alt="Activate Service Hooks"></td>
|
||
<td>Make sure the "Active" checkbox is selected and click the "Update service" button to save your changes.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h2 id="automated-builds-with-bitbucket">Automated Builds with Bitbucket</h2>
|
||
|
||
<p>In order to setup an Automated Build, you need to first link your
|
||
<a href="https://hub.docker.com">Docker Hub</a> account with a Bitbucket account.
|
||
This will allow the registry to see your repositories.</p>
|
||
|
||
<p>To get started, log into your Docker Hub account and click the
|
||
&ldquo;+ Add Repository&rdquo; button at the upper right of the screen. Then
|
||
select <a href="https://registry.hub.docker.com/builds/add/">Automated Build</a>.</p>
|
||
|
||
<p>Select the <a href="https://registry.hub.docker.com/associate/bitbucket/">Bitbucket source</a>.</p>
|
||
|
||
<p>Then follow the onscreen instructions to authorize and link your
|
||
Bitbucket account to Docker Hub. Once it is linked, you&rsquo;ll be able
|
||
to choose a repository from which to create the Automatic Build.</p>
|
||
|
||
<h3 id="creating-an-automated-build-1">Creating an Automated Build</h3>
|
||
|
||
<p>You can <a href="https://registry.hub.docker.com/builds/bitbucket/select/">create an Automated Build</a> from any of your
|
||
public or private Bitbucket repositories with a <code>Dockerfile</code>.</p>
|
||
|
||
<h3 id="adding-a-hook">Adding a Hook</h3>
|
||
|
||
<p>When you link your Docker Hub account, a <code>POST</code> hook should get automatically
|
||
added to your Bitbucket repository. Follow the steps below to confirm or modify the
|
||
Bitbucket hooks for your Automated Build:</p>
|
||
|
||
<table class="table table-bordered">
|
||
<thead>
|
||
<tr>
|
||
<th>Step</th>
|
||
<th>Screenshot</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>1.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/bb_menu.png" alt="Settings" width="180"></td>
|
||
<td>Log in to Bitbucket.org and go to your Repository page. Click on "Settings" on
|
||
the far left side of the page, under "Navigation". You must have admin privileges
|
||
to the repository in order to do this.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>2.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/bb_hooks.png" alt="Hooks" width="180"></td>
|
||
<td>Click on "Hooks" on the near left side of the page, under "Settings".</td></tr>
|
||
<tr>
|
||
<td>3.</td>
|
||
<td><img src="http://localhost/docker-hub/hub-images/bb_post-hook.png" alt="Docker Post Hook"></td><td>You should now see a list of hooks associated with the repo, including a <code>POST</code> hook that points at
|
||
registry.hub.docker.com/hooks/bitbucket.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h2 id="the-dockerfile-and-automated-builds">The Dockerfile and Automated Builds</h2>
|
||
|
||
<p>During the build process, Docker will copy the contents of your <code>Dockerfile</code>.
|
||
It will also add it to the <a href="https://hub.docker.com">Docker Hub</a> for the Docker
|
||
community (for public repositories) or approved team members/orgs (for private
|
||
repositories) to see on the repository page.</p>
|
||
|
||
<h3 id="readme-md">README.md</h3>
|
||
|
||
<p>If you have a <code>README.md</code> file in your repository, it will be used as the
|
||
repository&rsquo;s full description.The build process will look for a
|
||
<code>README.md</code> in the same directory as your <code>Dockerfile</code>.</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Warning:</strong>
|
||
If you change the full description after a build, it will be
|
||
rewritten the next time the Automated Build has been built. To make changes,
|
||
modify the <code>README.md</code> from the Git repository.</p>
|
||
</blockquote>
|
||
|
||
<h2 id="remote-build-triggers">Remote Build triggers</h2>
|
||
|
||
<p>If you need a way to trigger Automated Builds outside of GitHub or Bitbucket,
|
||
you can set up a build trigger. When you turn on the build trigger for an
|
||
Automated Build, it will give you a URL to which you can send POST requests.
|
||
This will trigger the Automated Build, much as with a GitHub webhook.</p>
|
||
|
||
<p>Build triggers are available under the Settings menu of each Automated Build
|
||
repository on the Docker Hub.</p>
|
||
|
||
<p><img src="http://localhost/docker-hub/hub-images/build-trigger.png" alt="Build trigger screen" />
|
||
</p>
|
||
|
||
<p>You can use <code>curl</code> to trigger a build:</p>
|
||
|
||
<pre><code>$ curl --data &quot;build=true&quot; -X POST https://registry.hub.docker.com/u/svendowideit/testhook/trigger/be579c
|
||
82-7c0e-11e4-81c4-0242ac110020/
|
||
OK
|
||
</code></pre>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong>
|
||
You can only trigger one build at a time and no more than one
|
||
every five minutes. If you already have a build pending, or if you
|
||
recently submitted a build request, those requests <em>will be ignored</em>.
|
||
To verify everything is working correctly, check the logs of last
|
||
ten triggers on the settings page .</p>
|
||
</blockquote>
|
||
|
||
<h2 id="webhooks">Webhooks</h2>
|
||
|
||
<p>Automated Builds also include a Webhooks feature. Webhooks can be called
|
||
after a successful repository push is made. This includes when a new tag is added
|
||
to an existing image.</p>
|
||
|
||
<p>The webhook call will generate a HTTP POST with the following JSON
|
||
payload:</p>
|
||
|
||
<pre><code>{
|
||
&quot;callback_url&quot;: &quot;https://registry.hub.docker.com/u/svendowideit/testhook/hook/2141b5bi5i5b02bec211i4eeih0242eg11000a/&quot;,
|
||
&quot;push_data&quot;: {
|
||
&quot;images&quot;: [
|
||
&quot;27d47432a69bca5f2700e4dff7de0388ed65f9d3fb1ec645e2bc24c223dc1cc3&quot;,
|
||
&quot;51a9c7c1f8bb2fa19bcd09789a34e63f35abb80044bc10196e304f6634cc582c&quot;,
|
||
...
|
||
],
|
||
&quot;pushed_at&quot;: 1.417566161e+09,
|
||
&quot;pusher&quot;: &quot;trustedbuilder&quot;
|
||
},
|
||
&quot;repository&quot;: {
|
||
&quot;comment_count&quot;: 0,
|
||
&quot;date_created&quot;: 1.417494799e+09,
|
||
&quot;description&quot;: &quot;&quot;,
|
||
&quot;dockerfile&quot;: &quot;#\n# BUILD\u0009\u0009docker build -t svendowideit/apt-cacher .\n# RUN\u0009\u0009docker run -d -p 3142:3142 -name apt-cacher-run apt-cacher\n#\n# and then you can run containers with:\n# \u0009\u0009docker run -t -i -rm -e http_proxy http://192.168.1.2:3142/ debian bash\n#\nFROM\u0009\u0009ubuntu\nMAINTAINER\u0009SvenDowideit@home.org.au\n\n\nVOLUME\u0009\u0009[\&quot;/var/cache/apt-cacher-ng\&quot;]\nRUN\u0009\u0009apt-get update ; apt-get install -yq apt-cacher-ng\n\nEXPOSE \u0009\u00093142\nCMD\u0009\u0009chmod 777 /var/cache/apt-cacher-ng ; /etc/init.d/apt-cacher-ng start ; tail -f /var/log/apt-cacher-ng/*\n&quot;,
|
||
&quot;full_description&quot;: &quot;Docker Hub based automated build from a GitHub repo&quot;,
|
||
&quot;is_official&quot;: false,
|
||
&quot;is_private&quot;: true,
|
||
&quot;is_trusted&quot;: true,
|
||
&quot;name&quot;: &quot;testhook&quot;,
|
||
&quot;namespace&quot;: &quot;svendowideit&quot;,
|
||
&quot;owner&quot;: &quot;svendowideit&quot;,
|
||
&quot;repo_name&quot;: &quot;svendowideit/testhook&quot;,
|
||
&quot;repo_url&quot;: &quot;https://registry.hub.docker.com/u/svendowideit/testhook/&quot;,
|
||
&quot;star_count&quot;: 0,
|
||
&quot;status&quot;: &quot;Active&quot;
|
||
}
|
||
}
|
||
</code></pre>
|
||
|
||
<p>Webhooks are available under the Settings menu of each Repository.</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong> If you want to test your webhook out we recommend using
|
||
a tool like <a href="http://requestb.in/">requestb.in</a>.</p>
|
||
|
||
<p><strong>Note</strong>: The Docker Hub servers are currently in the IP range
|
||
<code>162.242.195.64 - 162.242.195.127</code>, so you can restrict your webhooks to
|
||
accept webhook requests from that set of IP addresses.</p>
|
||
</blockquote>
|
||
|
||
<h3 id="webhook-chains">Webhook chains</h3>
|
||
|
||
<p>Webhook chains allow you to chain calls to multiple services. For example,
|
||
you can use this to trigger a deployment of your container only after
|
||
it has been successfully tested, then update a separate Changelog once the
|
||
deployment is complete.
|
||
After clicking the &ldquo;Add webhook&rdquo; button, simply add as many URLs as necessary
|
||
in your chain.</p>
|
||
|
||
<p>The first webhook in a chain will be called after a successful push. Subsequent
|
||
URLs will be contacted after the callback has been validated.</p>
|
||
|
||
<h3 id="validating-a-callback">Validating a callback</h3>
|
||
|
||
<p>In order to validate a callback in a webhook chain, you need to</p>
|
||
|
||
<ol>
|
||
<li>Retrieve the <code>callback_url</code> value in the request&rsquo;s JSON payload.</li>
|
||
<li>Send a POST request to this URL containing a valid JSON body.</li>
|
||
</ol>
|
||
|
||
<blockquote>
|
||
<p><strong>Note</strong>: A chain request will only be considered complete once the last
|
||
callback has been validated.</p>
|
||
</blockquote>
|
||
|
||
<p>To help you debug or simply view the results of your webhook(s),
|
||
view the &ldquo;History&rdquo; of the webhook available on its settings page.</p>
|
||
|
||
<h3 id="callback-json-data">Callback JSON data</h3>
|
||
|
||
<p>The following parameters are recognized in callback data:</p>
|
||
|
||
<ul>
|
||
<li><code>state</code> (required): Accepted values are <code>success</code>, <code>failure</code> and <code>error</code>.
|
||
If the state isn&rsquo;t <code>success</code>, the webhook chain will be interrupted.</li>
|
||
<li><code>description</code>: A string containing miscellaneous information that will be
|
||
available on the Docker Hub. Maximum 255 characters.</li>
|
||
<li><code>context</code>: A string containing the context of the operation. Can be retrieved
|
||
from the Docker Hub. Maximum 100 characters.</li>
|
||
<li><code>target_url</code>: The URL where the results of the operation can be found. Can be
|
||
retrieved on the Docker Hub.</li>
|
||
</ul>
|
||
|
||
<p><em>Example callback payload:</em></p>
|
||
|
||
<pre><code>{
|
||
&quot;state&quot;: &quot;success&quot;,
|
||
&quot;description&quot;: &quot;387 tests PASSED&quot;,
|
||
&quot;context&quot;: &quot;Continuous integration by Acme CI&quot;,
|
||
&quot;target_url&quot;: &quot;http://ci.acme.com/results/afd339c1c3d27&quot;
|
||
}
|
||
</code></pre>
|
||
|
||
<h2 id="repository-links">Repository links</h2>
|
||
|
||
<p>Repository links are a way to associate one Automated Build with
|
||
another. If one gets updated,the linking system triggers a rebuild
|
||
for the other Automated Build. This makes it easy to keep all your
|
||
Automated Builds up to date.</p>
|
||
|
||
<p>To add a link, go to the repository for the Automated Build you want to
|
||
link to and click on <em>Repository Links</em> under the Settings menu at
|
||
right. Then, enter the name of the repository that you want have linked.</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Warning:</strong>
|
||
You can add more than one repository link, however, you should
|
||
do so very carefully. Creating a two way relationship between Automated Builds will
|
||
cause an endless build loop.</p>
|
||
</blockquote>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Automatically start containers</title>
|
||
<link>http://localhost/docker/articles/host_integration/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/articles/host_integration/</guid>
|
||
<description>
|
||
|
||
<h1 id="automatically-start-containers">Automatically start containers</h1>
|
||
|
||
<p>As of Docker 1.2,
|
||
<a href="http://localhost/reference/commandline/cli/#restart-policies">restart policies</a> are the
|
||
built-in Docker mechanism for restarting containers when they exit. If set,
|
||
restart policies will be used when the Docker daemon starts up, as typically
|
||
happens after a system boot. Restart policies will ensure that linked containers
|
||
are started in the correct order.</p>
|
||
|
||
<p>If restart policies don&rsquo;t suit your needs (i.e., you have non-Docker processes
|
||
that depend on Docker containers), you can use a process manager like
|
||
<a href="http://upstart.ubuntu.com/">upstart</a>,
|
||
<a href="http://freedesktop.org/wiki/Software/systemd/">systemd</a> or
|
||
<a href="http://supervisord.org/">supervisor</a> instead.</p>
|
||
|
||
<h2 id="using-a-process-manager">Using a process manager</h2>
|
||
|
||
<p>Docker does not set any restart policies by default, but be aware that they will
|
||
conflict with most process managers. So don&rsquo;t set restart policies if you are
|
||
using a process manager.</p>
|
||
|
||
<p><em>Note:</em> Prior to Docker 1.2, restarting of Docker containers had to be
|
||
explicitly disabled. Refer to the
|
||
<a href="http://localhost/v1.1/articles/host_integration/">previous version</a> of this article for the
|
||
details on how to do that.</p>
|
||
|
||
<p>When you have finished setting up your image and are happy with your
|
||
running container, you can then attach a process manager to manage it.
|
||
When you run <code>docker start -a</code>, Docker will automatically attach to the
|
||
running container, or start it if needed and forward all signals so that
|
||
the process manager can detect when a container stops and correctly
|
||
restart it.</p>
|
||
|
||
<p>Here are a few sample scripts for systemd and upstart to integrate with
|
||
Docker.</p>
|
||
|
||
<h2 id="examples">Examples</h2>
|
||
|
||
<p>The examples below show configuration files for two popular process managers,
|
||
upstart and systemd. In these examples, we&rsquo;ll assume that we have already
|
||
created a container to run Redis with <code>--name=redis_server</code>. These files define
|
||
a new service that will be started after the docker daemon service has started.</p>
|
||
|
||
<h3 id="upstart">upstart</h3>
|
||
|
||
<pre><code>description &quot;Redis container&quot;
|
||
author &quot;Me&quot;
|
||
start on filesystem and started docker
|
||
stop on runlevel [!2345]
|
||
respawn
|
||
script
|
||
/usr/bin/docker start -a redis_server
|
||
end script
|
||
</code></pre>
|
||
|
||
<h3 id="systemd">systemd</h3>
|
||
|
||
<pre><code>[Unit]
|
||
Description=Redis container
|
||
Requires=docker.service
|
||
After=docker.service
|
||
|
||
[Service]
|
||
Restart=always
|
||
ExecStart=/usr/bin/docker start -a redis_server
|
||
ExecStop=/usr/bin/docker stop -t 2 redis_server
|
||
|
||
[Install]
|
||
WantedBy=local.target
|
||
</code></pre>
|
||
|
||
<p>If you need to pass options to the redis container (such as <code>--env</code>),
|
||
then you&rsquo;ll need to use <code>docker run</code> rather than <code>docker start</code>. This will
|
||
create a new container every time the service is started, which will be stopped
|
||
and removed when the service is stopped.</p>
|
||
|
||
<pre><code>[Service]
|
||
...
|
||
ExecStart=/usr/bin/docker run --env foo=bar --name redis_server redis
|
||
ExecStop=/usr/bin/docker stop -t 2 redis_server ; /usr/bin/docker rm -f redis_server
|
||
...
|
||
</code></pre>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Best practices for writing Dockerfiles</title>
|
||
<link>http://localhost/docker/articles/dockerfile_best-practices/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/articles/dockerfile_best-practices/</guid>
|
||
<description>
|
||
|
||
<h1 id="best-practices-for-writing-dockerfiles">Best practices for writing Dockerfiles</h1>
|
||
|
||
<h2 id="overview">Overview</h2>
|
||
|
||
<p>Docker can build images automatically by reading the instructions from a
|
||
<code>Dockerfile</code>, a text file that contains all the commands, in order, needed to
|
||
build a given image. <code>Dockerfile</code>s adhere to a specific format and use a
|
||
specific set of instructions. You can learn the basics on the
|
||
<a href="https://docs.docker.com/reference/builder/">Dockerfile Reference</a> page. If
|
||
you’re new to writing <code>Dockerfile</code>s, you should start there.</p>
|
||
|
||
<p>This document covers the best practices and methods recommended by Docker,
|
||
Inc. and the Docker community for creating easy-to-use, effective
|
||
<code>Dockerfile</code>s. We strongly suggest you follow these recommendations (in fact,
|
||
if you’re creating an Official Image, you <em>must</em> adhere to these practices).</p>
|
||
|
||
<p>You can see many of these practices and recommendations in action in the <a href="https://github.com/docker-library/buildpack-deps/blob/master/jessie/Dockerfile">buildpack-deps <code>Dockerfile</code></a>.</p>
|
||
|
||
<blockquote>
|
||
<p>Note: for more detailed explanations of any of the Dockerfile commands
|
||
mentioned here, visit the <a href="https://docs.docker.com/reference/builder/">Dockerfile Reference</a> page.</p>
|
||
</blockquote>
|
||
|
||
<h2 id="general-guidelines-and-recommendations">General guidelines and recommendations</h2>
|
||
|
||
<h3 id="containers-should-be-ephemeral">Containers should be ephemeral</h3>
|
||
|
||
<p>The container produced by the image your <code>Dockerfile</code> defines should be as
|
||
ephemeral as possible. By “ephemeral,” we mean that it can be stopped and
|
||
destroyed and a new one built and put in place with an absolute minimum of
|
||
set-up and configuration.</p>
|
||
|
||
<h3 id="use-a-dockerignore-file">Use a .dockerignore file</h3>
|
||
|
||
<p>In most cases, it&rsquo;s best to put each Dockerfile in an empty directory. Then,
|
||
add to that directory only the files needed for building the Dockerfile. To
|
||
increase the build&rsquo;s performance, you can exclude files and directories by
|
||
adding a <code>.dockerignore</code> file to that directory as well. This file supports
|
||
exclusion patterns similar to <code>.gitignore</code> files. For information on creating one,
|
||
see the <a href="../../reference/builder/#dockerignore-file">.dockerignore file</a>.</p>
|
||
|
||
<h3 id="avoid-installing-unnecessary-packages">Avoid installing unnecessary packages</h3>
|
||
|
||
<p>In order to reduce complexity, dependencies, file sizes, and build times, you
|
||
should avoid installing extra or unnecessary packages just because they
|
||
might be “nice to have.” For example, you don’t need to include a text editor
|
||
in a database image.</p>
|
||
|
||
<h3 id="run-only-one-process-per-container">Run only one process per container</h3>
|
||
|
||
<p>In almost all cases, you should only run a single process in a single
|
||
container. Decoupling applications into multiple containers makes it much
|
||
easier to scale horizontally and reuse containers. If that service depends on
|
||
another service, make use of <a href="https://docs.docker.com/userguide/dockerlinks/">container linking</a>.</p>
|
||
|
||
<h3 id="minimize-the-number-of-layers">Minimize the number of layers</h3>
|
||
|
||
<p>You need to find the balance between readability (and thus long-term
|
||
maintainability) of the <code>Dockerfile</code> and minimizing the number of layers it
|
||
uses. Be strategic and cautious about the number of layers you use.</p>
|
||
|
||
<h3 id="sort-multi-line-arguments">Sort multi-line arguments</h3>
|
||
|
||
<p>Whenever possible, ease later changes by sorting multi-line arguments
|
||
alphanumerically. This will help you avoid duplication of packages and make the
|
||
list much easier to update. This also makes PRs a lot easier to read and
|
||
review. Adding a space before a backslash (<code>\</code>) helps as well.</p>
|
||
|
||
<p>Here’s an example from the <a href="https://github.com/docker-library/buildpack-deps"><code>buildpack-deps</code> image</a>:</p>
|
||
|
||
<pre><code>RUN apt-get update &amp;&amp; apt-get install -y \
|
||
bzr \
|
||
cvs \
|
||
git \
|
||
mercurial \
|
||
subversion
|
||
</code></pre>
|
||
|
||
<h3 id="build-cache">Build cache</h3>
|
||
|
||
<p>During the process of building an image Docker will step through the
|
||
instructions in your <code>Dockerfile</code> executing each in the order specified.
|
||
As each instruction is examined Docker will look for an existing image in its
|
||
cache that it can reuse, rather than creating a new (duplicate) image.
|
||
If you do not want to use the cache at all you can use the <code>--no-cache=true</code>
|
||
option on the <code>docker build</code> command.</p>
|
||
|
||
<p>However, if you do let Docker use its cache then it is very important to
|
||
understand when it will, and will not, find a matching image. The basic rules
|
||
that Docker will follow are outlined below:</p>
|
||
|
||
<ul>
|
||
<li><p>Starting with a base image that is already in the cache, the next
|
||
instruction is compared against all child images derived from that base
|
||
image to see if one of them was built using the exact same instruction. If
|
||
not, the cache is invalidated.</p></li>
|
||
|
||
<li><p>In most cases simply comparing the instruction in the <code>Dockerfile</code> with one
|
||
of the child images is sufficient. However, certain instructions require
|
||
a little more examination and explanation.</p></li>
|
||
|
||
<li><p>In the case of the <code>ADD</code> and <code>COPY</code> instructions, the contents of the file(s)
|
||
being put into the image are examined. Specifically, a checksum is done
|
||
of the file(s) and then that checksum is used during the cache lookup.
|
||
If anything has changed in the file(s), including its metadata,
|
||
then the cache is invalidated.</p></li>
|
||
|
||
<li><p>Aside from the <code>ADD</code> and <code>COPY</code> commands cache checking will not look at the
|
||
files in the container to determine a cache match. For example, when processing
|
||
a <code>RUN apt-get -y update</code> command the files updated in the container
|
||
will not be examined to determine if a cache hit exists. In that case just
|
||
the command string itself will be used to find a match.</p></li>
|
||
</ul>
|
||
|
||
<p>Once the cache is invalidated, all subsequent <code>Dockerfile</code> commands will
|
||
generate new images and the cache will not be used.</p>
|
||
|
||
<h2 id="the-dockerfile-instructions">The Dockerfile instructions</h2>
|
||
|
||
<p>Below you&rsquo;ll find recommendations for the best way to write the
|
||
various instructions available for use in a <code>Dockerfile</code>.</p>
|
||
|
||
<h3 id="from-https-docs-docker-com-reference-builder-from"><a href="https://docs.docker.com/reference/builder/#from"><code>FROM</code></a></h3>
|
||
|
||
<p>Whenever possible, use current Official Repositories as the basis for your
|
||
image. We recommend the <a href="https://registry.hub.docker.com/_/debian/">Debian image</a>
|
||
since it’s very tightly controlled and kept extremely minimal (currently under
|
||
100 mb), while still being a full distribution.</p>
|
||
|
||
<h3 id="run-https-docs-docker-com-reference-builder-run"><a href="https://docs.docker.com/reference/builder/#run"><code>RUN</code></a></h3>
|
||
|
||
<p>As always, to make your <code>Dockerfile</code> more readable, understandable, and
|
||
maintainable, put long or complex <code>RUN</code> statements on multiple lines separated
|
||
with backslashes.</p>
|
||
|
||
<p>Probably the most common use-case for <code>RUN</code> is an application of <code>apt-get</code>.
|
||
When using <code>apt-get</code>, here are a few things to keep in mind:</p>
|
||
|
||
<ul>
|
||
<li><p>Don’t do <code>RUN apt-get update</code> on a single line. This will cause
|
||
caching issues if the referenced archive gets updated, which will make your
|
||
subsequent <code>apt-get install</code> fail without comment.</p></li>
|
||
|
||
<li><p>Avoid <code>RUN apt-get upgrade</code> or <code>dist-upgrade</code>, since many of the “essential”
|
||
packages from the base images will fail to upgrade inside an unprivileged
|
||
container. If a base package is out of date, you should contact its
|
||
maintainers. If you know there’s a particular package, <code>foo</code>, that needs to be
|
||
updated, use <code>apt-get install -y foo</code> and it will update automatically.</p></li>
|
||
|
||
<li><p>Do write instructions like:</p>
|
||
|
||
<p>RUN apt-get update &amp;&amp; apt-get install -y package-bar package-foo package-baz</p></li>
|
||
</ul>
|
||
|
||
<p>Writing the instruction this way not only makes it easier to read
|
||
and maintain, but also, by including <code>apt-get update</code>, ensures that the cache
|
||
will naturally be busted and the latest versions will be installed with no
|
||
further coding or manual intervention required.</p>
|
||
|
||
<ul>
|
||
<li>Further natural cache-busting can be realized by version-pinning packages
|
||
(e.g., <code>package-foo=1.3.*</code>). This will force retrieval of that version
|
||
regardless of what’s in the cache.
|
||
Writing your <code>apt-get</code> code this way will greatly ease maintenance and reduce
|
||
failures due to unanticipated changes in required packages.</li>
|
||
</ul>
|
||
|
||
<h4 id="example">Example</h4>
|
||
|
||
<p>Below is a well-formed <code>RUN</code> instruction that demonstrates the above
|
||
recommendations. Note that the last package, <code>s3cmd</code>, specifies a version
|
||
<code>1.1.0*</code>. If the image previously used an older version, specifying the new one
|
||
will cause a cache bust of <code>apt-get update</code> and ensure the installation of
|
||
the new version (which in this case had a new, required feature).</p>
|
||
|
||
<pre><code>RUN apt-get update &amp;&amp; apt-get install -y \
|
||
aufs-tools \
|
||
automake \
|
||
btrfs-tools \
|
||
build-essential \
|
||
curl \
|
||
dpkg-sig \
|
||
git \
|
||
iptables \
|
||
libapparmor-dev \
|
||
libcap-dev \
|
||
libsqlite3-dev \
|
||
lxc=1.0* \
|
||
mercurial \
|
||
parallel \
|
||
reprepro \
|
||
ruby1.9.1 \
|
||
ruby1.9.1-dev \
|
||
s3cmd=1.1.0*
|
||
</code></pre>
|
||
|
||
<p>Writing the instruction this way also helps you avoid potential duplication of
|
||
a given package because it is much easier to read than an instruction like:</p>
|
||
|
||
<pre><code>RUN apt-get install -y package-foo &amp;&amp; apt-get install -y package-bar
|
||
</code></pre>
|
||
|
||
<h3 id="cmd-https-docs-docker-com-reference-builder-cmd"><a href="https://docs.docker.com/reference/builder/#cmd"><code>CMD</code></a></h3>
|
||
|
||
<p>The <code>CMD</code> instruction should be used to run the software contained by your
|
||
image, along with any arguments. <code>CMD</code> should almost always be used in the
|
||
form of <code>CMD [“executable”, “param1”, “param2”…]</code>. Thus, if the image is for a
|
||
service (Apache, Rails, etc.), you would run something like
|
||
<code>CMD [&quot;apache2&quot;,&quot;-DFOREGROUND&quot;]</code>. Indeed, this form of the instruction is
|
||
recommended for any service-based image.</p>
|
||
|
||
<p>In most other cases, <code>CMD</code> should be given an interactive shell (bash, python,
|
||
perl, etc), for example, <code>CMD [&quot;perl&quot;, &quot;-de0&quot;]</code>, <code>CMD [&quot;python&quot;]</code>, or
|
||
<code>CMD [“php”, “-a”]</code>. Using this form means that when you execute something like
|
||
<code>docker run -it python</code>, you’ll get dropped into a usable shell, ready to go.
|
||
<code>CMD</code> should rarely be used in the manner of <code>CMD [“param”, “param”]</code> in
|
||
conjunction with <a href="https://docs.docker.com/reference/builder/#entrypoint"><code>ENTRYPOINT</code></a>, unless
|
||
you and your expected users are already quite familiar with how <code>ENTRYPOINT</code>
|
||
works.</p>
|
||
|
||
<h3 id="expose-https-docs-docker-com-reference-builder-expose"><a href="https://docs.docker.com/reference/builder/#expose"><code>EXPOSE</code></a></h3>
|
||
|
||
<p>The <code>EXPOSE</code> instruction indicates the ports on which a container will listen
|
||
for connections. Consequently, you should use the common, traditional port for
|
||
your application. For example, an image containing the Apache web server would
|
||
use <code>EXPOSE 80</code>, while an image containing MongoDB would use <code>EXPOSE 27017</code> and
|
||
so on.</p>
|
||
|
||
<p>For external access, your users can execute <code>docker run</code> with a flag indicating
|
||
how to map the specified port to the port of their choice.
|
||
For container linking, Docker provides environment variables for the path from
|
||
the recipient container back to the source (ie, <code>MYSQL_PORT_3306_TCP</code>).</p>
|
||
|
||
<h3 id="env-https-docs-docker-com-reference-builder-env"><a href="https://docs.docker.com/reference/builder/#env"><code>ENV</code></a></h3>
|
||
|
||
<p>In order to make new software easier to run, you can use <code>ENV</code> to update the
|
||
<code>PATH</code> environment variable for the software your container installs. For
|
||
example, <code>ENV PATH /usr/local/nginx/bin:$PATH</code> will ensure that <code>CMD [“nginx”]</code>
|
||
just works.</p>
|
||
|
||
<p>The <code>ENV</code> instruction is also useful for providing required environment
|
||
variables specific to services you wish to containerize, such as Postgres’s
|
||
<code>PGDATA</code>.</p>
|
||
|
||
<p>Lastly, <code>ENV</code> can also be used to set commonly used version numbers so that
|
||
version bumps are easier to maintain, as seen in the following example:</p>
|
||
|
||
<pre><code>ENV PG_MAJOR 9.3
|
||
ENV PG_VERSION 9.3.4
|
||
RUN curl -SL http://example.com/postgres-$PG_VERSION.tar.xz | tar -xJC /usr/src/postgress &amp;&amp; …
|
||
ENV PATH /usr/local/postgres-$PG_MAJOR/bin:$PATH
|
||
</code></pre>
|
||
|
||
<p>Similar to having constant variables in a program (as opposed to hard-coding
|
||
values), this approach lets you change a single <code>ENV</code> instruction to
|
||
auto-magically bump the version of the software in your container.</p>
|
||
|
||
<h3 id="add-https-docs-docker-com-reference-builder-add-or-copy-https-docs-docker-com-reference-builder-copy"><a href="https://docs.docker.com/reference/builder/#add"><code>ADD</code></a> or <a href="https://docs.docker.com/reference/builder/#copy"><code>COPY</code></a></h3>
|
||
|
||
<p>Although <code>ADD</code> and <code>COPY</code> are functionally similar, generally speaking, <code>COPY</code>
|
||
is preferred. That’s because it’s more transparent than <code>ADD</code>. <code>COPY</code> only
|
||
supports the basic copying of local files into the container, while <code>ADD</code> has
|
||
some features (like local-only tar extraction and remote URL support) that are
|
||
not immediately obvious. Consequently, the best use for <code>ADD</code> is local tar file
|
||
auto-extraction into the image, as in <code>ADD rootfs.tar.xz /</code>.</p>
|
||
|
||
<p>If you have multiple <code>Dockerfile</code> steps that use different files from your
|
||
context, <code>COPY</code> them individually, rather than all at once. This will ensure that
|
||
each step&rsquo;s build cache is only invalidated (forcing the step to be re-run) if the
|
||
specifically required files change.</p>
|
||
|
||
<p>For example:</p>
|
||
|
||
<pre><code>COPY requirements.txt /tmp/
|
||
RUN pip install /tmp/requirements.txt
|
||
COPY . /tmp/
|
||
</code></pre>
|
||
|
||
<p>Results in fewer cache invalidations for the <code>RUN</code> step, than if you put the
|
||
<code>COPY . /tmp/</code> before it.</p>
|
||
|
||
<p>Because image size matters, using <code>ADD</code> to fetch packages from remote URLs is
|
||
strongly discouraged; you should use <code>curl</code> or <code>wget</code> instead. That way you can
|
||
delete the files you no longer need after they&rsquo;ve been extracted and you won&rsquo;t
|
||
have to add another layer in your image. For example, you should avoid doing
|
||
things like:</p>
|
||
|
||
<pre><code>ADD http://example.com/big.tar.xz /usr/src/things/
|
||
RUN tar -xJf /usr/src/things/big.tar.xz -C /usr/src/things
|
||
RUN make -C /usr/src/things all
|
||
</code></pre>
|
||
|
||
<p>And instead, do something like:</p>
|
||
|
||
<pre><code>RUN mkdir -p /usr/src/things \
|
||
&amp;&amp; curl -SL http://example.com/big.tar.gz \
|
||
| tar -xJC /usr/src/things \
|
||
&amp;&amp; make -C /usr/src/things all
|
||
</code></pre>
|
||
|
||
<p>For other items (files, directories) that do not require <code>ADD</code>’s tar
|
||
auto-extraction capability, you should always use <code>COPY</code>.</p>
|
||
|
||
<h3 id="entrypoint-https-docs-docker-com-reference-builder-entrypoint"><a href="https://docs.docker.com/reference/builder/#entrypoint"><code>ENTRYPOINT</code></a></h3>
|
||
|
||
<p>The best use for <code>ENTRYPOINT</code> is to set the image&rsquo;s main command, allowing that
|
||
image to be run as though it was that command (and then use <code>CMD</code> as the
|
||
default flags).</p>
|
||
|
||
<p>Let&rsquo;s start with an example of an image for the command line tool <code>s3cmd</code>:</p>
|
||
|
||
<pre><code>ENTRYPOINT [&quot;s3cmd&quot;]
|
||
CMD [&quot;--help&quot;]
|
||
</code></pre>
|
||
|
||
<p>Now the image can be run like this to show the command&rsquo;s help:</p>
|
||
|
||
<pre><code>$ docker run s3cmd
|
||
</code></pre>
|
||
|
||
<p>Or using the right parameters to execute a command:</p>
|
||
|
||
<pre><code>$ docker run s3cmd ls s3://mybucket
|
||
</code></pre>
|
||
|
||
<p>This is useful because the image name can double as a reference to the binary as
|
||
shown in the command above.</p>
|
||
|
||
<p>The <code>ENTRYPOINT</code> instruction can also be used in combination with a helper
|
||
script, allowing it to function in a similar way to the command above, even
|
||
when starting the tool may require more than one step.</p>
|
||
|
||
<p>For example, the <a href="https://registry.hub.docker.com/_/postgres/">Postgres Official Image</a>
|
||
uses the following script as its <code>ENTRYPOINT</code>:</p>
|
||
|
||
<pre><code class="language-bash">#!/bin/bash
|
||
set -e
|
||
|
||
if [ &quot;$1&quot; = 'postgres' ]; then
|
||
chown -R postgres &quot;$PGDATA&quot;
|
||
|
||
if [ -z &quot;$(ls -A &quot;$PGDATA&quot;)&quot; ]; then
|
||
gosu postgres initdb
|
||
fi
|
||
|
||
exec gosu postgres &quot;$@&quot;
|
||
fi
|
||
|
||
exec &quot;$@&quot;
|
||
</code></pre>
|
||
|
||
<blockquote>
|
||
<p><strong>Note</strong>:
|
||
This script uses <a href="http://wiki.bash-hackers.org/commands/builtin/exec">the <code>exec</code> Bash command</a>
|
||
so that the final running application becomes the container&rsquo;s PID 1. This allows
|
||
the application to receive any Unix signals sent to the container.
|
||
See the <a href="https://docs.docker.com/reference/builder/#ENTRYPOINT"><code>ENTRYPOINT</code></a>
|
||
help for more details.</p>
|
||
</blockquote>
|
||
|
||
<p>The helper script is copied into the container and run via <code>ENTRYPOINT</code> on
|
||
container start:</p>
|
||
|
||
<pre><code>COPY ./docker-entrypoint.sh /
|
||
ENTRYPOINT [&quot;/docker-entrypoint.sh&quot;]
|
||
</code></pre>
|
||
|
||
<p>This script allows the user to interact with Postgres in several ways.</p>
|
||
|
||
<p>It can simply start Postgres:</p>
|
||
|
||
<pre><code>$ docker run postgres
|
||
</code></pre>
|
||
|
||
<p>Or, it can be used to run Postgres and pass parameters to the server:</p>
|
||
|
||
<pre><code>$ docker run postgres postgres --help
|
||
</code></pre>
|
||
|
||
<p>Lastly, it could also be used to start a totally different tool, such Bash:</p>
|
||
|
||
<pre><code>$ docker run --rm -it postgres bash
|
||
</code></pre>
|
||
|
||
<h3 id="volume-https-docs-docker-com-reference-builder-volume"><a href="https://docs.docker.com/reference/builder/#volume"><code>VOLUME</code></a></h3>
|
||
|
||
<p>The <code>VOLUME</code> instruction should be used to expose any database storage area,
|
||
configuration storage, or files/folders created by your docker container. You
|
||
are strongly encouraged to use <code>VOLUME</code> for any mutable and/or user-serviceable
|
||
parts of your image.</p>
|
||
|
||
<h3 id="user-https-docs-docker-com-reference-builder-user"><a href="https://docs.docker.com/reference/builder/#user"><code>USER</code></a></h3>
|
||
|
||
<p>If a service can run without privileges, use <code>USER</code> to change to a non-root
|
||
user. Start by creating the user and group in the <code>Dockerfile</code> with something
|
||
like <code>RUN groupadd -r postgres &amp;&amp; useradd -r -g postgres postgres</code>.</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong> Users and groups in an image get a non-deterministic
|
||
UID/GID in that the “next” UID/GID gets assigned regardless of image
|
||
rebuilds. So, if it’s critical, you should assign an explicit UID/GID.</p>
|
||
</blockquote>
|
||
|
||
<p>You should avoid installing or using <code>sudo</code> since it has unpredictable TTY and
|
||
signal-forwarding behavior that can cause more problems than it solves. If
|
||
you absolutely need functionality similar to <code>sudo</code> (e.g., initializing the
|
||
daemon as root but running it as non-root), you may be able to use
|
||
<a href="https://github.com/tianon/gosu">“gosu”</a>.</p>
|
||
|
||
<p>Lastly, to reduce layers and complexity, avoid switching <code>USER</code> back
|
||
and forth frequently.</p>
|
||
|
||
<h3 id="workdir-https-docs-docker-com-reference-builder-workdir"><a href="https://docs.docker.com/reference/builder/#workdir"><code>WORKDIR</code></a></h3>
|
||
|
||
<p>For clarity and reliability, you should always use absolute paths for your
|
||
<code>WORKDIR</code>. Also, you should use <code>WORKDIR</code> instead of proliferating
|
||
instructions like <code>RUN cd … &amp;&amp; do-something</code>, which are hard to read,
|
||
troubleshoot, and maintain.</p>
|
||
|
||
<h3 id="onbuild-https-docs-docker-com-reference-builder-onbuild"><a href="https://docs.docker.com/reference/builder/#onbuild"><code>ONBUILD</code></a></h3>
|
||
|
||
<p>An <code>ONBUILD</code> command executes after the current <code>Dockerfile</code> build completes.
|
||
<code>ONBUILD</code> executes in any child image derived <code>FROM</code> the current image. Think
|
||
of the <code>ONBUILD</code> command as an instruction the parent <code>Dockerfile</code> gives
|
||
to the child <code>Dockerfile</code>.</p>
|
||
|
||
<p>A Docker build executes <code>ONBUILD</code> commands before any command in a child
|
||
<code>Dockerfile</code>.</p>
|
||
|
||
<p><code>ONBUILD</code> is useful for images that are going to be built <code>FROM</code> a given
|
||
image. For example, you would use <code>ONBUILD</code> for a language stack image that
|
||
builds arbitrary user software written in that language within the
|
||
<code>Dockerfile</code>, as you can see in <a href="https://github.com/docker-library/ruby/blob/master/2.1/onbuild/Dockerfile">Ruby’s <code>ONBUILD</code> variants</a>.</p>
|
||
|
||
<p>Images built from <code>ONBUILD</code> should get a separate tag, for example:
|
||
<code>ruby:1.9-onbuild</code> or <code>ruby:2.0-onbuild</code>.</p>
|
||
|
||
<p>Be careful when putting <code>ADD</code> or <code>COPY</code> in <code>ONBUILD</code>. The “onbuild” image will
|
||
fail catastrophically if the new build&rsquo;s context is missing the resource being
|
||
added. Adding a separate tag, as recommended above, will help mitigate this by
|
||
allowing the <code>Dockerfile</code> author to make a choice.</p>
|
||
|
||
<h2 id="examples-for-official-repositories">Examples for Official Repositories</h2>
|
||
|
||
<p>These Official Repositories have exemplary <code>Dockerfile</code>s:</p>
|
||
|
||
<ul>
|
||
<li><a href="https://registry.hub.docker.com/_/golang/">Go</a></li>
|
||
<li><a href="https://registry.hub.docker.com/_/perl/">Perl</a></li>
|
||
<li><a href="https://registry.hub.docker.com/_/hylang/">Hy</a></li>
|
||
<li><a href="https://registry.hub.docker.com/_/rails">Rails</a></li>
|
||
</ul>
|
||
|
||
<h2 id="additional-resources">Additional resources:</h2>
|
||
|
||
<ul>
|
||
<li><a href="https://docs.docker.com/reference/builder/#onbuild">Dockerfile Reference</a></li>
|
||
<li><a href="https://docs.docker.com/articles/baseimages/">More about Base Images</a></li>
|
||
<li><a href="https://docs.docker.com/docker-hub/builds/">More about Automated Builds</a></li>
|
||
<li><a href="https://docs.docker.com/docker-hub/official_repos/">Guidelines for Creating Official
|
||
Repositories</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Coding style checklist</title>
|
||
<link>http://localhost/docker/project/coding-style/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/project/coding-style/</guid>
|
||
<description>
|
||
|
||
<h1 id="coding-style-checklist">Coding style checklist</h1>
|
||
|
||
<p>This checklist summarizes the material you experienced working through <a href="http://localhost/project/make-a-contribution">make a
|
||
code contribution</a> and <a href="http://localhost/project/advanced-contributing">advanced
|
||
contributing</a>. The checklist applies to both
|
||
program code and documentation code.</p>
|
||
|
||
<h2 id="change-and-commit-code">Change and commit code</h2>
|
||
|
||
<ul>
|
||
<li><p>Fork the <code>docker/docker</code> repository.</p></li>
|
||
|
||
<li><p>Make changes on your fork in a feature branch. Name your branch <code>XXXX-something</code>
|
||
where <code>XXXX</code> is the issue number you are working on.</p></li>
|
||
|
||
<li><p>Run <code>gofmt -s -w file.go</code> on each changed file before
|
||
committing your changes. Most editors have plug-ins that do this automatically.</p></li>
|
||
|
||
<li><p>Update the documentation when creating or modifying features.</p></li>
|
||
|
||
<li><p>Commits that fix or close an issue should reference them in the commit message
|
||
<code>Closes #XXXX</code> or <code>Fixes #XXXX</code>. Mentions help by automatically closing the
|
||
issue on a merge.</p></li>
|
||
|
||
<li><p>After every commit, run the test suite and ensure it is passing.</p></li>
|
||
|
||
<li><p>Sync and rebase frequently as you code to keep up with <code>docker</code> master.</p></li>
|
||
|
||
<li><p>Set your <code>git</code> signature and make sure you sign each commit.</p></li>
|
||
|
||
<li><p>Do not add yourself to the <code>AUTHORS</code> file. This file is autogenerated from the
|
||
Git history.</p></li>
|
||
</ul>
|
||
|
||
<h2 id="tests-and-testing">Tests and testing</h2>
|
||
|
||
<ul>
|
||
<li><p>Submit unit tests for your changes.</p></li>
|
||
|
||
<li><p>Make use of the builtin Go test framework built.</p></li>
|
||
|
||
<li><p>Use existing Docker test files (<code>name_test.go</code>) for inspiration.</p></li>
|
||
|
||
<li><p>Run <a href="../test-and-docs" target="_blank">the full test suite</a> on your
|
||
branch before submitting a pull request.</p></li>
|
||
|
||
<li><p>Run <code>make docs</code> to build the documentation and then check it locally.</p></li>
|
||
|
||
<li><p>Use an <a href="http://www.hemingwayapp.com" target="_blank">online grammar
|
||
checker</a> or similar to test you documentation changes for clarity,
|
||
concision, and correctness.</p></li>
|
||
</ul>
|
||
|
||
<h2 id="pull-requests">Pull requests</h2>
|
||
|
||
<ul>
|
||
<li><p>Sync and cleanly rebase on top of Docker&rsquo;s <code>master</code> without multiple branches
|
||
mixed into the PR.</p></li>
|
||
|
||
<li><p>Before the pull request, squash your commits into logical units of work using
|
||
<code>git rebase -i</code> and <code>git push -f</code>.</p></li>
|
||
|
||
<li><p>Include documentation changes in the same commit so that a revert would
|
||
remove all traces of the feature or fix.</p></li>
|
||
|
||
<li><p>Reference each issue in your pull request description (<code>#XXXX</code>)</p></li>
|
||
</ul>
|
||
|
||
<h2 id="respond-to-pull-requests-reviews">Respond to pull requests reviews</h2>
|
||
|
||
<ul>
|
||
<li><p>Docker maintainers use LGTM (<strong>l</strong>ooks-<strong>g</strong>ood-<strong>t</strong>o-<strong>m</strong>e) in PR comments
|
||
to indicate acceptance.</p></li>
|
||
|
||
<li><p>Code review comments may be added to your pull request. Discuss, then make
|
||
the suggested modifications and push additional commits to your feature
|
||
branch.</p></li>
|
||
|
||
<li><p>Incorporate changes on your feature branch and push to your fork. This
|
||
automatically updates your open pull request.</p></li>
|
||
|
||
<li><p>Post a comment after pushing to alert reviewers to PR changes; pushing a
|
||
change does not send notifications.</p></li>
|
||
|
||
<li><p>A change requires LGTMs from an absolute majority maintainers of an
|
||
affected component. For example, if you change <code>docs/</code> and <code>registry/</code> code,
|
||
an absolute majority of the <code>docs/</code> and the <code>registry/</code> maintainers must
|
||
approve your PR.</p></li>
|
||
</ul>
|
||
|
||
<h2 id="merges-after-pull-requests">Merges after pull requests</h2>
|
||
|
||
<ul>
|
||
<li><p>After a merge, <a href="https://master.dockerproject.org/">a master build</a> is
|
||
available almost immediately.</p></li>
|
||
|
||
<li><p>If you made a documentation change, you can see it at
|
||
<a href="http://docs.master.dockerproject.org/">docs.master.dockerproject.org</a>.</p></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Configure Git for contributing</title>
|
||
<link>http://localhost/docker/project/set-up-git/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/project/set-up-git/</guid>
|
||
<description>
|
||
|
||
<h1 id="configure-git-for-contributing">Configure Git for contributing</h1>
|
||
|
||
<p>Work through this page to configure Git and a repository you&rsquo;ll use throughout
|
||
the Contributor Guide. The work you do further in the guide, depends on the work
|
||
you do here.</p>
|
||
|
||
<h2 id="fork-and-clone-the-docker-code">Fork and clone the Docker code</h2>
|
||
|
||
<p>Before contributing, you first fork the Docker code repository. A fork copies
|
||
a repository at a particular point in time. GitHub tracks for you where a fork
|
||
originates.</p>
|
||
|
||
<p>As you make contributions, you change your fork&rsquo;s code. When you are ready,
|
||
you make a pull request back to the original Docker repository. If you aren&rsquo;t
|
||
familiar with this workflow, don&rsquo;t worry, this guide walks you through all the
|
||
steps.</p>
|
||
|
||
<p>To fork and clone Docker:</p>
|
||
|
||
<ol>
|
||
<li><p>Open a browser and log into GitHub with your account.</p></li>
|
||
|
||
<li><p>Go to the <a href="https://github.com/docker/docker"
|
||
target="_blank">docker/docker repository</a>.</p></li>
|
||
|
||
<li><p>Click the &ldquo;Fork&rdquo; button in the upper right corner of the GitHub interface.</p>
|
||
|
||
<p><img src="http://localhost/project/images/fork_docker.png" alt="Branch Signature" />
|
||
</p>
|
||
|
||
<p>GitHub forks the repository to your GitHub account. The original
|
||
<code>docker/docker</code> repository becomes a new fork <code>YOUR_ACCOUNT/docker</code> under
|
||
your account.</p></li>
|
||
|
||
<li><p>Copy your fork&rsquo;s clone URL from GitHub.</p>
|
||
|
||
<p>GitHub allows you to use HTTPS or SSH protocols for clones. You can use the
|
||
<code>git</code> command line or clients like Subversion to clone a repository.</p>
|
||
|
||
<p><img src="http://localhost/project/images/copy_url.png" alt="Copy clone URL" />
|
||
</p>
|
||
|
||
<p>This guide assume you are using the HTTPS protocol and the <code>git</code> command
|
||
line. If you are comfortable with SSH and some other tool, feel free to use
|
||
that instead. You&rsquo;ll need to convert what you see in the guide to what is
|
||
appropriate to your tool.</p></li>
|
||
|
||
<li><p>Open a terminal window on your local host and change to your home directory.</p>
|
||
|
||
<pre><code>$ cd ~
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<p>In Windows, you&rsquo;ll work in your Boot2Docker window instead of Powershell or
|
||
a <code>cmd</code> window.</p>
|
||
|
||
<ol>
|
||
<li><p>Create a <code>repos</code> directory.</p>
|
||
|
||
<pre><code>$ mkdir repos
|
||
</code></pre></li>
|
||
|
||
<li><p>Change into your <code>repos</code> directory.</p>
|
||
|
||
<pre><code>$ cd repos
|
||
</code></pre></li>
|
||
|
||
<li><p>Clone the fork to your local host into a repository called <code>docker-fork</code>.</p>
|
||
|
||
<pre><code>$ git clone https://github.com/moxiegirl/docker.git docker-fork
|
||
</code></pre>
|
||
|
||
<p>Naming your local repo <code>docker-fork</code> should help make these instructions
|
||
easier to follow; experienced coders don&rsquo;t typically change the name.</p></li>
|
||
|
||
<li><p>Change directory into your new <code>docker-fork</code> directory.</p>
|
||
|
||
<pre><code>$ cd docker-fork
|
||
</code></pre>
|
||
|
||
<p>Take a moment to familiarize yourself with the repository&rsquo;s contents. List
|
||
the contents.</p></li>
|
||
</ol>
|
||
|
||
<h2 id="set-your-signature-and-an-upstream-remote">Set your signature and an upstream remote</h2>
|
||
|
||
<p>When you contribute to Docker, you must certify you agree with the
|
||
<a href="http://developercertificate.org/" target="_blank">Developer Certificate of Origin</a>.
|
||
You indicate your agreement by signing your <code>git</code> commits like this:</p>
|
||
|
||
<pre><code>Signed-off-by: Pat Smith &lt;pat.smith@email.com&gt;
|
||
</code></pre>
|
||
|
||
<p>To create a signature, you configure your username and email address in Git.
|
||
You can set these globally or locally on just your <code>docker-fork</code> repository.
|
||
You must sign with your real name. We don&rsquo;t accept anonymous contributions or
|
||
contributions through pseudonyms.</p>
|
||
|
||
<p>As you change code in your fork, you&rsquo;ll want to keep it in sync with the changes
|
||
others make in the <code>docker/docker</code> repository. To make syncing easier, you&rsquo;ll
|
||
also add a <em>remote</em> called <code>upstream</code> that points to <code>docker/docker</code>. A remote
|
||
is just another project version hosted on the internet or network.</p>
|
||
|
||
<p>To configure your username, email, and add a remote:</p>
|
||
|
||
<ol>
|
||
<li><p>Change to the root of your <code>docker-fork</code> repository.</p>
|
||
|
||
<pre><code>$ cd docker-fork
|
||
</code></pre></li>
|
||
|
||
<li><p>Set your <code>user.name</code> for the repository.</p>
|
||
|
||
<pre><code>$ git config --local user.name &quot;FirstName LastName&quot;
|
||
</code></pre></li>
|
||
|
||
<li><p>Set your <code>user.email</code> for the repository.</p>
|
||
|
||
<pre><code>$ git config --local user.email &quot;emailname@mycompany.com&quot;
|
||
</code></pre></li>
|
||
|
||
<li><p>Set your local repo to track changes upstream, on the <code>docker</code> repository.</p>
|
||
|
||
<pre><code>$ git remote add upstream https://github.com/docker/docker.git
|
||
</code></pre></li>
|
||
|
||
<li><p>Check the result in your <code>git</code> configuration.</p>
|
||
|
||
<pre><code>$ git config --local -l
|
||
core.repositoryformatversion=0
|
||
core.filemode=true
|
||
core.bare=false
|
||
core.logallrefupdates=true
|
||
remote.origin.url=https://github.com/moxiegirl/docker.git
|
||
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
|
||
branch.master.remote=origin
|
||
branch.master.merge=refs/heads/master
|
||
user.name=Mary Anthony
|
||
user.email=mary@docker.com
|
||
remote.upstream.url=https://github.com/docker/docker.git
|
||
remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/*
|
||
</code></pre>
|
||
|
||
<p>To list just the remotes use:</p>
|
||
|
||
<pre><code>$ git remote -v
|
||
origin https://github.com/moxiegirl/docker.git (fetch)
|
||
origin https://github.com/moxiegirl/docker.git (push)
|
||
upstream https://github.com/docker/docker.git (fetch)
|
||
upstream https://github.com/docker/docker.git (push)
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<h2 id="create-and-push-a-branch">Create and push a branch</h2>
|
||
|
||
<p>As you change code in your fork, make your changes on a repository branch.
|
||
The branch name should reflect what you are working on. In this section, you
|
||
create a branch, make a change, and push it up to your fork.</p>
|
||
|
||
<p>This branch is just for testing your config for this guide. The changes are part
|
||
of a dry run, so the branch name will be dry-run-test. To create and push
|
||
the branch to your fork on GitHub:</p>
|
||
|
||
<ol>
|
||
<li><p>Open a terminal and go to the root of your <code>docker-fork</code>.</p>
|
||
|
||
<pre><code>$ cd docker-fork
|
||
</code></pre></li>
|
||
|
||
<li><p>Create a <code>dry-run-test</code> branch.</p>
|
||
|
||
<pre><code>$ git checkout -b dry-run-test
|
||
</code></pre>
|
||
|
||
<p>This command creates the branch and switches the repository to it.</p></li>
|
||
|
||
<li><p>Verify you are in your new branch.</p>
|
||
|
||
<pre><code>$ git branch
|
||
* dry-run-test
|
||
master
|
||
</code></pre>
|
||
|
||
<p>The current branch has an * (asterisk) marker. So, these results shows you
|
||
are on the right branch.</p></li>
|
||
|
||
<li><p>Create a <code>TEST.md</code> file in the repository&rsquo;s root.</p>
|
||
|
||
<pre><code>$ touch TEST.md
|
||
</code></pre></li>
|
||
|
||
<li><p>Edit the file and add your email and location.</p>
|
||
|
||
<p><img src="http://localhost/project/images/contributor-edit.png" alt="Add your information" />
|
||
</p>
|
||
|
||
<p>You can use any text editor you are comfortable with.</p></li>
|
||
|
||
<li><p>Save and close the file.</p></li>
|
||
|
||
<li><p>Check the status of your branch.</p>
|
||
|
||
<pre><code>$ git status
|
||
On branch dry-run-test
|
||
Untracked files:
|
||
(use &quot;git add &lt;file&gt;...&quot; to include in what will be committed)
|
||
|
||
|
||
TEST.md
|
||
|
||
|
||
nothing added to commit but untracked files present (use &quot;git add&quot; to track)
|
||
</code></pre>
|
||
|
||
<p>You&rsquo;ve only changed the one file. It is untracked so far by git.</p></li>
|
||
|
||
<li><p>Add your file.</p>
|
||
|
||
<pre><code>$ git add TEST.md
|
||
</code></pre>
|
||
|
||
<p>That is the only <em>staged</em> file. Stage is fancy word for work that Git is
|
||
tracking.</p></li>
|
||
|
||
<li><p>Sign and commit your change.</p>
|
||
|
||
<pre><code>$ git commit -s -m &quot;Making a dry run test.&quot;
|
||
[dry-run-test 6e728fb] Making a dry run test
|
||
1 file changed, 1 insertion(+)
|
||
create mode 100644 TEST.md
|
||
</code></pre>
|
||
|
||
<p>Commit messages should have a short summary sentence of no more than 50
|
||
characters. Optionally, you can also include a more detailed explanation
|
||
after the summary. Separate the summary from any explanation with an empty
|
||
line.</p></li>
|
||
|
||
<li><p>Push your changes to GitHub.</p>
|
||
|
||
<pre><code>$ git push --set-upstream origin dry-run-test
|
||
Username for 'https://github.com': moxiegirl
|
||
Password for 'https://moxiegirl@github.com':
|
||
</code></pre>
|
||
|
||
<p>Git prompts you for your GitHub username and password. Then, the command
|
||
returns a result.</p>
|
||
|
||
<pre><code>Counting objects: 13, done.
|
||
Compressing objects: 100% (2/2), done.
|
||
Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done.
|
||
Total 3 (delta 1), reused 0 (delta 0)
|
||
To https://github.com/moxiegirl/docker.git
|
||
* [new branch] dry-run-test -&gt; dry-run-test
|
||
Branch dry-run-test set up to track remote branch dry-run-test from origin.
|
||
</code></pre></li>
|
||
|
||
<li><p>Open your browser to Github.</p></li>
|
||
|
||
<li><p>Navigate to your Docker fork.</p></li>
|
||
|
||
<li><p>Make sure the <code>dry-run-test</code> branch exists, that it has your commit, and the
|
||
commit is signed.</p>
|
||
|
||
<p><img src="http://localhost/project/images/branch-sig.png" alt="Branch Signature" />
|
||
</p></li>
|
||
</ol>
|
||
|
||
<h2 id="where-to-go-next">Where to go next</h2>
|
||
|
||
<p>Congratulations, you have finished configuring both your local host environment
|
||
and Git for contributing. In the next section you&rsquo;ll <a href="http://localhost/project/set-up-dev-env/">learn how to set up and
|
||
work in a Docker development container</a>.</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Configuring and running Docker</title>
|
||
<link>http://localhost/docker/articles/configuring/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/docker/articles/configuring/</guid>
|
||
<description>
|
||
|
||
<h1 id="configuring-and-running-docker-on-various-distributions">Configuring and running Docker on various distributions</h1>
|
||
|
||
<p>After successfully installing Docker, the <code>docker</code> daemon runs with its default
|
||
configuration.</p>
|
||
|
||
<p>In a production environment, system administrators typically configure the
|
||
<code>docker</code> daemon to start and stop according to an organization&rsquo;s requirements. In most
|
||
cases, the system administrator configures a process manager such as <code>SysVinit</code>, <code>Upstart</code>,
|
||
or <code>systemd</code> to manage the <code>docker</code> daemon&rsquo;s start and stop.</p>
|
||
|
||
<h3 id="running-the-docker-daemon-directly">Running the docker daemon directly</h3>
|
||
|
||
<p>The <code>docker</code> daemon can be run directly using the <code>-d</code> option. By default it listens on
|
||
the Unix socket <code>unix:///var/run/docker.sock</code></p>
|
||
|
||
<pre><code>$ docker -d
|
||
|
||
INFO[0000] +job init_networkdriver()
|
||
INFO[0000] +job serveapi(unix:///var/run/docker.sock)
|
||
INFO[0000] Listening for HTTP on unix (/var/run/docker.sock)
|
||
...
|
||
...
|
||
</code></pre>
|
||
|
||
<h3 id="configuring-the-docker-daemon-directly">Configuring the docker daemon directly</h3>
|
||
|
||
<p>If you&rsquo;re running the <code>docker</code> daemon directly by running <code>docker -d</code> instead
|
||
of using a process manager, you can append the configuration options to the <code>docker</code> run
|
||
command directly. Just like the <code>-d</code> option, other options can be passed to the <code>docker</code>
|
||
daemon to configure it.</p>
|
||
|
||
<p>Some of the daemon&rsquo;s options are:</p>
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Flag</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<tr>
|
||
<td><code>-D</code>, <code>--debug=false</code></td>
|
||
<td>Enable or disable debug mode. By default, this is false.</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td><code>-H</code>,<code>--host=[]</code></td>
|
||
<td>Daemon socket(s) to connect to.</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td><code>--tls=false</code></td>
|
||
<td>Enable or disable TLS. By default, this is false.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>Here is a an example of running the <code>docker</code> daemon with configuration options:</p>
|
||
|
||
<pre><code>$ docker -d -D --tls=true --tlscert=/var/docker/server.pem --tlskey=/var/docker/serverkey.pem -H tcp://192.168.59.3:2376
|
||
</code></pre>
|
||
|
||
<p>These options :</p>
|
||
|
||
<ul>
|
||
<li>Enable <code>-D</code> (debug) mode</li>
|
||
<li>Set <code>tls</code> to true with the server certificate and key specified using <code>--tlscert</code> and <code>--tlskey</code> respectively</li>
|
||
<li>Listen for connections on <code>tcp://192.168.59.3:2376</code></li>
|
||
</ul>
|
||
|
||
<p>The command line reference has the <a href="http://localhost/reference/commandline/cli/#daemon">complete list of daemon flags</a>
|
||
with explanations.</p>
|
||
|
||
<h2 id="ubuntu">Ubuntu</h2>
|
||
|
||
<p>As of <code>14.04</code>, Ubuntu uses Upstart as a process manager. By default, Upstart jobs
|
||
are located in <code>/etc/init</code> and the <code>docker</code> Upstart job can be found at <code>/etc/init/docker.conf</code>.</p>
|
||
|
||
<p>After successfully <a href="http://localhost/installation/ubuntulinux/">installing Docker for Ubuntu</a>,
|
||
you can check the running status using Upstart in this way:</p>
|
||
|
||
<pre><code>$ sudo status docker
|
||
|
||
docker start/running, process 989
|
||
</code></pre>
|
||
|
||
<h3 id="running-docker">Running Docker</h3>
|
||
|
||
<p>You can start/stop/restart the <code>docker</code> daemon using</p>
|
||
|
||
<pre><code>$ sudo start docker
|
||
|
||
$ sudo stop docker
|
||
|
||
$ sudo restart docker
|
||
</code></pre>
|
||
|
||
<h3 id="configuring-docker">Configuring Docker</h3>
|
||
|
||
<p>You configure the <code>docker</code> daemon in the <code>/etc/default/docker</code> file on your
|
||
system. You do this by specifying values in a <code>DOCKER_OPTS</code> variable.</p>
|
||
|
||
<p>To configure Docker options:</p>
|
||
|
||
<ol>
|
||
<li><p>Log into your host as a user with <code>sudo</code> or <code>root</code> privileges.</p></li>
|
||
|
||
<li><p>If you don&rsquo;t have one, create the <code>/etc/default/docker</code> file on your host. Depending on how
|
||
you installed Docker, you may already have this file.</p></li>
|
||
|
||
<li><p>Open the file with your favorite editor.</p>
|
||
|
||
<pre><code>$ sudo vi /etc/default/docker
|
||
</code></pre></li>
|
||
|
||
<li><p>Add a <code>DOCKER_OPTS</code> variable with the following options. These options are appended to the
|
||
<code>docker</code> daemon&rsquo;s run command.</p></li>
|
||
</ol>
|
||
|
||
<pre><code> DOCKER_OPTS=&quot;-D --tls=true --tlscert=/var/docker/server.pem --tlskey=/var/docker/serverkey.pem -H tcp://192.168.59.3:2376&quot;
|
||
</code></pre>
|
||
|
||
<p>These options :</p>
|
||
|
||
<ul>
|
||
<li>Enable <code>-D</code> (debug) mode</li>
|
||
<li>Set <code>tls</code> to true with the server certificate and key specified using <code>--tlscert</code> and <code>--tlskey</code> respectively</li>
|
||
<li>Listen for connections on <code>tcp://192.168.59.3:2376</code></li>
|
||
</ul>
|
||
|
||
<p>The command line reference has the <a href="http://localhost/reference/commandline/cli/#daemon">complete list of daemon flags</a>
|
||
with explanations.</p>
|
||
|
||
<ol>
|
||
<li><p>Save and close the file.</p></li>
|
||
|
||
<li><p>Restart the <code>docker</code> daemon.</p>
|
||
|
||
<pre><code>$ sudo restart docker
|
||
</code></pre></li>
|
||
|
||
<li><p>Verify that the <code>docker</code> daemon is running as specified with the <code>ps</code> command.</p>
|
||
|
||
<pre><code>$ ps aux | grep docker | grep -v grep
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<h3 id="logs">Logs</h3>
|
||
|
||
<p>By default logs for Upstart jobs are located in <code>/var/log/upstart</code> and the logs for <code>docker</code> daemon
|
||
can be located at <code>/var/log/upstart/docker.log</code></p>
|
||
|
||
<pre><code>$ tail -f /var/log/upstart/docker.log
|
||
INFO[0000] Loading containers: done.
|
||
INFO[0000] docker daemon: 1.6.0 4749651; execdriver: native-0.2; graphdriver: aufs
|
||
INFO[0000] +job acceptconnections()
|
||
INFO[0000] -job acceptconnections() = OK (0)
|
||
INFO[0000] Daemon has completed initialization
|
||
</code></pre>
|
||
|
||
<h2 id="centos-red-hat-enterprise-linux-fedora">CentOS / Red Hat Enterprise Linux / Fedora</h2>
|
||
|
||
<p>As of <code>7.x</code>, CentOS and RHEL use <code>systemd</code> as the process manager. As of <code>21</code>, Fedora uses
|
||
<code>systemd</code> as its process manager.</p>
|
||
|
||
<p>After successfully installing Docker for <a href="http://localhost/installation/centos/">CentOS</a>/<a href="http://localhost/installation/rhel/">Red Hat Enterprise Linux</a>/<a href="http://localhost/installation/fedora">Fedora</a>, you can check the running status in this way:</p>
|
||
|
||
<pre><code>$ sudo systemctl status docker
|
||
</code></pre>
|
||
|
||
<h3 id="running-docker-1">Running Docker</h3>
|
||
|
||
<p>You can start/stop/restart the <code>docker</code> daemon using</p>
|
||
|
||
<pre><code>$ sudo systemctl start docker
|
||
|
||
$ sudo systemctl stop docker
|
||
|
||
$ sudo systemctl restart docker
|
||
</code></pre>
|
||
|
||
<p>If you want Docker to start at boot, you should also:</p>
|
||
|
||
<pre><code>$ sudo systemctl enable docker
|
||
</code></pre>
|
||
|
||
<h3 id="configuring-docker-1">Configuring Docker</h3>
|
||
|
||
<p>You configure the <code>docker</code> daemon in the <code>/etc/sysconfig/docker</code> file on your
|
||
host. You do this by specifying values in a variable. For CentOS 7.x and RHEL 7.x, the name
|
||
of the variable is <code>OPTIONS</code> and for CentOS 6.x and RHEL 6.x, the name of the variable is
|
||
<code>other_args</code>. For this section, we will use CentOS 7.x as an example to configure the <code>docker</code>
|
||
daemon.</p>
|
||
|
||
<p>By default, systemd services are located either in <code>/etc/systemd/service</code>, <code>/lib/systemd/system</code>
|
||
or <code>/usr/lib/systemd/system</code>. The <code>docker.service</code> file can be found in either of these three
|
||
directories depending on your host.</p>
|
||
|
||
<p>To configure Docker options:</p>
|
||
|
||
<ol>
|
||
<li><p>Log into your host as a user with <code>sudo</code> or <code>root</code> privileges.</p></li>
|
||
|
||
<li><p>If you don&rsquo;t have one, create the <code>/etc/sysconfig/docker</code> file on your host. Depending on how
|
||
you installed Docker, you may already have this file.</p></li>
|
||
|
||
<li><p>Open the file with your favorite editor.</p>
|
||
|
||
<pre><code>$ sudo vi /etc/sysconfig/docker
|
||
</code></pre></li>
|
||
|
||
<li><p>Add a <code>OPTIONS</code> variable with the following options. These options are appended to the
|
||
command that starts the <code>docker</code> daemon.</p></li>
|
||
</ol>
|
||
|
||
<pre><code> OPTIONS=&quot;-D --tls=true --tlscert=/var/docker/server.pem --tlskey=/var/docker/serverkey.pem -H tcp://192.168.59.3:2376&quot;
|
||
</code></pre>
|
||
|
||
<p>These options :</p>
|
||
|
||
<ul>
|
||
<li>Enable <code>-D</code> (debug) mode</li>
|
||
<li>Set <code>tls</code> to true with the server certificate and key specified using <code>--tlscert</code> and <code>--tlskey</code> respectively</li>
|
||
<li>Listen for connections on <code>tcp://192.168.59.3:2376</code></li>
|
||
</ul>
|
||
|
||
<p>The command line reference has the <a href="http://localhost/reference/commandline/cli/#daemon">complete list of daemon flags</a>
|
||
with explanations.</p>
|
||
|
||
<ol>
|
||
<li><p>Save and close the file.</p></li>
|
||
|
||
<li><p>Restart the <code>docker</code> daemon.</p>
|
||
|
||
<pre><code>$ sudo service docker restart
|
||
</code></pre></li>
|
||
|
||
<li><p>Verify that the <code>docker</code> daemon is running as specified with the <code>ps</code> command.</p>
|
||
|
||
<pre><code>$ ps aux | grep docker | grep -v grep
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<h3 id="logs-1">Logs</h3>
|
||
|
||
<p>systemd has its own logging system called the journal. The logs for the <code>docker</code> daemon can
|
||
be viewed using <code>journalctl -u docker</code></p>
|
||
|
||
<pre><code>$ sudo journalctl -u docker
|
||
May 06 00:22:05 localhost.localdomain systemd[1]: Starting Docker Application Container Engine...
|
||
May 06 00:22:05 localhost.localdomain docker[2495]: time=&quot;2015-05-06T00:22:05Z&quot; level=&quot;info&quot; msg=&quot;+job serveapi(unix:///var/run/docker.sock)&quot;
|
||
May 06 00:22:05 localhost.localdomain docker[2495]: time=&quot;2015-05-06T00:22:05Z&quot; level=&quot;info&quot; msg=&quot;Listening for HTTP on unix (/var/run/docker.sock)&quot;
|
||
May 06 00:22:06 localhost.localdomain docker[2495]: time=&quot;2015-05-06T00:22:06Z&quot; level=&quot;info&quot; msg=&quot;+job init_networkdriver()&quot;
|
||
May 06 00:22:06 localhost.localdomain docker[2495]: time=&quot;2015-05-06T00:22:06Z&quot; level=&quot;info&quot; msg=&quot;-job init_networkdriver() = OK (0)&quot;
|
||
May 06 00:22:06 localhost.localdomain docker[2495]: time=&quot;2015-05-06T00:22:06Z&quot; level=&quot;info&quot; msg=&quot;Loading containers: start.&quot;
|
||
May 06 00:22:06 localhost.localdomain docker[2495]: time=&quot;2015-05-06T00:22:06Z&quot; level=&quot;info&quot; msg=&quot;Loading containers: done.&quot;
|
||
May 06 00:22:06 localhost.localdomain docker[2495]: time=&quot;2015-05-06T00:22:06Z&quot; level=&quot;info&quot; msg=&quot;docker daemon: 1.5.0-dev fc0329b/1.5.0; execdriver: native-0.2; graphdriver: devicemapper&quot;
|
||
May 06 00:22:06 localhost.localdomain docker[2495]: time=&quot;2015-05-06T00:22:06Z&quot; level=&quot;info&quot; msg=&quot;+job acceptconnections()&quot;
|
||
May 06 00:22:06 localhost.localdomain docker[2495]: time=&quot;2015-05-06T00:22:06Z&quot; level=&quot;info&quot; msg=&quot;-job acceptconnections() = OK (0)&quot;
|
||
</code></pre>
|
||
|
||
<p><em>Note: Using and configuring journal is an advanced topic and is beyond the scope of this article.</em></p>
|
||
</description>
|
||
</item>
|
||
|
||
</channel>
|
||
</rss> |