mirror of
https://github.com/docker/docs.git
synced 2026-04-05 10:48:55 +07:00
2427 lines
112 KiB
XML
2427 lines
112 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>Composes on Docker Docs</title>
|
||
<link>http://localhost/compose/</link>
|
||
<description>Recent content in Composes on Docker Docs</description>
|
||
<generator>Hugo -- gohugo.io</generator>
|
||
<language>en-us</language>
|
||
<atom:link href="http://localhost/compose/index.xml" rel="self" type="application/rss+xml" />
|
||
|
||
<item>
|
||
<title></title>
|
||
<link>http://localhost/compose/README/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/README/</guid>
|
||
<description>
|
||
|
||
<h1 id="contributing-to-the-docker-compose-documentation">Contributing to the Docker Compose documentation</h1>
|
||
|
||
<p>The documentation in this directory is part of the <a href="https://docs.docker.com">https://docs.docker.com</a> website. Docker uses <a href="http://gohugo.io/overview/introduction/">the Hugo static generator</a> to convert project Markdown files to a static HTML site.</p>
|
||
|
||
<p>You don&rsquo;t need to be a Hugo expert to contribute to the compose documentation. If you are familiar with Markdown, you can modify the content in the <code>docs</code> files.</p>
|
||
|
||
<p>If you want to add a new file or change the location of the document in the menu, you do need to know a little more.</p>
|
||
|
||
<h2 id="documentation-contributing-workflow">Documentation contributing workflow</h2>
|
||
|
||
<ol>
|
||
<li><p>Edit a Markdown file in the tree.</p></li>
|
||
|
||
<li><p>Save your changes.</p></li>
|
||
|
||
<li><p>Make sure you are in the <code>docs</code> subdirectory.</p></li>
|
||
|
||
<li><p>Build the documentation.</p>
|
||
|
||
<pre><code>$ make docs
|
||
---&gt; ffcf3f6c4e97
|
||
Removing intermediate container a676414185e8
|
||
Successfully built ffcf3f6c4e97
|
||
docker run --rm -it -e AWS_S3_BUCKET -e NOCACHE -p 8000:8000 -e DOCKERHOST &quot;docs-base:test-tooling&quot; hugo server --port=8000 --baseUrl=192.168.59.103 --bind=0.0.0.0
|
||
ERROR: 2015/06/13 MenuEntry's .Url is deprecated and will be removed in Hugo 0.15. Use .URL instead.
|
||
0 of 4 drafts rendered
|
||
0 future content
|
||
12 pages created
|
||
0 paginator pages created
|
||
0 tags created
|
||
0 categories created
|
||
in 55 ms
|
||
Serving pages from /docs/public
|
||
Web Server is available at http://0.0.0.0:8000/
|
||
Press Ctrl+C to stop
|
||
</code></pre></li>
|
||
|
||
<li><p>Open the available server in your browser.</p>
|
||
|
||
<p>The documentation server has the complete menu but only the Docker Compose
|
||
documentation resolves. You can&rsquo;t access the other project docs from this
|
||
localized build.</p></li>
|
||
</ol>
|
||
|
||
<h2 id="tips-on-hugo-metadata-and-menu-positioning">Tips on Hugo metadata and menu positioning</h2>
|
||
|
||
<p>The top of each Docker Compose documentation file contains TOML metadata. The metadata is commented out to prevent it from appearing in GitHub.</p>
|
||
|
||
<pre><code>&lt;!--[metadata]&gt;
|
||
+++
|
||
title = &quot;Extending services in Compose&quot;
|
||
description = &quot;How to use Docker Compose's extends keyword to share configuration between files and projects&quot;
|
||
keywords = [&quot;fig, composition, compose, docker, orchestration, documentation, docs&quot;]
|
||
[menu.main]
|
||
parent=&quot;smn_workw_compose&quot;
|
||
weight=2
|
||
+++
|
||
&lt;![end-metadata]--&gt;
|
||
</code></pre>
|
||
|
||
<p>The metadata alone has this structure:</p>
|
||
|
||
<pre><code>+++
|
||
title = &quot;Extending services in Compose&quot;
|
||
description = &quot;How to use Docker Compose's extends keyword to share configuration between files and projects&quot;
|
||
keywords = [&quot;fig, composition, compose, docker, orchestration, documentation, docs&quot;]
|
||
[menu.main]
|
||
parent=&quot;smn_workw_compose&quot;
|
||
weight=2
|
||
+++
|
||
</code></pre>
|
||
|
||
<p>The <code>[menu.main]</code> section refers to navigation defined <a href="https://github.com/docker/docs-base/blob/hugo/config.toml">in the main Docker menu</a>. This metadata says <em>add a menu item called</em> Extending services in Compose <em>to the menu with the</em> <code>smn_workdw_compose</code> <em>identifier</em>. If you locate the menu in the configuration, you&rsquo;ll find <em>Create multi-container applications</em> is the menu title.</p>
|
||
|
||
<p>You can move an article in the tree by specifying a new parent. You can shift the location of the item by changing its weight. Higher numbers are heavier and shift the item to the bottom of menu. Low or no numbers shift it up.</p>
|
||
|
||
<h2 id="other-key-documentation-repositories">Other key documentation repositories</h2>
|
||
|
||
<p>The <code>docker/docs-base</code> repository contains <a href="https://github.com/docker/docs-base">the Hugo theme and menu configuration</a>. If you open the <code>Dockerfile</code> you&rsquo;ll see the <code>make docs</code> relies on this as a base image for building the Compose documentation.</p>
|
||
|
||
<p>The <code>docker/docs.docker.com</code> repository contains <a href="https://github.com/docker/docs.docker.com">build system for building the Docker documentation site</a>. Fork this repository to build the entire documentation site.</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Command-line Completion</title>
|
||
<link>http://localhost/compose/completion/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/completion/</guid>
|
||
<description>
|
||
|
||
<h1 id="command-line-completion">Command-line Completion</h1>
|
||
|
||
<p>Compose comes with <a href="http://en.wikipedia.org/wiki/Command-line_completion">command completion</a>
|
||
for the bash and zsh shell.</p>
|
||
|
||
<h2 id="installing-command-completion">Installing Command Completion</h2>
|
||
|
||
<h3 id="bash">Bash</h3>
|
||
|
||
<p>Make sure bash completion is installed. If you use a current Linux in a non-minimal installation, bash completion should be available.
|
||
On a Mac, install with <code>brew install bash-completion</code></p>
|
||
|
||
<p>Place the completion script in <code>/etc/bash_completion.d/</code> (<code>/usr/local/etc/bash_completion.d/</code> on a Mac), using e.g.</p>
|
||
|
||
<pre><code> curl -L https://raw.githubusercontent.com/docker/compose/$(docker-compose --version | awk 'NR==1{print $NF}')/contrib/completion/bash/docker-compose &gt; /etc/bash_completion.d/docker-compose
|
||
</code></pre>
|
||
|
||
<p>Completion will be available upon next login.</p>
|
||
|
||
<h3 id="zsh">Zsh</h3>
|
||
|
||
<p>Place the completion script in your <code>/path/to/zsh/completion</code>, using e.g. <code>~/.zsh/completion/</code></p>
|
||
|
||
<pre><code>mkdir -p ~/.zsh/completion
|
||
curl -L https://raw.githubusercontent.com/docker/compose/$(docker-compose --version | awk 'NR==1{print $NF}')/contrib/completion/zsh/_docker-compose &gt; ~/.zsh/completion/_docker-compose
|
||
</code></pre>
|
||
|
||
<p>Include the directory in your <code>$fpath</code>, e.g. by adding in <code>~/.zshrc</code></p>
|
||
|
||
<pre><code>fpath=(~/.zsh/completion $fpath)
|
||
</code></pre>
|
||
|
||
<p>Make sure <code>compinit</code> is loaded or do it by adding in <code>~/.zshrc</code></p>
|
||
|
||
<pre><code>autoload -Uz compinit &amp;&amp; compinit -i
|
||
</code></pre>
|
||
|
||
<p>Then reload your shell</p>
|
||
|
||
<pre><code>exec $SHELL -l
|
||
</code></pre>
|
||
|
||
<h2 id="available-completions">Available completions</h2>
|
||
|
||
<p>Depending on what you typed on the command line so far, it will complete</p>
|
||
|
||
<ul>
|
||
<li>available docker-compose commands</li>
|
||
<li>options that are available for a particular command</li>
|
||
<li>service names that make sense in a given context (e.g. services with running or stopped instances or services based on images vs. services based on Dockerfiles). For <code>docker-compose scale</code>, completed service names will automatically have &ldquo;=&rdquo; appended.</li>
|
||
<li>arguments for selected options, e.g. <code>docker-compose kill -s</code> will complete some signals like SIGHUP and SIGUSR1.</li>
|
||
</ul>
|
||
|
||
<p>Enjoy working with Compose faster and with less typos!</p>
|
||
|
||
<h2 id="compose-documentation">Compose documentation</h2>
|
||
|
||
<ul>
|
||
<li><a href="../compose/">User guide</a></li>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/django/">Get started with Django</a></li>
|
||
<li><a href="../compose/rails/">Get started with Rails</a></li>
|
||
<li><a href="../compose/wordpress/">Get started with WordPress</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Compose CLI reference</title>
|
||
<link>http://localhost/compose/reference/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/reference/</guid>
|
||
<description>
|
||
|
||
<h2 id="compose-cli-reference">Compose CLI reference</h2>
|
||
|
||
<p>The following pages describe the usage information for the <a href="../compose/reference/docker-compose/">docker-compose</a> subcommands. You can also see this information by running <code>docker-compose [SUBCOMMAND] --help</code> from the command line.</p>
|
||
|
||
<ul>
|
||
<li><a href="../compose/reference/build/">build</a></li>
|
||
<li><a href="../compose/reference/help/">help</a></li>
|
||
<li><a href="../compose/reference/kill/">kill</a></li>
|
||
<li><a href="../compose/reference/ps/">ps</a></li>
|
||
<li><a href="../compose/reference/restart/">restart</a></li>
|
||
<li><a href="../compose/reference/run/">run</a></li>
|
||
<li><a href="../compose/reference/start/">start</a></li>
|
||
<li><a href="../compose/reference/up/">up</a></li>
|
||
<li><a href="../compose/reference/logs/">logs</a></li>
|
||
<li><a href="../compose/reference/port/">port</a></li>
|
||
<li><a href="../compose/reference/pull/">pull</a></li>
|
||
<li><a href="../compose/reference/rm/">rm</a></li>
|
||
<li><a href="../compose/reference/scale/">scale</a></li>
|
||
<li><a href="../compose/reference/stop/">stop</a></li>
|
||
</ul>
|
||
|
||
<h2 id="where-to-go-next">Where to go next</h2>
|
||
|
||
<ul>
|
||
<li><a href="../compose/reference/overview/">CLI environment variables</a></li>
|
||
<li><a href="../compose/reference/docker-compose/">docker-compose Command</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Compose environment variables reference</title>
|
||
<link>http://localhost/compose/env/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/env/</guid>
|
||
<description>
|
||
|
||
<h1 id="compose-environment-variables-reference">Compose environment variables reference</h1>
|
||
|
||
<p><strong>Note:</strong> Environment variables are no longer the recommended method for connecting to linked services. Instead, you should use the link name (by default, the name of the linked service) as the hostname to connect to. See the <a href="../compose/compose-file/#links">docker-compose.yml documentation</a> for details.</p>
|
||
|
||
<p>Compose uses <a href="http://docs.docker.com/userguide/dockerlinks/">Docker links</a> to expose services&rsquo; containers to one another. Each linked container injects a set of environment variables, each of which begins with the uppercase name of the container.</p>
|
||
|
||
<p>To see what environment variables are available to a service, run <code>docker-compose run SERVICE env</code>.</p>
|
||
|
||
<p><b><i>name</i>_PORT</b><br>
|
||
Full URL, e.g. <code>DB_PORT=tcp://172.17.0.5:5432</code></p>
|
||
|
||
<p><b><i>name</i>_PORT_<i>num</i>_<i>protocol</i></b><br>
|
||
Full URL, e.g. <code>DB_PORT_5432_TCP=tcp://172.17.0.5:5432</code></p>
|
||
|
||
<p><b><i>name</i>_PORT_<i>num</i>_<i>protocol</i>_ADDR</b><br>
|
||
Container&rsquo;s IP address, e.g. <code>DB_PORT_5432_TCP_ADDR=172.17.0.5</code></p>
|
||
|
||
<p><b><i>name</i>_PORT_<i>num</i>_<i>protocol</i>_PORT</b><br>
|
||
Exposed port number, e.g. <code>DB_PORT_5432_TCP_PORT=5432</code></p>
|
||
|
||
<p><b><i>name</i>_PORT_<i>num</i>_<i>protocol</i>_PROTO</b><br>
|
||
Protocol (tcp or udp), e.g. <code>DB_PORT_5432_TCP_PROTO=tcp</code></p>
|
||
|
||
<p><b><i>name</i>_NAME</b><br>
|
||
Fully qualified container name, e.g. <code>DB_1_NAME=/myapp_web_1/myapp_db_1</code></p>
|
||
|
||
<h2 id="related-information">Related Information</h2>
|
||
|
||
<ul>
|
||
<li><a href="../compose/">User guide</a></li>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Compose file reference</title>
|
||
<link>http://localhost/compose/compose-file/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/compose-file/</guid>
|
||
<description>
|
||
|
||
<h1 id="compose-file-reference">Compose file reference</h1>
|
||
|
||
<p>The compose file is a <a href="http://yaml.org/">YAML</a> file where all the top level
|
||
keys are the name of a service, and the values are the service definition.
|
||
The default path for a compose file is <code>./docker-compose.yml</code>.</p>
|
||
|
||
<p>Each service defined in <code>docker-compose.yml</code> must specify exactly one of
|
||
<code>image</code> or <code>build</code>. Other keys are optional, and are analogous to their
|
||
<code>docker run</code> command-line counterparts.</p>
|
||
|
||
<p>As with <code>docker run</code>, options specified in the Dockerfile (e.g., <code>CMD</code>,
|
||
<code>EXPOSE</code>, <code>VOLUME</code>, <code>ENV</code>) are respected by default - you don&rsquo;t need to
|
||
specify them again in <code>docker-compose.yml</code>.</p>
|
||
|
||
<h2 id="service-configuration-reference">Service configuration reference</h2>
|
||
|
||
<p>This section contains a list of all configuration options supported by a service
|
||
definition.</p>
|
||
|
||
<h3 id="build">build</h3>
|
||
|
||
<p>Path to a directory containing a Dockerfile. When the value supplied is a
|
||
relative path, it is interpreted as relative to the location of the yml file
|
||
itself. This directory is also the build context that is sent to the Docker daemon.</p>
|
||
|
||
<p>Compose will build and tag it with a generated name, and use that image thereafter.</p>
|
||
|
||
<pre><code>build: /path/to/build/dir
|
||
</code></pre>
|
||
|
||
<p>Using <code>build</code> together with <code>image</code> is not allowed. Attempting to do so results in an error.</p>
|
||
|
||
<h3 id="cap-add-cap-drop">cap_add, cap_drop</h3>
|
||
|
||
<p>Add or drop container capabilities.
|
||
See <code>man 7 capabilities</code> for a full list.</p>
|
||
|
||
<pre><code>cap_add:
|
||
- ALL
|
||
|
||
cap_drop:
|
||
- NET_ADMIN
|
||
- SYS_ADMIN
|
||
</code></pre>
|
||
|
||
<h3 id="command">command</h3>
|
||
|
||
<p>Override the default command.</p>
|
||
|
||
<pre><code>command: bundle exec thin -p 3000
|
||
</code></pre>
|
||
|
||
<h3 id="cgroup-parent">cgroup_parent</h3>
|
||
|
||
<p>Specify an optional parent cgroup for the container.</p>
|
||
|
||
<pre><code>cgroup_parent: m-executor-abcd
|
||
</code></pre>
|
||
|
||
<h3 id="container-name">container_name</h3>
|
||
|
||
<p>Specify a custom container name, rather than a generated default name.</p>
|
||
|
||
<pre><code>container_name: my-web-container
|
||
</code></pre>
|
||
|
||
<p>Because Docker container names must be unique, you cannot scale a service
|
||
beyond 1 container if you have specified a custom name. Attempting to do so
|
||
results in an error.</p>
|
||
|
||
<h3 id="devices">devices</h3>
|
||
|
||
<p>List of device mappings. Uses the same format as the <code>--device</code> docker
|
||
client create option.</p>
|
||
|
||
<pre><code>devices:
|
||
- &quot;/dev/ttyUSB0:/dev/ttyUSB0&quot;
|
||
</code></pre>
|
||
|
||
<h3 id="dns">dns</h3>
|
||
|
||
<p>Custom DNS servers. Can be a single value or a list.</p>
|
||
|
||
<pre><code>dns: 8.8.8.8
|
||
dns:
|
||
- 8.8.8.8
|
||
- 9.9.9.9
|
||
</code></pre>
|
||
|
||
<h3 id="dns-search">dns_search</h3>
|
||
|
||
<p>Custom DNS search domains. Can be a single value or a list.</p>
|
||
|
||
<pre><code>dns_search: example.com
|
||
dns_search:
|
||
- dc1.example.com
|
||
- dc2.example.com
|
||
</code></pre>
|
||
|
||
<h3 id="dockerfile">dockerfile</h3>
|
||
|
||
<p>Alternate Dockerfile.</p>
|
||
|
||
<p>Compose will use an alternate file to build with.</p>
|
||
|
||
<pre><code>dockerfile: Dockerfile-alternate
|
||
</code></pre>
|
||
|
||
<p>Using <code>dockerfile</code> together with <code>image</code> is not allowed. Attempting to do so results in an error.</p>
|
||
|
||
<h3 id="env-file">env_file</h3>
|
||
|
||
<p>Add environment variables from a file. Can be a single value or a list.</p>
|
||
|
||
<p>If you have specified a Compose file with <code>docker-compose -f FILE</code>, paths in
|
||
<code>env_file</code> are relative to the directory that file is in.</p>
|
||
|
||
<p>Environment variables specified in <code>environment</code> override these values.</p>
|
||
|
||
<pre><code>env_file: .env
|
||
|
||
env_file:
|
||
- ./common.env
|
||
- ./apps/web.env
|
||
- /opt/secrets.env
|
||
</code></pre>
|
||
|
||
<p>Compose expects each line in an env file to be in <code>VAR=VAL</code> format. Lines
|
||
beginning with <code>#</code> (i.e. comments) are ignored, as are blank lines.</p>
|
||
|
||
<pre><code># Set Rails/Rack environment
|
||
RACK_ENV=development
|
||
</code></pre>
|
||
|
||
<h3 id="environment">environment</h3>
|
||
|
||
<p>Add environment variables. You can use either an array or a dictionary. Any
|
||
boolean values; true, false, yes no, need to be enclosed in quotes to ensure
|
||
they are not converted to True or False by the YML parser.</p>
|
||
|
||
<p>Environment variables with only a key are resolved to their values on the
|
||
machine Compose is running on, which can be helpful for secret or host-specific values.</p>
|
||
|
||
<pre><code>environment:
|
||
RACK_ENV: development
|
||
SHOW: 'true'
|
||
SESSION_SECRET:
|
||
|
||
environment:
|
||
- RACK_ENV=development
|
||
- SHOW=true
|
||
- SESSION_SECRET
|
||
</code></pre>
|
||
|
||
<h3 id="expose">expose</h3>
|
||
|
||
<p>Expose ports without publishing them to the host machine - they&rsquo;ll only be
|
||
accessible to linked services. Only the internal port can be specified.</p>
|
||
|
||
<pre><code>expose:
|
||
- &quot;3000&quot;
|
||
- &quot;8000&quot;
|
||
</code></pre>
|
||
|
||
<h3 id="extends">extends</h3>
|
||
|
||
<p>Extend another service, in the current file or another, optionally overriding
|
||
configuration.</p>
|
||
|
||
<p>You can use <code>extends</code> on any service together with other configuration keys.
|
||
The <code>extends</code> value must be a dictionary defined with a required <code>service</code>
|
||
and an optional <code>file</code> key.</p>
|
||
|
||
<pre><code>extends:
|
||
file: common.yml
|
||
service: webapp
|
||
</code></pre>
|
||
|
||
<p>The <code>service</code> the name of the service being extended, for example
|
||
<code>web</code> or <code>database</code>. The <code>file</code> is the location of a Compose configuration
|
||
file defining that service.</p>
|
||
|
||
<p>If you omit the <code>file</code> Compose looks for the service configuration in the
|
||
current file. The <code>file</code> value can be an absolute or relative path. If you
|
||
specify a relative path, Compose treats it as relative to the location of the
|
||
current file.</p>
|
||
|
||
<p>You can extend a service that itself extends another. You can extend
|
||
indefinitely. Compose does not support circular references and <code>docker-compose</code>
|
||
returns an error if it encounters one.</p>
|
||
|
||
<p>For more on <code>extends</code>, see the
|
||
<a href="../compose/extends/#extending-services">the extends documentation</a>.</p>
|
||
|
||
<h3 id="external-links">external_links</h3>
|
||
|
||
<p>Link to containers started outside this <code>docker-compose.yml</code> or even outside
|
||
of Compose, especially for containers that provide shared or common services.
|
||
<code>external_links</code> follow semantics similar to <code>links</code> when specifying both the
|
||
container name and the link alias (<code>CONTAINER:ALIAS</code>).</p>
|
||
|
||
<pre><code>external_links:
|
||
- redis_1
|
||
- project_db_1:mysql
|
||
- project_db_1:postgresql
|
||
</code></pre>
|
||
|
||
<h3 id="extra-hosts">extra_hosts</h3>
|
||
|
||
<p>Add hostname mappings. Use the same values as the docker client <code>--add-host</code> parameter.</p>
|
||
|
||
<pre><code>extra_hosts:
|
||
- &quot;somehost:162.242.195.82&quot;
|
||
- &quot;otherhost:50.31.209.229&quot;
|
||
</code></pre>
|
||
|
||
<p>An entry with the ip address and hostname will be created in <code>/etc/hosts</code> inside containers for this service, e.g:</p>
|
||
|
||
<pre><code>162.242.195.82 somehost
|
||
50.31.209.229 otherhost
|
||
</code></pre>
|
||
|
||
<h3 id="image">image</h3>
|
||
|
||
<p>Tag or partial image ID. Can be local or remote - Compose will attempt to
|
||
pull if it doesn&rsquo;t exist locally.</p>
|
||
|
||
<pre><code>image: ubuntu
|
||
image: orchardup/postgresql
|
||
image: a4bc65fd
|
||
</code></pre>
|
||
|
||
<h3 id="labels">labels</h3>
|
||
|
||
<p>Add metadata to containers using <a href="http://docs.docker.com/userguide/labels-custom-metadata/">Docker labels</a>. You can use either an array or a dictionary.</p>
|
||
|
||
<p>It&rsquo;s recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.</p>
|
||
|
||
<pre><code>labels:
|
||
com.example.description: &quot;Accounting webapp&quot;
|
||
com.example.department: &quot;Finance&quot;
|
||
com.example.label-with-empty-value: &quot;&quot;
|
||
|
||
labels:
|
||
- &quot;com.example.description=Accounting webapp&quot;
|
||
- &quot;com.example.department=Finance&quot;
|
||
- &quot;com.example.label-with-empty-value&quot;
|
||
</code></pre>
|
||
|
||
<h3 id="links">links</h3>
|
||
|
||
<p>Link to containers in another service. Either specify both the service name and
|
||
the link alias (<code>SERVICE:ALIAS</code>), or just the service name (which will also be
|
||
used for the alias).</p>
|
||
|
||
<pre><code>links:
|
||
- db
|
||
- db:database
|
||
- redis
|
||
</code></pre>
|
||
|
||
<p>An entry with the alias&rsquo; name will be created in <code>/etc/hosts</code> inside containers
|
||
for this service, e.g:</p>
|
||
|
||
<pre><code>172.17.2.186 db
|
||
172.17.2.186 database
|
||
172.17.2.187 redis
|
||
</code></pre>
|
||
|
||
<p>Environment variables will also be created - see the <a href="../compose/env/">environment variable
|
||
reference</a> for details.</p>
|
||
|
||
<h3 id="log-driver">log_driver</h3>
|
||
|
||
<p>Specify a logging driver for the service&rsquo;s containers, as with the <code>--log-driver</code>
|
||
option for docker run (<a href="https://docs.docker.com/reference/logging/overview/">documented here</a>).</p>
|
||
|
||
<p>The default value is json-file.</p>
|
||
|
||
<pre><code>log_driver: &quot;json-file&quot;
|
||
log_driver: &quot;syslog&quot;
|
||
log_driver: &quot;none&quot;
|
||
</code></pre>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong> Only the <code>json-file</code> driver makes the logs available directly from
|
||
<code>docker-compose up</code> and <code>docker-compose logs</code>. Using any other driver will not
|
||
print any logs.</p>
|
||
</blockquote>
|
||
|
||
<h3 id="log-opt">log_opt</h3>
|
||
|
||
<p>Specify logging options with <code>log_opt</code> for the logging driver, as with the <code>--log-opt</code> option for <code>docker run</code>.</p>
|
||
|
||
<p>Logging options are key value pairs. An example of <code>syslog</code> options:</p>
|
||
|
||
<pre><code>log_driver: &quot;syslog&quot;
|
||
log_opt:
|
||
syslog-address: &quot;tcp://192.168.0.42:123&quot;
|
||
</code></pre>
|
||
|
||
<h3 id="net">net</h3>
|
||
|
||
<p>Networking mode. Use the same values as the docker client <code>--net</code> parameter.</p>
|
||
|
||
<pre><code>net: &quot;bridge&quot;
|
||
net: &quot;none&quot;
|
||
net: &quot;container:[name or id]&quot;
|
||
net: &quot;host&quot;
|
||
</code></pre>
|
||
|
||
<h3 id="pid">pid</h3>
|
||
|
||
<pre><code>pid: &quot;host&quot;
|
||
</code></pre>
|
||
|
||
<p>Sets the PID mode to the host PID mode. This turns on sharing between
|
||
container and the host operating system the PID address space. Containers
|
||
launched with this flag will be able to access and manipulate other
|
||
containers in the bare-metal machine&rsquo;s namespace and vise-versa.</p>
|
||
|
||
<h3 id="ports">ports</h3>
|
||
|
||
<p>Expose ports. Either specify both ports (<code>HOST:CONTAINER</code>), or just the container
|
||
port (a random host port will be chosen).</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong> When mapping ports in the <code>HOST:CONTAINER</code> format, you may experience
|
||
erroneous results when using a container port lower than 60, because YAML will
|
||
parse numbers in the format <code>xx:yy</code> as sexagesimal (base 60). For this reason,
|
||
we recommend always explicitly specifying your port mappings as strings.</p>
|
||
</blockquote>
|
||
|
||
<pre><code>ports:
|
||
- &quot;3000&quot;
|
||
- &quot;3000-3005&quot;
|
||
- &quot;8000:8000&quot;
|
||
- &quot;9090-9091:8080-8081&quot;
|
||
- &quot;49100:22&quot;
|
||
- &quot;127.0.0.1:8001:8001&quot;
|
||
- &quot;127.0.0.1:5000-5010:5000-5010&quot;
|
||
</code></pre>
|
||
|
||
<h3 id="security-opt">security_opt</h3>
|
||
|
||
<p>Override the default labeling scheme for each container.</p>
|
||
|
||
<pre><code> security_opt:
|
||
- label:user:USER
|
||
- label:role:ROLE
|
||
</code></pre>
|
||
|
||
<h3 id="volumes-volume-driver">volumes, volume_driver</h3>
|
||
|
||
<p>Mount paths as volumes, optionally specifying a path on the host machine
|
||
(<code>HOST:CONTAINER</code>), or an access mode (<code>HOST:CONTAINER:ro</code>).</p>
|
||
|
||
<pre><code>volumes:
|
||
- /var/lib/mysql
|
||
- ./cache:/tmp/cache
|
||
- ~/configs:/etc/configs/:ro
|
||
</code></pre>
|
||
|
||
<p>You can mount a relative path on the host, which will expand relative to
|
||
the directory of the Compose configuration file being used. Relative paths
|
||
should always begin with <code>.</code> or <code>..</code>.</p>
|
||
|
||
<p>If you use a volume name (instead of a volume path), you may also specify
|
||
a <code>volume_driver</code>.</p>
|
||
|
||
<pre><code>volume_driver: mydriver
|
||
</code></pre>
|
||
|
||
<blockquote>
|
||
<p>Note: No path expansion will be done if you have also specified a
|
||
<code>volume_driver</code>.</p>
|
||
</blockquote>
|
||
|
||
<p>See <a href="https://docs.docker.com/userguide/dockervolumes/">Docker Volumes</a> and
|
||
<a href="https://docs.docker.com/extend/plugins_volume/">Volume Plugins</a> for more
|
||
information.</p>
|
||
|
||
<h3 id="volumes-from">volumes_from</h3>
|
||
|
||
<p>Mount all of the volumes from another service or container, optionally
|
||
specifying read-only access(<code>ro</code>) or read-write(<code>rw</code>).</p>
|
||
|
||
<pre><code>volumes_from:
|
||
- service_name
|
||
- container_name
|
||
- service_name:rw
|
||
</code></pre>
|
||
|
||
<h3 id="cpu-shares-cpuset-domainname-entrypoint-hostname-ipc-mac-address-mem-limit-memswap-limit-privileged-read-only-restart-stdin-open-tty-user-working-dir">cpu_shares, cpuset, domainname, entrypoint, hostname, ipc, mac_address, mem_limit, memswap_limit, privileged, read_only, restart, stdin_open, tty, user, working_dir</h3>
|
||
|
||
<p>Each of these is a single value, analogous to its
|
||
<a href="https://docs.docker.com/reference/run/">docker run</a> counterpart.</p>
|
||
|
||
<pre><code>cpu_shares: 73
|
||
cpuset: 0,1
|
||
|
||
entrypoint: /code/entrypoint.sh
|
||
user: postgresql
|
||
working_dir: /code
|
||
|
||
domainname: foo.com
|
||
hostname: foo
|
||
ipc: host
|
||
mac_address: 02:42:ac:11:65:43
|
||
|
||
mem_limit: 1000000000
|
||
memswap_limit: 2000000000
|
||
privileged: true
|
||
|
||
restart: always
|
||
|
||
read_only: true
|
||
stdin_open: true
|
||
tty: true
|
||
</code></pre>
|
||
|
||
<h2 id="variable-substitution">Variable substitution</h2>
|
||
|
||
<p>Your configuration options can contain environment variables. Compose uses the
|
||
variable values from the shell environment in which <code>docker-compose</code> is run. For
|
||
example, suppose the shell contains <code>POSTGRES_VERSION=9.3</code> and you supply this
|
||
configuration:</p>
|
||
|
||
<pre><code>db:
|
||
image: &quot;postgres:${POSTGRES_VERSION}&quot;
|
||
</code></pre>
|
||
|
||
<p>When you run <code>docker-compose up</code> with this configuration, Compose looks for the
|
||
<code>POSTGRES_VERSION</code> environment variable in the shell and substitutes its value
|
||
in. For this example, Compose resolves the <code>image</code> to <code>postgres:9.3</code> before
|
||
running the configuration.</p>
|
||
|
||
<p>If an environment variable is not set, Compose substitutes with an empty
|
||
string. In the example above, if <code>POSTGRES_VERSION</code> is not set, the value for
|
||
the <code>image</code> option is <code>postgres:</code>.</p>
|
||
|
||
<p>Both <code>$VARIABLE</code> and <code>${VARIABLE}</code> syntax are supported. Extended shell-style
|
||
features, such as <code>${VARIABLE-default}</code> and <code>${VARIABLE/foo/bar}</code>, are not
|
||
supported.</p>
|
||
|
||
<p>You can use a <code>$$</code> (double-dollar sign) when your configuration needs a literal
|
||
dollar sign. This also prevents Compose from interpolating a value, so a <code>$$</code>
|
||
allows you to refer to environment variables that you don&rsquo;t want processed by
|
||
Compose.</p>
|
||
|
||
<pre><code>web:
|
||
build: .
|
||
command: &quot;$$VAR_NOT_INTERPOLATED_BY_COMPOSE&quot;
|
||
</code></pre>
|
||
|
||
<p>If you forget and use a single dollar sign (<code>$</code>), Compose interprets the value as an environment variable and will warn you:</p>
|
||
|
||
<p>The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.</p>
|
||
|
||
<h2 id="compose-documentation">Compose documentation</h2>
|
||
|
||
<ul>
|
||
<li><a href="../compose/">User guide</a></li>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/django/">Get started with Django</a></li>
|
||
<li><a href="../compose/rails/">Get started with Rails</a></li>
|
||
<li><a href="../compose/wordpress/">Get started with WordPress</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Docker Compose</title>
|
||
<link>http://localhost/compose/install/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/install/</guid>
|
||
<description>
|
||
|
||
<h1 id="install-docker-compose">Install Docker Compose</h1>
|
||
|
||
<p>You can run Compose on OS X and 64-bit Linux. It is currently not supported on
|
||
the Windows operating system. To install Compose, you&rsquo;ll need to install Docker
|
||
first.</p>
|
||
|
||
<p>To install Compose, do the following:</p>
|
||
|
||
<ol>
|
||
<li><p>Install Docker Engine version 1.7.1 or greater:</p>
|
||
|
||
<ul>
|
||
<li><p><a href="https://docs.docker.com/installation/mac/" target="_blank">Mac OS X installation</a> (Toolbox installation includes both Engine and Compose)</p></li>
|
||
|
||
<li><p><a href="https://docs.docker.com/installation/ubuntulinux/" target="_blank">Ubuntu installation</a></p></li>
|
||
|
||
<li><p><a href="https://docs.docker.com/installation/" target="_blank">other system installations</a></p></li>
|
||
</ul></li>
|
||
|
||
<li><p>Mac OS X users are done installing. Others should continue to the next step.</p></li>
|
||
|
||
<li><p>Go to the <a href="https://github.com/docker/compose/releases" target="_blank">Compose repository release page on GitHub</a>.</p></li>
|
||
|
||
<li><p>Follow the instructions from the release page and run the <code>curl</code> command,
|
||
which the release page specifies, in your terminal.</p>
|
||
|
||
<blockquote>
|
||
<p>Note: If you get a &ldquo;Permission denied&rdquo; error, your <code>/usr/local/bin</code> directory
|
||
probably isn&rsquo;t writable and you&rsquo;ll need to install Compose as the superuser. Run
|
||
<code>sudo -i</code>, then the two commands below, then <code>exit</code>.</p>
|
||
</blockquote>
|
||
|
||
<p>The following is an example command illustrating the format:</p>
|
||
|
||
<pre><code>curl -L https://github.com/docker/compose/releases/download/VERSION_NUM/docker-compose-`uname -s`-`uname -m` &gt; /usr/local/bin/docker-compose
|
||
</code></pre>
|
||
|
||
<p>If you have problems installing with <code>curl</code>, see
|
||
<a href="#alternative-install-options">Alternative Install Options</a>.</p></li>
|
||
|
||
<li><p>Apply executable permissions to the binary:</p>
|
||
|
||
<pre><code>$ chmod +x /usr/local/bin/docker-compose
|
||
</code></pre></li>
|
||
|
||
<li><p>Optionally, install <a href="../compose/completion/">command completion</a> for the
|
||
<code>bash</code> and <code>zsh</code> shell.</p></li>
|
||
|
||
<li><p>Test the installation.</p>
|
||
|
||
<pre><code>$ docker-compose --version
|
||
docker-compose version: 1.5.0
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<h2 id="alternative-install-options">Alternative install options</h2>
|
||
|
||
<h3 id="install-using-pip">Install using pip</h3>
|
||
|
||
<p>Compose can be installed from <a href="https://pypi.python.org/pypi/docker-compose">pypi</a>
|
||
using <code>pip</code>. If you install using <code>pip</code> it is highly recommended that you use a
|
||
<a href="https://virtualenv.pypa.io/en/latest/">virtualenv</a> because many operating systems
|
||
have python system packages that conflict with docker-compose dependencies. See
|
||
the <a href="http://docs.python-guide.org/en/latest/dev/virtualenvs/">virtualenv tutorial</a>
|
||
to get started.</p>
|
||
|
||
<pre><code>$ pip install docker-compose
|
||
</code></pre>
|
||
|
||
<h3 id="install-as-a-container">Install as a container</h3>
|
||
|
||
<p>Compose can also be run inside a container, from a small bash script wrapper.
|
||
To install compose as a container run:</p>
|
||
|
||
<pre><code>$ curl -L https://github.com/docker/compose/releases/download/1.5.0/run.sh &gt; /usr/local/bin/docker-compose
|
||
$ chmod +x /usr/local/bin/docker-compose
|
||
</code></pre>
|
||
|
||
<h2 id="master-builds">Master builds</h2>
|
||
|
||
<p>If you&rsquo;re interested in trying out a pre-release build you can download a
|
||
binary from <a href="https://dl.bintray.com/docker-compose/master/">https://dl.bintray.com/docker-compose/master/</a>. Pre-release
|
||
builds allow you to try out new features before they are released, but may
|
||
be less stable.</p>
|
||
|
||
<h2 id="upgrading">Upgrading</h2>
|
||
|
||
<p>If you&rsquo;re upgrading from Compose 1.2 or earlier, you&rsquo;ll need to remove or migrate
|
||
your existing containers after upgrading Compose. This is because, as of version
|
||
1.3, Compose uses Docker labels to keep track of containers, and so they need to
|
||
be recreated with labels added.</p>
|
||
|
||
<p>If Compose detects containers that were created without labels, it will refuse
|
||
to run so that you don&rsquo;t end up with two sets of them. If you want to keep using
|
||
your existing containers (for example, because they have data volumes you want
|
||
to preserve) you can migrate them with the following command:</p>
|
||
|
||
<pre><code>$ docker-compose migrate-to-labels
|
||
</code></pre>
|
||
|
||
<p>Alternatively, if you&rsquo;re not worried about keeping them, you can remove them.
|
||
Compose will just create new ones.</p>
|
||
|
||
<pre><code>$ docker rm -f -v myapp_web_1 myapp_db_1 ...
|
||
</code></pre>
|
||
|
||
<h2 id="uninstallation">Uninstallation</h2>
|
||
|
||
<p>To uninstall Docker Compose if you installed using <code>curl</code>:</p>
|
||
|
||
<pre><code>$ rm /usr/local/bin/docker-compose
|
||
</code></pre>
|
||
|
||
<p>To uninstall Docker Compose if you installed using <code>pip</code>:</p>
|
||
|
||
<pre><code>$ pip uninstall docker-compose
|
||
</code></pre>
|
||
|
||
<blockquote>
|
||
<p><strong>Note</strong>: If you get a &ldquo;Permission denied&rdquo; error using either of the above
|
||
methods, you probably do not have the proper permissions to remove
|
||
<code>docker-compose</code>. To force the removal, prepend <code>sudo</code> to either of the above
|
||
commands and run again.</p>
|
||
</blockquote>
|
||
|
||
<h2 id="where-to-go-next">Where to go next</h2>
|
||
|
||
<ul>
|
||
<li><a href="../">User guide</a></li>
|
||
<li><a href="../compose/gettingstarted/">Getting Started</a></li>
|
||
<li><a href="../compose/django/">Get started with Django</a></li>
|
||
<li><a href="../compose/rails/">Get started with Rails</a></li>
|
||
<li><a href="../compose/wordpress/">Get started with WordPress</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Extending services in Compose</title>
|
||
<link>http://localhost/compose/extends/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/extends/</guid>
|
||
<description>
|
||
|
||
<h1 id="extending-services-and-compose-files">Extending services and Compose files</h1>
|
||
|
||
<p>Compose supports two methods of sharing common configuration:</p>
|
||
|
||
<ol>
|
||
<li>Extending an entire Compose file by
|
||
<a href="#multiple-compose-files">using multiple Compose files</a></li>
|
||
<li>Extending individual services with <a href="#extending-services">the <code>extends</code> field</a></li>
|
||
</ol>
|
||
|
||
<h2 id="multiple-compose-files">Multiple Compose files</h2>
|
||
|
||
<p>Using multiple Compose files enables you to customize a Compose application
|
||
for different environments or different workflows.</p>
|
||
|
||
<h3 id="understanding-multiple-compose-files">Understanding multiple Compose files</h3>
|
||
|
||
<p>By default, Compose reads two files, a <code>docker-compose.yml</code> and an optional
|
||
<code>docker-compose.override.yml</code> file. By convention, the <code>docker-compose.yml</code>
|
||
contains your base configuration. The override file, as its name implies, can
|
||
contain configuration overrides for existing services or entirely new
|
||
services.</p>
|
||
|
||
<p>If a service is defined in both files, Compose merges the configurations using
|
||
the same rules as the <code>extends</code> field (see <a href="#adding-and-overriding-configuration">Adding and overriding
|
||
configuration</a>), with one exception. If a
|
||
service contains <code>links</code> or <code>volumes_from</code> those fields are copied over and
|
||
replace any values in the original service, in the same way single-valued fields
|
||
are copied.</p>
|
||
|
||
<p>To use multiple override files, or an override file with a different name, you
|
||
can use the <code>-f</code> option to specify the list of files. Compose merges files in
|
||
the order they&rsquo;re specified on the command line. See the <a href="../compose/reference/docker-compose/"><code>docker-compose</code>
|
||
command reference</a> for more information about
|
||
using <code>-f</code>.</p>
|
||
|
||
<p>When you use multiple configuration files, you must make sure all paths in the
|
||
files are relative to the base Compose file (the first Compose file specified
|
||
with <code>-f</code>). This is required because override files need not be valid
|
||
Compose files. Override files can contain small fragments of configuration.
|
||
Tracking which fragment of a service is relative to which path is difficult and
|
||
confusing, so to keep paths easier to understand, all paths must be defined
|
||
relative to the base file.</p>
|
||
|
||
<h3 id="example-use-case">Example use case</h3>
|
||
|
||
<p>In this section are two common use cases for multiple compose files: changing a
|
||
Compose app for different environments, and running administrative tasks
|
||
against a Compose app.</p>
|
||
|
||
<h4 id="different-environments">Different environments</h4>
|
||
|
||
<p>A common use case for multiple files is changing a development Compose app
|
||
for a production-like environment (which may be production, staging or CI).
|
||
To support these differences, you can split your Compose configuration into
|
||
a few different files:</p>
|
||
|
||
<p>Start with a base file that defines the canonical configuration for the
|
||
services.</p>
|
||
|
||
<p><strong>docker-compose.yml</strong></p>
|
||
|
||
<pre><code>web:
|
||
image: example/my_web_app:latest
|
||
links:
|
||
- db
|
||
- cache
|
||
|
||
db:
|
||
image: postgres:latest
|
||
|
||
cache:
|
||
image: redis:latest
|
||
</code></pre>
|
||
|
||
<p>In this example the development configuration exposes some ports to the
|
||
host, mounts our code as a volume, and builds the web image.</p>
|
||
|
||
<p><strong>docker-compose.override.yml</strong></p>
|
||
|
||
<pre><code>web:
|
||
build: .
|
||
volumes:
|
||
- '.:/code'
|
||
ports:
|
||
- 8883:80
|
||
environment:
|
||
DEBUG: 'true'
|
||
|
||
db:
|
||
command: '-d'
|
||
ports:
|
||
- 5432:5432
|
||
|
||
cache:
|
||
ports:
|
||
- 6379:6379
|
||
</code></pre>
|
||
|
||
<p>When you run <code>docker-compose up</code> it reads the overrides automatically.</p>
|
||
|
||
<p>Now, it would be nice to use this Compose app in a production environment. So,
|
||
create another override file (which might be stored in a different git
|
||
repo or managed by a different team).</p>
|
||
|
||
<p><strong>docker-compose.prod.yml</strong></p>
|
||
|
||
<pre><code>web:
|
||
ports:
|
||
- 80:80
|
||
environment:
|
||
PRODUCTION: 'true'
|
||
|
||
cache:
|
||
environment:
|
||
TTL: '500'
|
||
</code></pre>
|
||
|
||
<p>To deploy with this production Compose file you can run</p>
|
||
|
||
<pre><code>docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
||
</code></pre>
|
||
|
||
<p>This deploys all three services using the configuration in
|
||
<code>docker-compose.yml</code> and <code>docker-compose.prod.yml</code> (but not the
|
||
dev configuration in <code>docker-compose.override.yml</code>).</p>
|
||
|
||
<p>See <a href="../compose/production/">production</a> for more information about Compose in
|
||
production.</p>
|
||
|
||
<h4 id="administrative-tasks">Administrative tasks</h4>
|
||
|
||
<p>Another common use case is running adhoc or administrative tasks against one
|
||
or more services in a Compose app. This example demonstrates running a
|
||
database backup.</p>
|
||
|
||
<p>Start with a <strong>docker-compose.yml</strong>.</p>
|
||
|
||
<pre><code>web:
|
||
image: example/my_web_app:latest
|
||
links:
|
||
- db
|
||
|
||
db:
|
||
image: postgres:latest
|
||
</code></pre>
|
||
|
||
<p>In a <strong>docker-compose.admin.yml</strong> add a new service to run the database
|
||
export or backup.</p>
|
||
|
||
<pre><code>dbadmin:
|
||
build: database_admin/
|
||
links:
|
||
- db
|
||
</code></pre>
|
||
|
||
<p>To start a normal environment run <code>docker-compose up -d</code>. To run a database
|
||
backup, include the <code>docker-compose.admin.yml</code> as well.</p>
|
||
|
||
<pre><code>docker-compose -f docker-compose.yml -f docker-compose.admin.yml \
|
||
run dbadmin db-backup
|
||
</code></pre>
|
||
|
||
<h2 id="extending-services">Extending services</h2>
|
||
|
||
<p>Docker Compose&rsquo;s <code>extends</code> keyword enables sharing of common configurations
|
||
among different files, or even different projects entirely. Extending services
|
||
is useful if you have several services that reuse a common set of configuration
|
||
options. Using <code>extends</code> you can define a common set of service options in one
|
||
place and refer to it from anywhere.</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong> <code>links</code> and <code>volumes_from</code> are never shared between services using
|
||
<code>extends</code>. See
|
||
<a href="#adding-and-overriding-configuration">Adding and overriding configuration</a>
|
||
for more information.</p>
|
||
</blockquote>
|
||
|
||
<h3 id="understand-the-extends-configuration">Understand the extends configuration</h3>
|
||
|
||
<p>When defining any service in <code>docker-compose.yml</code>, you can declare that you are
|
||
extending another service like this:</p>
|
||
|
||
<pre><code>web:
|
||
extends:
|
||
file: common-services.yml
|
||
service: webapp
|
||
</code></pre>
|
||
|
||
<p>This instructs Compose to re-use the configuration for the <code>webapp</code> service
|
||
defined in the <code>common-services.yml</code> file. Suppose that <code>common-services.yml</code>
|
||
looks like this:</p>
|
||
|
||
<pre><code>webapp:
|
||
build: .
|
||
ports:
|
||
- &quot;8000:8000&quot;
|
||
volumes:
|
||
- &quot;/data&quot;
|
||
</code></pre>
|
||
|
||
<p>In this case, you&rsquo;ll get exactly the same result as if you wrote
|
||
<code>docker-compose.yml</code> with the same <code>build</code>, <code>ports</code> and <code>volumes</code> configuration
|
||
values defined directly under <code>web</code>.</p>
|
||
|
||
<p>You can go further and define (or re-define) configuration locally in
|
||
<code>docker-compose.yml</code>:</p>
|
||
|
||
<pre><code>web:
|
||
extends:
|
||
file: common-services.yml
|
||
service: webapp
|
||
environment:
|
||
- DEBUG=1
|
||
cpu_shares: 5
|
||
|
||
important_web:
|
||
extends: web
|
||
cpu_shares: 10
|
||
</code></pre>
|
||
|
||
<p>You can also write other services and link your <code>web</code> service to them:</p>
|
||
|
||
<pre><code>web:
|
||
extends:
|
||
file: common-services.yml
|
||
service: webapp
|
||
environment:
|
||
- DEBUG=1
|
||
cpu_shares: 5
|
||
links:
|
||
- db
|
||
db:
|
||
image: postgres
|
||
</code></pre>
|
||
|
||
<h3 id="example-use-case-1">Example use case</h3>
|
||
|
||
<p>Extending an individual service is useful when you have multiple services that
|
||
have a common configuration. The example below is a Compose app with
|
||
two services: a web application and a queue worker. Both services use the same
|
||
codebase and share many configuration options.</p>
|
||
|
||
<p>In a <strong>common.yml</strong> we define the common configuration:</p>
|
||
|
||
<pre><code>app:
|
||
build: .
|
||
environment:
|
||
CONFIG_FILE_PATH: /code/config
|
||
API_KEY: xxxyyy
|
||
cpu_shares: 5
|
||
</code></pre>
|
||
|
||
<p>In a <strong>docker-compose.yml</strong> we define the concrete services which use the
|
||
common configuration:</p>
|
||
|
||
<pre><code>webapp:
|
||
extends:
|
||
file: common.yml
|
||
service: app
|
||
command: /code/run_web_app
|
||
ports:
|
||
- 8080:8080
|
||
links:
|
||
- queue
|
||
- db
|
||
|
||
queue_worker:
|
||
extends:
|
||
file: common.yml
|
||
service: app
|
||
command: /code/run_worker
|
||
links:
|
||
- queue
|
||
</code></pre>
|
||
|
||
<h2 id="adding-and-overriding-configuration">Adding and overriding configuration</h2>
|
||
|
||
<p>Compose copies configurations from the original service over to the local one,
|
||
<strong>except</strong> for <code>links</code> and <code>volumes_from</code>. These exceptions exist to avoid
|
||
implicit dependencies&mdash;you always define <code>links</code> and <code>volumes_from</code>
|
||
locally. This ensures dependencies between services are clearly visible when
|
||
reading the current file. Defining these locally also ensures changes to the
|
||
referenced file don&rsquo;t result in breakage.</p>
|
||
|
||
<p>If a configuration option is defined in both the original service the local
|
||
service, the local value <em>replaces</em> or <em>extends</em> the original value.</p>
|
||
|
||
<p>For single-value options like <code>image</code>, <code>command</code> or <code>mem_limit</code>, the new value
|
||
replaces the old value.</p>
|
||
|
||
<pre><code># original service
|
||
command: python app.py
|
||
|
||
# local service
|
||
command: python otherapp.py
|
||
|
||
# result
|
||
command: python otherapp.py
|
||
</code></pre>
|
||
|
||
<p>In the case of <code>build</code> and <code>image</code>, using one in the local service causes
|
||
Compose to discard the other, if it was defined in the original service.</p>
|
||
|
||
<p>Example of image replacing build:</p>
|
||
|
||
<pre><code># original service
|
||
build: .
|
||
|
||
# local service
|
||
image: redis
|
||
|
||
# result
|
||
image: redis
|
||
</code></pre>
|
||
|
||
<p>Example of build replacing image:</p>
|
||
|
||
<pre><code># original service
|
||
image: redis
|
||
|
||
# local service
|
||
build: .
|
||
|
||
# result
|
||
build: .
|
||
</code></pre>
|
||
|
||
<p>For the <strong>multi-value options</strong> <code>ports</code>, <code>expose</code>, <code>external_links</code>, <code>dns</code> and
|
||
<code>dns_search</code>, Compose concatenates both sets of values:</p>
|
||
|
||
<pre><code># original service
|
||
expose:
|
||
- &quot;3000&quot;
|
||
|
||
# local service
|
||
expose:
|
||
- &quot;4000&quot;
|
||
- &quot;5000&quot;
|
||
|
||
# result
|
||
expose:
|
||
- &quot;3000&quot;
|
||
- &quot;4000&quot;
|
||
- &quot;5000&quot;
|
||
</code></pre>
|
||
|
||
<p>In the case of <code>environment</code>, <code>labels</code>, <code>volumes</code> and <code>devices</code>, Compose
|
||
&ldquo;merges&rdquo; entries together with locally-defined values taking precedence:</p>
|
||
|
||
<pre><code># original service
|
||
environment:
|
||
- FOO=original
|
||
- BAR=original
|
||
|
||
# local service
|
||
environment:
|
||
- BAR=local
|
||
- BAZ=local
|
||
|
||
# result
|
||
environment:
|
||
- FOO=original
|
||
- BAR=local
|
||
- BAZ=local
|
||
</code></pre>
|
||
|
||
<h2 id="compose-documentation">Compose documentation</h2>
|
||
|
||
<ul>
|
||
<li><a href="../">User guide</a></li>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/gettingstarted/">Getting Started</a></li>
|
||
<li><a href="../compose/django/">Get started with Django</a></li>
|
||
<li><a href="../compose/rails/">Get started with Rails</a></li>
|
||
<li><a href="../compose/wordpress/">Get started with WordPress</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Getting Started</title>
|
||
<link>http://localhost/compose/gettingstarted/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/gettingstarted/</guid>
|
||
<description>
|
||
|
||
<h1 id="getting-started">Getting Started</h1>
|
||
|
||
<p>On this page you build a simple Python web application running on Compose. The
|
||
application uses the Flask framework and increments a value in Redis. While the
|
||
sample uses Python, the concepts demonstrated here should be understandable even
|
||
if you&rsquo;re not familiar with it.</p>
|
||
|
||
<h2 id="prerequisites">Prerequisites</h2>
|
||
|
||
<p>Make sure you have already
|
||
<a href="../compose/install/">installed both Docker Engine and Docker Compose</a>. You
|
||
don&rsquo;t need to install Python, it is provided by a Docker image.</p>
|
||
|
||
<h2 id="step-1-setup">Step 1: Setup</h2>
|
||
|
||
<ol>
|
||
<li><p>Create a directory for the project:</p>
|
||
|
||
<pre><code>$ mkdir composetest
|
||
$ cd composetest
|
||
</code></pre></li>
|
||
|
||
<li><p>With your favorite text editor create a file called <code>app.py</code> in your project
|
||
directory.</p>
|
||
|
||
<pre><code>from flask import Flask
|
||
from redis import Redis
|
||
|
||
|
||
app = Flask(__name__)
|
||
redis = Redis(host='redis', port=6379)
|
||
|
||
|
||
@app.route('/')
|
||
def hello():
|
||
redis.incr('hits')
|
||
return 'Hello World! I have been seen %s times.' % redis.get('hits')
|
||
|
||
|
||
if __name__ == &quot;__main__&quot;:
|
||
app.run(host=&quot;0.0.0.0&quot;, debug=True)
|
||
</code></pre></li>
|
||
|
||
<li><p>Create another file called <code>requirements.txt</code> in your project directory and
|
||
add the following:</p>
|
||
|
||
<pre><code>flask
|
||
redis
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<p>These define the applications dependencies.</p>
|
||
|
||
<h2 id="step-2-create-a-docker-image">Step 2: Create a Docker image</h2>
|
||
|
||
<p>In this step, you build a new Docker image. The image contains all the
|
||
dependencies the Python application requires, including Python itself.</p>
|
||
|
||
<ol>
|
||
<li><p>In your project directory create a file named <code>Dockerfile</code> and add the
|
||
following:</p>
|
||
|
||
<pre><code>FROM python:2.7
|
||
ADD . /code
|
||
WORKDIR /code
|
||
RUN pip install -r requirements.txt
|
||
CMD python app.py
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<p>This tells Docker to:</p>
|
||
|
||
<ul>
|
||
<li>Build an image starting with the Python 2.7 image.</li>
|
||
<li>Add the current directory <code>.</code> into the path <code>/code</code> in the image.</li>
|
||
<li>Set the working directory to <code>/code</code>.</li>
|
||
<li>Install the Python dependencies.</li>
|
||
<li>Set the default command for the container to <code>python app.py</code></li>
|
||
</ul>
|
||
|
||
<p>For more information on how to write Dockerfiles, see the <a href="https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile">Docker user guide</a> and the <a href="http://docs.docker.com/reference/builder/">Dockerfile reference</a>.</p>
|
||
|
||
<ol>
|
||
<li><p>Build the image.</p>
|
||
|
||
<pre><code>$ docker build -t web .
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<p>This command builds an image named <code>web</code> from the contents of the current
|
||
directory. The command automatically locates the <code>Dockerfile</code>, <code>app.py</code>, and
|
||
<code>requirements.txt</code> files.</p>
|
||
|
||
<h2 id="step-3-define-services">Step 3: Define services</h2>
|
||
|
||
<p>Define a set of services using <code>docker-compose.yml</code>:</p>
|
||
|
||
<ol>
|
||
<li><p>Create a file called docker-compose.yml in your project directory and add
|
||
the following:</p>
|
||
|
||
<pre><code>web:
|
||
build: .
|
||
ports:
|
||
- &quot;5000:5000&quot;
|
||
volumes:
|
||
- .:/code
|
||
links:
|
||
- redis
|
||
redis:
|
||
image: redis
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<p>This Compose file defines two services, <code>web</code> and <code>redis</code>. The web service:</p>
|
||
|
||
<ul>
|
||
<li>Builds from the <code>Dockerfile</code> in the current directory.</li>
|
||
<li>Forwards the exposed port 5000 on the container to port 5000 on the host machine.</li>
|
||
<li>Mounts the project directory on the host to <code>/code</code> inside the container allowing you to modify the code without having to rebuild the image.</li>
|
||
<li>Links the web service to the Redis service.</li>
|
||
</ul>
|
||
|
||
<p>The <code>redis</code> service uses the latest public <a href="https://registry.hub.docker.com/_/redis/">Redis</a> image pulled from the Docker Hub registry.</p>
|
||
|
||
<h2 id="step-4-build-and-run-your-app-with-compose">Step 4: Build and run your app with Compose</h2>
|
||
|
||
<ol>
|
||
<li><p>From your project directory, start up your application.</p>
|
||
|
||
<pre><code>$ docker-compose up
|
||
Pulling image redis...
|
||
Building web...
|
||
Starting composetest_redis_1...
|
||
Starting composetest_web_1...
|
||
redis_1 | [8] 02 Jan 18:43:35.576 # Server started, Redis version 2.8.3
|
||
web_1 | * Running on http://0.0.0.0:5000/
|
||
web_1 | * Restarting with stat
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<p>Compose pulls a Redis image, builds an image for your code, and start the
|
||
services you defined.</p>
|
||
|
||
<ol>
|
||
<li>Enter <code>http://0.0.0.0:5000/</code> in a browser to see the application running.</li>
|
||
</ol>
|
||
|
||
<p>If you&rsquo;re using Docker on Linux natively, then the web app should now be
|
||
listening on port 5000 on your Docker daemon host. If <a href="http://0.0.0.0:5000">http://0.0.0.0:5000</a>
|
||
doesn&rsquo;t resolve, you can also try <a href="http://localhost:5000">http://localhost:5000</a>.</p>
|
||
|
||
<p>If you&rsquo;re using Docker Machine on a Mac, use <code>docker-machine ip MACHINE_VM</code> to get
|
||
the IP address of your Docker host. Then, <code>open http://MACHINE_VM_IP:5000</code> in a
|
||
browser.</p>
|
||
|
||
<p>You should see a message in your browser saying:</p>
|
||
|
||
<p><code>Hello World! I have been seen 1 times.</code></p>
|
||
|
||
<ol>
|
||
<li>Refresh the page.</li>
|
||
</ol>
|
||
|
||
<p>The number should increment.</p>
|
||
|
||
<h2 id="step-5-experiment-with-some-other-commands">Step 5: Experiment with some other commands</h2>
|
||
|
||
<p>If you want to run your services in the background, you can pass the <code>-d</code> flag
|
||
(for &ldquo;detached&rdquo; mode) to <code>docker-compose up</code> and use <code>docker-compose ps</code> to
|
||
see what is currently running:</p>
|
||
|
||
<pre><code> $ docker-compose up -d
|
||
Starting composetest_redis_1...
|
||
Starting composetest_web_1...
|
||
$ docker-compose ps
|
||
Name Command State Ports
|
||
-------------------------------------------------------------------
|
||
composetest_redis_1 /usr/local/bin/run Up
|
||
composetest_web_1 /bin/sh -c python app.py Up 5000-&gt;5000/tcp
|
||
</code></pre>
|
||
|
||
<p>The <code>docker-compose run</code> command allows you to run one-off commands for your
|
||
services. For example, to see what environment variables are available to the
|
||
<code>web</code> service:</p>
|
||
|
||
<pre><code> $ docker-compose run web env
|
||
</code></pre>
|
||
|
||
<p>See <code>docker-compose --help</code> to see other available commands. You can also install <a href="../compose/completion/">command completion</a> for the bash and zsh shell, which will also show you available commands.</p>
|
||
|
||
<p>If you started Compose with <code>docker-compose up -d</code>, you&rsquo;ll probably want to stop
|
||
your services once you&rsquo;ve finished with them:</p>
|
||
|
||
<pre><code> $ docker-compose stop
|
||
</code></pre>
|
||
|
||
<p>At this point, you have seen the basics of how Compose works.</p>
|
||
|
||
<h2 id="where-to-go-next">Where to go next</h2>
|
||
|
||
<ul>
|
||
<li>Next, try the quick start guide for <a href="../compose/django/">Django</a>,
|
||
<a href="../compose/rails/">Rails</a>, or <a href="../compose/wordpress/">WordPress</a>.</li>
|
||
<li><a href="../compose/reference/">Explore the full list of Compose commands</a></li>
|
||
<li><a href="../compose/compose-file/">Compose configuration file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Introduction to the CLI</title>
|
||
<link>http://localhost/compose/reference/overview/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/reference/overview/</guid>
|
||
<description>
|
||
|
||
<h1 id="introduction-to-the-cli">Introduction to the CLI</h1>
|
||
|
||
<p>This section describes the subcommands you can use with the <code>docker-compose</code> command. You can run subcommand against one or more services. To run against a specific service, you supply the service name from your compose configuration. If you do not specify the service name, the command runs against all the services in your configuration.</p>
|
||
|
||
<h2 id="commands">Commands</h2>
|
||
|
||
<ul>
|
||
<li><a href="../compose/reference/docker-compose/">docker-compose Command</a></li>
|
||
<li><a href="../compose/reference/">CLI Reference</a></li>
|
||
</ul>
|
||
|
||
<h2 id="environment-variables">Environment Variables</h2>
|
||
|
||
<p>Several environment variables are available for you to configure the Docker Compose command-line behaviour.</p>
|
||
|
||
<p>Variables starting with <code>DOCKER_</code> are the same as those used to configure the
|
||
Docker command-line client. If you&rsquo;re using <code>docker-machine</code>, then the <code>eval &quot;$(docker-machine env my-docker-vm)&quot;</code> command should set them to their correct values. (In this example, <code>my-docker-vm</code> is the name of a machine you created.)</p>
|
||
|
||
<h3 id="compose-project-name">COMPOSE_PROJECT_NAME</h3>
|
||
|
||
<p>Sets the project name. This value is prepended along with the service name to the container container on start up. For example, if you project name is <code>myapp</code> and it includes two services <code>db</code> and <code>web</code> then compose starts containers named <code>myapp_db_1</code> and <code>myapp_web_1</code> respectively.</p>
|
||
|
||
<p>Setting this is optional. If you do not set this, the <code>COMPOSE_PROJECT_NAME</code> defaults to the <code>basename</code> of the current working directory.</p>
|
||
|
||
<h3 id="compose-file">COMPOSE_FILE</h3>
|
||
|
||
<p>Specify the file containing the compose configuration. If not provided, Compose looks for a file named <code>docker-compose.yml</code> in the current directory and then each parent directory in succession until a file by that name is found.</p>
|
||
|
||
<h3 id="compose-api-version">COMPOSE_API_VERSION</h3>
|
||
|
||
<p>The Docker API only supports requests from clients which report a specific
|
||
version. If you receive a <code>client and server don't have same version error</code> using
|
||
<code>docker-compose</code>, you can workaround this error by setting this environment
|
||
variable. Set the version value to match the server version.</p>
|
||
|
||
<p>Setting this variable is intended as a workaround for situations where you need
|
||
to run temporarily with a mismatch between the client and server version. For
|
||
example, if you can upgrade the client but need to wait to upgrade the server.</p>
|
||
|
||
<p>Running with this variable set and a known mismatch does prevent some Docker
|
||
features from working properly. The exact features that fail would depend on the
|
||
Docker client and server versions. For this reason, running with this variable
|
||
set is only intended as a workaround and it is not officially supported.</p>
|
||
|
||
<p>If you run into problems running with this set, resolve the mismatch through
|
||
upgrade and remove this setting to see if your problems resolve before notifying
|
||
support.</p>
|
||
|
||
<h3 id="docker-host">DOCKER_HOST</h3>
|
||
|
||
<p>Sets the URL of the <code>docker</code> daemon. As with the Docker client, defaults to <code>unix:///var/run/docker.sock</code>.</p>
|
||
|
||
<h3 id="docker-tls-verify">DOCKER_TLS_VERIFY</h3>
|
||
|
||
<p>When set to anything other than an empty string, enables TLS communication with
|
||
the <code>docker</code> daemon.</p>
|
||
|
||
<h3 id="docker-cert-path">DOCKER_CERT_PATH</h3>
|
||
|
||
<p>Configures the path to the <code>ca.pem</code>, <code>cert.pem</code>, and <code>key.pem</code> files used for TLS verification. Defaults to <code>~/.docker</code>.</p>
|
||
|
||
<h3 id="compose-http-timeout">COMPOSE_HTTP_TIMEOUT</h3>
|
||
|
||
<p>Configures the time (in seconds) a request to the Docker daemon is allowed to hang before Compose considers
|
||
it failed. Defaults to 60 seconds.</p>
|
||
|
||
<h2 id="related-information">Related Information</h2>
|
||
|
||
<ul>
|
||
<li><a href="../compose/">User guide</a></li>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Networking in Compose</title>
|
||
<link>http://localhost/compose/networking/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/networking/</guid>
|
||
<description>
|
||
|
||
<h1 id="networking-in-compose">Networking in Compose</h1>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong> Compose&rsquo;s networking support is experimental, and must be explicitly enabled with the <code>docker-compose --x-networking</code> flag.</p>
|
||
</blockquote>
|
||
|
||
<p>Compose sets up a single default
|
||
<a href="../engine/reference/commandline/network_create/">network</a> for your app. Each
|
||
container for a service joins the default network and is both <em>reachable</em> by
|
||
other containers on that network, and <em>discoverable</em> by them at a hostname
|
||
identical to the container name.</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong> Your app&rsquo;s network is given the same name as the &ldquo;project name&rdquo;, which is based on the name of the directory it lives in. See the <a href="../compose/reference/docker-compose/">Command line overview</a> for how to override it.</p>
|
||
</blockquote>
|
||
|
||
<p>For example, suppose your app is in a directory called <code>myapp</code>, and your <code>docker-compose.yml</code> looks like this:</p>
|
||
|
||
<pre><code>web:
|
||
build: .
|
||
ports:
|
||
- &quot;8000:8000&quot;
|
||
db:
|
||
image: postgres
|
||
</code></pre>
|
||
|
||
<p>When you run <code>docker-compose --x-networking up</code>, the following happens:</p>
|
||
|
||
<ol>
|
||
<li>A network called <code>myapp</code> is created.</li>
|
||
<li>A container is created using <code>web</code>&rsquo;s configuration. It joins the network
|
||
<code>myapp</code> under the name <code>myapp_web_1</code>.</li>
|
||
<li>A container is created using <code>db</code>&rsquo;s configuration. It joins the network
|
||
<code>myapp</code> under the name <code>myapp_db_1</code>.</li>
|
||
</ol>
|
||
|
||
<p>Each container can now look up the hostname <code>myapp_web_1</code> or <code>myapp_db_1</code> and
|
||
get back the appropriate container&rsquo;s IP address. For example, <code>web</code>&rsquo;s
|
||
application code could connect to the URL <code>postgres://myapp_db_1:5432</code> and start
|
||
using the Postgres database.</p>
|
||
|
||
<p>Because <code>web</code> explicitly maps a port, it&rsquo;s also accessible from the outside world via port 8000 on your Docker host&rsquo;s network interface.</p>
|
||
|
||
<blockquote>
|
||
<p><strong>Note:</strong> in the next release there will be additional aliases for the
|
||
container, including a short name without the project name and container
|
||
index. The full container name will remain as one of the alias for backwards
|
||
compatibility.</p>
|
||
</blockquote>
|
||
|
||
<h2 id="updating-containers">Updating containers</h2>
|
||
|
||
<p>If you make a configuration change to a service and run <code>docker-compose up</code> to update it, the old container will be removed and the new one will join the network under a different IP address but the same name. Running containers will be able to look up that name and connect to the new address, but the old address will stop working.</p>
|
||
|
||
<p>If any containers have connections open to the old container, they will be closed. It is a container&rsquo;s responsibility to detect this condition, look up the name again and reconnect.</p>
|
||
|
||
<h2 id="configure-how-services-are-published">Configure how services are published</h2>
|
||
|
||
<p>By default, containers for each service are published on the network with the
|
||
container name. If you want to change the name, or stop containers from being
|
||
discoverable at all, you can use the <code>container_name</code> option:</p>
|
||
|
||
<pre><code>web:
|
||
build: .
|
||
container_name: &quot;my-web-application&quot;
|
||
</code></pre>
|
||
|
||
<h2 id="links">Links</h2>
|
||
|
||
<p>Docker links are a one-way, single-host communication system. They should now be considered deprecated, and you should update your app to use networking instead. In the majority of cases, this will simply involve removing the <code>links</code> sections from your <code>docker-compose.yml</code>.</p>
|
||
|
||
<h2 id="specifying-the-network-driver">Specifying the network driver</h2>
|
||
|
||
<p>By default, Compose uses the <code>bridge</code> driver when creating the app’s network. The Docker Engine provides one other driver out-of-the-box: <code>overlay</code>, which implements secure communication between containers on different hosts (see the next section for how to set up and use the <code>overlay</code> driver). Docker also allows you to install <a href="../engine/extend/plugins_network/">custom network drivers</a>.</p>
|
||
|
||
<p>You can specify which one to use with the <code>--x-network-driver</code> flag:</p>
|
||
|
||
<pre><code>$ docker-compose --x-networking --x-network-driver=overlay up
|
||
</code></pre>
|
||
|
||
<h2 id="multi-host-networking">Multi-host networking</h2>
|
||
|
||
<p>(TODO: talk about Swarm and the overlay driver)</p>
|
||
|
||
<h2 id="custom-container-network-modes">Custom container network modes</h2>
|
||
|
||
<p>Compose allows you to specify a custom network mode for a service with the <code>net</code> option - for example, <code>net: &quot;host&quot;</code> specifies that its containers should use the same network namespace as the Docker host, and <code>net: &quot;none&quot;</code> specifies that they should have no networking capabilities.</p>
|
||
|
||
<p>If a service specifies the <code>net</code> option, its containers will <em>not</em> join the app’s network and will not be able to communicate with other services in the app.</p>
|
||
|
||
<p>If <em>all</em> services in an app specify the <code>net</code> option, a network will not be created at all.</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Overview of Docker Compose</title>
|
||
<link>http://localhost/compose/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/</guid>
|
||
<description>
|
||
|
||
<h1 id="overview-of-docker-compose">Overview of Docker Compose</h1>
|
||
|
||
<p>Compose is a tool for defining and running multi-container Docker applications.
|
||
With Compose, you use a Compose file to configure your application&rsquo;s services.
|
||
Then, using a single command, you create and start all the services
|
||
from your configuration. To learn more about all the features of Compose
|
||
see <a href="#features">the list of features</a>.</p>
|
||
|
||
<p>Compose is great for development, testing, and staging environments, as well as
|
||
CI workflows. You can learn more about each case in
|
||
<a href="#common-use-cases">Common Use Cases</a>.</p>
|
||
|
||
<p>Using Compose is basically a three-step process.</p>
|
||
|
||
<ol>
|
||
<li>Define your app&rsquo;s environment with a <code>Dockerfile</code> so it can be
|
||
reproduced anywhere.</li>
|
||
<li>Define the services that make up your app in <code>docker-compose.yml</code> so
|
||
they can be run together in an isolated environment.</li>
|
||
<li>Lastly, run <code>docker-compose up</code> and Compose will start and run your entire app.</li>
|
||
</ol>
|
||
|
||
<p>A <code>docker-compose.yml</code> looks like this:</p>
|
||
|
||
<pre><code>web:
|
||
build: .
|
||
ports:
|
||
- &quot;5000:5000&quot;
|
||
volumes:
|
||
- .:/code
|
||
links:
|
||
- redis
|
||
redis:
|
||
image: redis
|
||
</code></pre>
|
||
|
||
<p>For more information about the Compose file, see the
|
||
<a href="../compose/compose-file/">Compose file reference</a></p>
|
||
|
||
<p>Compose has commands for managing the whole lifecycle of your application:</p>
|
||
|
||
<ul>
|
||
<li>Start, stop and rebuild services</li>
|
||
<li>View the status of running services</li>
|
||
<li>Stream the log output of running services</li>
|
||
<li>Run a one-off command on a service</li>
|
||
</ul>
|
||
|
||
<h2 id="compose-documentation">Compose documentation</h2>
|
||
|
||
<ul>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/gettingstarted/">Getting Started</a></li>
|
||
<li><a href="../compose/django/">Get started with Django</a></li>
|
||
<li><a href="../compose/rails/">Get started with Rails</a></li>
|
||
<li><a href="../compose/wordpress/">Get started with WordPress</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
|
||
<h2 id="features">Features</h2>
|
||
|
||
<p>The features of Compose that make it effective are:</p>
|
||
|
||
<ul>
|
||
<li><a href="#Multiple-isolated-environments-on-a-single-host">Multiple isolated environments on a single host</a></li>
|
||
<li><a href="#preserve-volume-data-when-containers-are-created">Preserve volume data when containers are created</a></li>
|
||
<li><a href="#only-recreate-containers-that-have-changed">Only recreate containers that have changed</a></li>
|
||
<li><a href="#variables-and-moving-a-composition-between-environments">Variables and moving a composition between environments</a></li>
|
||
</ul>
|
||
|
||
<h4 id="multiple-isolated-environments-on-a-single-host">Multiple isolated environments on a single host</h4>
|
||
|
||
<p>Compose uses a project name to isolate environments from each other. You can use
|
||
this project name to:</p>
|
||
|
||
<ul>
|
||
<li>on a dev host, to create multiple copies of a single environment (ex: you want
|
||
to run a stable copy for each feature branch of a project)</li>
|
||
<li>on a CI server, to keep builds from interfering with each other, you can set
|
||
the project name to a unique build number</li>
|
||
<li>on a shared host or dev host, to prevent different projects which may use the
|
||
same service names, from interfering with each other</li>
|
||
</ul>
|
||
|
||
<p>The default project name is the basename of the project directory. You can set
|
||
a custom project name by using the
|
||
<a href="../compose/reference/docker-compose/"><code>-p</code> command line option</a> or the
|
||
<a href="../compose/reference/overview/#compose-project-name"><code>COMPOSE_PROJECT_NAME</code> environment variable</a>.</p>
|
||
|
||
<h4 id="preserve-volume-data-when-containers-are-created">Preserve volume data when containers are created</h4>
|
||
|
||
<p>Compose preserves all volumes used by your services. When <code>docker-compose up</code>
|
||
runs, if it finds any containers from previous runs, it copies the volumes from
|
||
the old container to the new container. This process ensures that any data
|
||
you&rsquo;ve created in volumes isn&rsquo;t lost.</p>
|
||
|
||
<h4 id="only-recreate-containers-that-have-changed">Only recreate containers that have changed</h4>
|
||
|
||
<p>Compose caches the configuration used to create a container. When you
|
||
restart a service that has not changed, Compose re-uses the existing
|
||
containers. Re-using containers means that you can make changes to your
|
||
environment very quickly.</p>
|
||
|
||
<h4 id="variables-and-moving-a-composition-between-environments">Variables and moving a composition between environments</h4>
|
||
|
||
<p>Compose supports variables in the Compose file. You can use these variables
|
||
to customize your composition for different environments, or different users.
|
||
See <a href="../compose/compose-file/#variable-substitution">Variable substitution</a> for more
|
||
details.</p>
|
||
|
||
<p>You can extend a Compose file using the <code>extends</code> field or by creating multiple
|
||
Compose files. See <a href="../compose/extends/">extends</a> for more details.</p>
|
||
|
||
<h2 id="common-use-cases">Common Use Cases</h2>
|
||
|
||
<p>Compose can be used in many different ways. Some common use cases are outlined
|
||
below.</p>
|
||
|
||
<h3 id="development-environments">Development environments</h3>
|
||
|
||
<p>When you&rsquo;re developing software, the ability to run an application in an
|
||
isolated environment and interact with it is crucial. The Compose command
|
||
line tool can be used to create the environment and interact with it.</p>
|
||
|
||
<p>The <a href="../compose/compose-file/">Compose file</a> provides a way to document and configure
|
||
all of the application&rsquo;s service dependencies (databases, queues, caches,
|
||
web service APIs, etc). Using the Compose command line tool you can create
|
||
and start one or more containers for each dependency with a single command
|
||
(<code>docker-compose up</code>).</p>
|
||
|
||
<p>Together, these features provide a convenient way for developers to get
|
||
started on a project. Compose can reduce a multi-page &ldquo;developer getting
|
||
started guide&rdquo; to a single machine readable Compose file and a few commands.</p>
|
||
|
||
<h3 id="automated-testing-environments">Automated testing environments</h3>
|
||
|
||
<p>An important part of any Continuous Deployment or Continuous Integration process
|
||
is the automated test suite. Automated end-to-end testing requires an
|
||
environment in which to run tests. Compose provides a convenient way to create
|
||
and destroy isolated testing environments for your test suite. By defining the full
|
||
environment in a <a href="../compose/compose-file/">Compose file</a> you can create and destroy these
|
||
environments in just a few commands:</p>
|
||
|
||
<pre><code>$ docker-compose up -d
|
||
$ ./run_tests
|
||
$ docker-compose stop
|
||
$ docker-compose rm -f
|
||
</code></pre>
|
||
|
||
<h3 id="single-host-deployments">Single host deployments</h3>
|
||
|
||
<p>Compose has traditionally been focused on development and testing workflows,
|
||
but with each release we&rsquo;re making progress on more production-oriented features.
|
||
You can use Compose to deploy to a remote Docker Engine. The Docker Engine may
|
||
be a single instance provisioned with
|
||
<a href="https://docs.docker.com/machine/">Docker Machine</a> or an entire
|
||
<a href="https://docs.docker.com/swarm/">Docker Swarm</a> cluster.</p>
|
||
|
||
<p>For details on using production-oriented features, see
|
||
<a href="../compose/production/">compose in production</a> in this documentation.</p>
|
||
|
||
<h2 id="release-notes">Release Notes</h2>
|
||
|
||
<p>To see a detailed list of changes for past and current releases of Docker
|
||
Compose, please refer to the
|
||
<a href="https://github.com/docker/compose/blob/master/CHANGELOG.md">CHANGELOG</a>.</p>
|
||
|
||
<h2 id="getting-help">Getting help</h2>
|
||
|
||
<p>Docker Compose is under active development. If you need help, would like to
|
||
contribute, or simply want to talk about the project with like-minded
|
||
individuals, we have a number of open channels for communication.</p>
|
||
|
||
<ul>
|
||
<li><p>To report bugs or file feature requests: please use the <a href="https://github.com/docker/compose/issues">issue tracker on Github</a>.</p></li>
|
||
|
||
<li><p>To talk about the project with people in real time: please join the
|
||
<code>#docker-compose</code> channel on freenode IRC.</p></li>
|
||
|
||
<li><p>To contribute code or documentation changes: please submit a <a href="https://github.com/docker/compose/pulls">pull request on Github</a>.</p></li>
|
||
</ul>
|
||
|
||
<p>For more information and resources, please visit the <a href="https://docs.docker.com/project/get-help/">Getting Help project page</a>.</p>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Quickstart Guide: Compose and Django</title>
|
||
<link>http://localhost/compose/django/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/django/</guid>
|
||
<description>
|
||
|
||
<h1 id="quickstart-guide-compose-and-django">Quickstart Guide: Compose and Django</h1>
|
||
|
||
<p>This quick-start guide demonstrates how to use Compose to set up and run a
|
||
simple Django/PostgreSQL app. Before starting, you&rsquo;ll need to have
|
||
<a href="../compose/install/">Compose installed</a>.</p>
|
||
|
||
<h2 id="define-the-project-components">Define the project components</h2>
|
||
|
||
<p>For this project, you need to create a Dockerfile, a Python dependencies file,
|
||
and a <code>docker-compose.yml</code> file.</p>
|
||
|
||
<ol>
|
||
<li><p>Create an empty project directory.</p>
|
||
|
||
<p>You can name the directory something easy for you to remember. This directory is the context for your application image. The directory should only contain resources to build that image.</p></li>
|
||
|
||
<li><p>Create a new file called <code>Dockerfile</code> in your project directory.</p>
|
||
|
||
<p>The Dockerfile defines an application&rsquo;s image content via one or more build
|
||
commands that configure that image. Once built, you can run the image in a
|
||
container. For more information on <code>Dockerfiles</code>, see the <a href="https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile">Docker user
|
||
guide</a>
|
||
and the <a href="http://docs.docker.com/reference/builder/">Dockerfile reference</a>.</p></li>
|
||
|
||
<li><p>Add the following content to the <code>Dockerfile</code>.</p>
|
||
|
||
<pre><code>FROM python:2.7
|
||
ENV PYTHONUNBUFFERED 1
|
||
RUN mkdir /code
|
||
WORKDIR /code
|
||
ADD requirements.txt /code/
|
||
RUN pip install -r requirements.txt
|
||
ADD . /code/
|
||
</code></pre>
|
||
|
||
<p>This <code>Dockerfile</code> starts with a Python 2.7 base image. The base image is
|
||
modified by adding a new <code>code</code> directory. The base image is further modified
|
||
by installing the Python requirements defined in the <code>requirements.txt</code> file.</p></li>
|
||
|
||
<li><p>Save and close the <code>Dockerfile</code>.</p></li>
|
||
|
||
<li><p>Create a <code>requirements.txt</code> in your project directory.</p>
|
||
|
||
<p>This file is used by the <code>RUN pip install -r requirements.txt</code> command in your <code>Dockerfile</code>.</p></li>
|
||
|
||
<li><p>Add the required software in the file.</p>
|
||
|
||
<pre><code>Django
|
||
psycopg2
|
||
</code></pre></li>
|
||
|
||
<li><p>Save and close the <code>requirements.txt</code> file.</p></li>
|
||
|
||
<li><p>Create a file called <code>docker-compose.yml</code> in your project directory.</p>
|
||
|
||
<p>The <code>docker-compose.yml</code> file describes the services that make your app. In
|
||
this example those services are a web server and database. The compose file
|
||
also describes which Docker images these services use, how they link
|
||
together, any volumes they might need mounted inside the containers.
|
||
Finally, the <code>docker-compose.yml</code> file describes which ports these services
|
||
expose. See the <a href="../compose/compose-file/"><code>docker-compose.yml</code> reference</a> for more
|
||
information on how this file works.</p></li>
|
||
|
||
<li><p>Add the following configuration to the file.</p>
|
||
|
||
<pre><code>db:
|
||
image: postgres
|
||
web:
|
||
build: .
|
||
command: python manage.py runserver 0.0.0.0:8000
|
||
volumes:
|
||
- .:/code
|
||
ports:
|
||
- &quot;8000:8000&quot;
|
||
links:
|
||
- db
|
||
</code></pre>
|
||
|
||
<p>This file defines two services: The <code>db</code> service and the <code>web</code> service.</p></li>
|
||
|
||
<li><p>Save and close the <code>docker-compose.yml</code> file.</p></li>
|
||
</ol>
|
||
|
||
<h2 id="create-a-django-project">Create a Django project</h2>
|
||
|
||
<p>In this step, you create a Django started project by building the image from the build context defined in the previous procedure.</p>
|
||
|
||
<ol>
|
||
<li><p>Change to the root of your project directory.</p></li>
|
||
|
||
<li><p>Create the Django project using the <code>docker-compose</code> command.</p>
|
||
|
||
<pre><code>$ docker-compose run web django-admin.py startproject composeexample .
|
||
</code></pre>
|
||
|
||
<p>This instructs Compose to run <code>django-admin.py startproject composeeexample</code>
|
||
in a container, using the <code>web</code> service&rsquo;s image and configuration. Because
|
||
the <code>web</code> image doesn&rsquo;t exist yet, Compose builds it from the current
|
||
directory, as specified by the <code>build: .</code> line in <code>docker-compose.yml</code>.</p>
|
||
|
||
<p>Once the <code>web</code> service image is built, Compose runs it and executes the
|
||
<code>django-admin.py startproject</code> command in the container. This command
|
||
instructs Django to create a set of files and directories representing a
|
||
Django project.</p></li>
|
||
|
||
<li><p>After the <code>docker-compose</code> command completes, list the contents of your project.</p>
|
||
|
||
<pre><code>$ ls -l
|
||
drwxr-xr-x 2 root root composeexample
|
||
-rw-rw-r-- 1 user user docker-compose.yml
|
||
-rw-rw-r-- 1 user user Dockerfile
|
||
-rwxr-xr-x 1 root root manage.py
|
||
-rw-rw-r-- 1 user user requirements.txt
|
||
</code></pre>
|
||
|
||
<p>The files <code>django-admin</code> created are owned by root. This happens because
|
||
the container runs as the <code>root</code> user.</p></li>
|
||
|
||
<li><p>Change the ownership of the new files.</p>
|
||
|
||
<pre><code>sudo chown -R $USER:$USER .
|
||
</code></pre></li>
|
||
</ol>
|
||
|
||
<h2 id="connect-the-database">Connect the database</h2>
|
||
|
||
<p>In this section, you set up the database connection for Django.</p>
|
||
|
||
<ol>
|
||
<li><p>In your project dirctory, edit the <code>composeexample/settings.py</code> file.</p></li>
|
||
|
||
<li><p>Replace the <code>DATABASES = ...</code> with the following:</p>
|
||
|
||
<pre><code>DATABASES = {
|
||
'default': {
|
||
'ENGINE': 'django.db.backends.postgresql_psycopg2',
|
||
'NAME': 'postgres',
|
||
'USER': 'postgres',
|
||
'HOST': 'db',
|
||
'PORT': 5432,
|
||
}
|
||
}
|
||
</code></pre>
|
||
|
||
<p>These settings are determined by the
|
||
<a href="https://registry.hub.docker.com/_/postgres/">postgres</a> Docker image
|
||
specified in <code>docker-compose.yml</code>.</p></li>
|
||
|
||
<li><p>Save and close the file.</p></li>
|
||
|
||
<li><p>Run the <code>docker-compose up</code> command.</p>
|
||
|
||
<pre><code>$ docker-compose up
|
||
Starting composepractice_db_1...
|
||
Starting composepractice_web_1...
|
||
Attaching to composepractice_db_1, composepractice_web_1
|
||
...
|
||
db_1 | PostgreSQL init process complete; ready for start up.
|
||
...
|
||
db_1 | LOG: database system is ready to accept connections
|
||
db_1 | LOG: autovacuum launcher started
|
||
..
|
||
web_1 | Django version 1.8.4, using settings 'composeexample.settings'
|
||
web_1 | Starting development server at http://0.0.0.0:8000/
|
||
web_1 | Quit the server with CONTROL-C.
|
||
</code></pre>
|
||
|
||
<p>At this point, your Django app should be running at port <code>8000</code> on your
|
||
Docker host. If you are using a Docker Machine VM, you can use the
|
||
<code>docker-machine ip MACHINE_NAME</code> to get the IP address.</p></li>
|
||
</ol>
|
||
|
||
<h2 id="more-compose-documentation">More Compose documentation</h2>
|
||
|
||
<ul>
|
||
<li><a href="../">User guide</a></li>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/gettingstarted/">Getting Started</a></li>
|
||
<li><a href="../compose/rails/">Get started with Rails</a></li>
|
||
<li><a href="../compose/wordpress/">Get started with WordPress</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Quickstart Guide: Compose and Rails</title>
|
||
<link>http://localhost/compose/rails/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/rails/</guid>
|
||
<description>
|
||
|
||
<h2 id="quickstart-guide-compose-and-rails">Quickstart Guide: Compose and Rails</h2>
|
||
|
||
<p>This Quickstart guide will show you how to use Compose to set up and run a Rails/PostgreSQL app. Before starting, you&rsquo;ll need to have <a href="../compose/install/">Compose installed</a>.</p>
|
||
|
||
<h3 id="define-the-project">Define the project</h3>
|
||
|
||
<p>Start by setting up the three files you&rsquo;ll need to build the app. First, since
|
||
your app is going to run inside a Docker container containing all of its
|
||
dependencies, you&rsquo;ll need to define exactly what needs to be included in the
|
||
container. This is done using a file called <code>Dockerfile</code>. To begin with, the
|
||
Dockerfile consists of:</p>
|
||
|
||
<pre><code>FROM ruby:2.2.0
|
||
RUN apt-get update -qq &amp;&amp; apt-get install -y build-essential libpq-dev
|
||
RUN mkdir /myapp
|
||
WORKDIR /myapp
|
||
ADD Gemfile /myapp/Gemfile
|
||
ADD Gemfile.lock /myapp/Gemfile.lock
|
||
RUN bundle install
|
||
ADD . /myapp
|
||
</code></pre>
|
||
|
||
<p>That&rsquo;ll put your application code inside an image that will build a container with Ruby, Bundler and all your dependencies inside it. For more information on how to write Dockerfiles, see the <a href="https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile">Docker user guide</a> and the <a href="http://docs.docker.com/reference/builder/">Dockerfile reference</a>.</p>
|
||
|
||
<p>Next, create a bootstrap <code>Gemfile</code> which just loads Rails. It&rsquo;ll be overwritten in a moment by <code>rails new</code>.</p>
|
||
|
||
<pre><code>source 'https://rubygems.org'
|
||
gem 'rails', '4.2.0'
|
||
</code></pre>
|
||
|
||
<p>You&rsquo;ll need an empty <code>Gemfile.lock</code> in order to build our <code>Dockerfile</code>.</p>
|
||
|
||
<pre><code>$ touch Gemfile.lock
|
||
</code></pre>
|
||
|
||
<p>Finally, <code>docker-compose.yml</code> is where the magic happens. This file describes the services that comprise your app (a database and a web app), how to get each one&rsquo;s Docker image (the database just runs on a pre-made PostgreSQL image, and the web app is built from the current directory), and the configuration needed to link them together and expose the web app&rsquo;s port.</p>
|
||
|
||
<pre><code>db:
|
||
image: postgres
|
||
web:
|
||
build: .
|
||
command: bundle exec rails s -p 3000 -b '0.0.0.0'
|
||
volumes:
|
||
- .:/myapp
|
||
ports:
|
||
- &quot;3000:3000&quot;
|
||
links:
|
||
- db
|
||
</code></pre>
|
||
|
||
<h3 id="build-the-project">Build the project</h3>
|
||
|
||
<p>With those three files in place, you can now generate the Rails skeleton app
|
||
using <code>docker-compose run</code>:</p>
|
||
|
||
<pre><code>$ docker-compose run web rails new . --force --database=postgresql --skip-bundle
|
||
</code></pre>
|
||
|
||
<p>First, Compose will build the image for the <code>web</code> service using the
|
||
<code>Dockerfile</code>. Then it&rsquo;ll run <code>rails new</code> inside a new container, using that
|
||
image. Once it&rsquo;s done, you should have generated a fresh app:</p>
|
||
|
||
<pre><code>$ ls
|
||
Dockerfile app docker-compose.yml tmp
|
||
Gemfile bin lib vendor
|
||
Gemfile.lock config log
|
||
README.rdoc config.ru public
|
||
Rakefile db test
|
||
</code></pre>
|
||
|
||
<p>The files <code>rails new</code> created are owned by root. This happens because the
|
||
container runs as the <code>root</code> user. Change the ownership of the new files.</p>
|
||
|
||
<pre><code>sudo chown -R $USER:$USER .
|
||
</code></pre>
|
||
|
||
<p>Uncomment the line in your new <code>Gemfile</code> which loads <code>therubyracer</code>, so you&rsquo;ve
|
||
got a Javascript runtime:</p>
|
||
|
||
<pre><code>gem 'therubyracer', platforms: :ruby
|
||
</code></pre>
|
||
|
||
<p>Now that you&rsquo;ve got a new <code>Gemfile</code>, you need to build the image again. (This,
|
||
and changes to the Dockerfile itself, should be the only times you&rsquo;ll need to
|
||
rebuild.)</p>
|
||
|
||
<pre><code>$ docker-compose build
|
||
</code></pre>
|
||
|
||
<h3 id="connect-the-database">Connect the database</h3>
|
||
|
||
<p>The app is now bootable, but you&rsquo;re not quite there yet. By default, Rails
|
||
expects a database to be running on <code>localhost</code> - so you need to point it at the
|
||
<code>db</code> container instead. You also need to change the database and username to
|
||
align with the defaults set by the <code>postgres</code> image.</p>
|
||
|
||
<p>Replace the contents of <code>config/database.yml</code> with the following:</p>
|
||
|
||
<pre><code>development: &amp;default
|
||
adapter: postgresql
|
||
encoding: unicode
|
||
database: postgres
|
||
pool: 5
|
||
username: postgres
|
||
password:
|
||
host: db
|
||
|
||
test:
|
||
&lt;&lt;: *default
|
||
database: myapp_test
|
||
</code></pre>
|
||
|
||
<p>You can now boot the app with:</p>
|
||
|
||
<pre><code>$ docker-compose up
|
||
</code></pre>
|
||
|
||
<p>If all&rsquo;s well, you should see some PostgreSQL output, and then—after a few
|
||
seconds—the familiar refrain:</p>
|
||
|
||
<pre><code>myapp_web_1 | [2014-01-17 17:16:29] INFO WEBrick 1.3.1
|
||
myapp_web_1 | [2014-01-17 17:16:29] INFO ruby 2.2.0 (2014-12-25) [x86_64-linux-gnu]
|
||
myapp_web_1 | [2014-01-17 17:16:29] INFO WEBrick::HTTPServer#start: pid=1 port=3000
|
||
</code></pre>
|
||
|
||
<p>Finally, you need to create the database. In another terminal, run:</p>
|
||
|
||
<pre><code>$ docker-compose run web rake db:create
|
||
</code></pre>
|
||
|
||
<p>That&rsquo;s it. Your app should now be running on port 3000 on your Docker daemon. If you&rsquo;re using <a href="https://docs.docker.com/machine">Docker Machine</a>, then <code>docker-machine ip MACHINE_VM</code> returns the Docker host IP address.</p>
|
||
|
||
<h2 id="more-compose-documentation">More Compose documentation</h2>
|
||
|
||
<ul>
|
||
<li><a href="../">User guide</a></li>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/gettingstarted/">Getting Started</a></li>
|
||
<li><a href="../compose/django/">Get started with Django</a></li>
|
||
<li><a href="../compose/wordpress/">Get started with WordPress</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Quickstart Guide: Compose and WordPress</title>
|
||
<link>http://localhost/compose/wordpress/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/wordpress/</guid>
|
||
<description>
|
||
|
||
<h1 id="quickstart-guide-compose-and-wordpress">Quickstart Guide: Compose and WordPress</h1>
|
||
|
||
<p>You can use Compose to easily run WordPress in an isolated environment built
|
||
with Docker containers.</p>
|
||
|
||
<h2 id="define-the-project">Define the project</h2>
|
||
|
||
<p>First, <a href="../compose/install/">Install Compose</a> and then download WordPress into the
|
||
current directory:</p>
|
||
|
||
<pre><code>$ curl https://wordpress.org/latest.tar.gz | tar -xvzf -
|
||
</code></pre>
|
||
|
||
<p>This will create a directory called <code>wordpress</code>. If you wish, you can rename it
|
||
to the name of your project.</p>
|
||
|
||
<p>Next, inside that directory, create a <code>Dockerfile</code>, a file that defines what
|
||
environment your app is going to run in. For more information on how to write
|
||
Dockerfiles, see the
|
||
<a href="https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile">Docker user guide</a> and the
|
||
<a href="http://docs.docker.com/reference/builder/">Dockerfile reference</a>. In this case,
|
||
your Dockerfile should be:</p>
|
||
|
||
<pre><code>FROM orchardup/php5
|
||
ADD . /code
|
||
</code></pre>
|
||
|
||
<p>This tells Docker how to build an image defining a container that contains PHP
|
||
and WordPress.</p>
|
||
|
||
<p>Next you&rsquo;ll create a <code>docker-compose.yml</code> file that will start your web service
|
||
and a separate MySQL instance:</p>
|
||
|
||
<pre><code>web:
|
||
build: .
|
||
command: php -S 0.0.0.0:8000 -t /code
|
||
ports:
|
||
- &quot;8000:8000&quot;
|
||
links:
|
||
- db
|
||
volumes:
|
||
- .:/code
|
||
db:
|
||
image: orchardup/mysql
|
||
environment:
|
||
MYSQL_DATABASE: wordpress
|
||
</code></pre>
|
||
|
||
<p>A supporting file is needed to get this working. <code>wp-config.php</code> is
|
||
the standard WordPress config file with a single change to point the database
|
||
configuration at the <code>db</code> container:</p>
|
||
|
||
<pre><code>&lt;?php
|
||
define('DB_NAME', 'wordpress');
|
||
define('DB_USER', 'root');
|
||
define('DB_PASSWORD', '');
|
||
define('DB_HOST', &quot;db:3306&quot;);
|
||
define('DB_CHARSET', 'utf8');
|
||
define('DB_COLLATE', '');
|
||
|
||
define('AUTH_KEY', 'put your unique phrase here');
|
||
define('SECURE_AUTH_KEY', 'put your unique phrase here');
|
||
define('LOGGED_IN_KEY', 'put your unique phrase here');
|
||
define('NONCE_KEY', 'put your unique phrase here');
|
||
define('AUTH_SALT', 'put your unique phrase here');
|
||
define('SECURE_AUTH_SALT', 'put your unique phrase here');
|
||
define('LOGGED_IN_SALT', 'put your unique phrase here');
|
||
define('NONCE_SALT', 'put your unique phrase here');
|
||
|
||
$table_prefix = 'wp_';
|
||
define('WPLANG', '');
|
||
define('WP_DEBUG', false);
|
||
|
||
if ( !defined('ABSPATH') )
|
||
define('ABSPATH', dirname(__FILE__) . '/');
|
||
|
||
require_once(ABSPATH . 'wp-settings.php');
|
||
</code></pre>
|
||
|
||
<h3 id="build-the-project">Build the project</h3>
|
||
|
||
<p>With those four files in place, run <code>docker-compose up</code> inside your WordPress
|
||
directory and it&rsquo;ll pull and build the needed images, and then start the web and
|
||
database containers. If you&rsquo;re using <a href="https://docs.docker.com/machine">Docker Machine</a>, then <code>docker-machine ip MACHINE_VM</code> gives you the machine address and you can open <code>http://MACHINE_VM_IP:8000</code> in a browser.</p>
|
||
|
||
<h2 id="more-compose-documentation">More Compose documentation</h2>
|
||
|
||
<ul>
|
||
<li><a href="../">User guide</a></li>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/gettingstarted/">Getting Started</a></li>
|
||
<li><a href="../compose/django/">Get started with Django</a></li>
|
||
<li><a href="../compose/rails/">Get started with Rails</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
<item>
|
||
<title>Using Compose in production</title>
|
||
<link>http://localhost/compose/production/</link>
|
||
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
||
<guid>http://localhost/compose/production/</guid>
|
||
<description>
|
||
|
||
<h2 id="using-compose-in-production">Using Compose in production</h2>
|
||
|
||
<blockquote>
|
||
<p>Compose is still primarily aimed at development and testing environments.
|
||
Compose may be used for smaller production deployments, but is probably
|
||
not yet suitable for larger deployments.</p>
|
||
</blockquote>
|
||
|
||
<p>When deploying to production, you&rsquo;ll almost certainly want to make changes to
|
||
your app configuration that are more appropriate to a live environment. These
|
||
changes may include:</p>
|
||
|
||
<ul>
|
||
<li>Removing any volume bindings for application code, so that code stays inside
|
||
the container and can&rsquo;t be changed from outside</li>
|
||
<li>Binding to different ports on the host</li>
|
||
<li>Setting environment variables differently (e.g., to decrease the verbosity of
|
||
logging, or to enable email sending)</li>
|
||
<li>Specifying a restart policy (e.g., <code>restart: always</code>) to avoid downtime</li>
|
||
<li>Adding extra services (e.g., a log aggregator)</li>
|
||
</ul>
|
||
|
||
<p>For this reason, you&rsquo;ll probably want to define an additional Compose file, say
|
||
<code>production.yml</code>, which specifies production-appropriate
|
||
configuration. This configuration file only needs to include the changes you&rsquo;d
|
||
like to make from the original Compose file. The additional Compose file
|
||
can be applied over the original <code>docker-compose.yml</code> to create a new configuration.</p>
|
||
|
||
<p>Once you&rsquo;ve got a second configuration file, tell Compose to use it with the
|
||
<code>-f</code> option:</p>
|
||
|
||
<pre><code>$ docker-compose -f docker-compose.yml -f production.yml up -d
|
||
</code></pre>
|
||
|
||
<p>See <a href="../compose/extends/#different-environments">Using multiple compose files</a> for a more
|
||
complete example.</p>
|
||
|
||
<h3 id="deploying-changes">Deploying changes</h3>
|
||
|
||
<p>When you make changes to your app code, you&rsquo;ll need to rebuild your image and
|
||
recreate your app&rsquo;s containers. To redeploy a service called
|
||
<code>web</code>, you would use:</p>
|
||
|
||
<pre><code>$ docker-compose build web
|
||
$ docker-compose up --no-deps -d web
|
||
</code></pre>
|
||
|
||
<p>This will first rebuild the image for <code>web</code> and then stop, destroy, and recreate
|
||
<em>just</em> the <code>web</code> service. The <code>--no-deps</code> flag prevents Compose from also
|
||
recreating any services which <code>web</code> depends on.</p>
|
||
|
||
<h3 id="running-compose-on-a-single-server">Running Compose on a single server</h3>
|
||
|
||
<p>You can use Compose to deploy an app to a remote Docker host by setting the
|
||
<code>DOCKER_HOST</code>, <code>DOCKER_TLS_VERIFY</code>, and <code>DOCKER_CERT_PATH</code> environment variables
|
||
appropriately. For tasks like this,
|
||
<a href="https://docs.docker.com/machine">Docker Machine</a> makes managing local and
|
||
remote Docker hosts very easy, and is recommended even if you&rsquo;re not deploying
|
||
remotely.</p>
|
||
|
||
<p>Once you&rsquo;ve set up your environment variables, all the normal <code>docker-compose</code>
|
||
commands will work with no further configuration.</p>
|
||
|
||
<h3 id="running-compose-on-a-swarm-cluster">Running Compose on a Swarm cluster</h3>
|
||
|
||
<p><a href="https://docs.docker.com/swarm">Docker Swarm</a>, a Docker-native clustering
|
||
system, exposes the same API as a single Docker host, which means you can use
|
||
Compose against a Swarm instance and run your apps across multiple hosts.</p>
|
||
|
||
<p>Compose/Swarm integration is still in the experimental stage, and Swarm is still
|
||
in beta, but if you&rsquo;d like to explore and experiment, check out the <a
|
||
href="https://github.com/docker/compose/blob/master/SWARM.md">integration
|
||
guide</a>.</p>
|
||
|
||
<h2 id="compose-documentation">Compose documentation</h2>
|
||
|
||
<ul>
|
||
<li><a href="../compose/install/">Installing Compose</a></li>
|
||
<li><a href="../compose/reference/">Command line reference</a></li>
|
||
<li><a href="../compose/compose-file/">Compose file reference</a></li>
|
||
</ul>
|
||
</description>
|
||
</item>
|
||
|
||
</channel>
|
||
</rss> |