new repository

1 files changed, 192 insertions, 0 deletions

diff --git a/devdocs/docker/compose%2Fextends%2Findex.html b/devdocs/docker/compose%2Fextends%2Findex.html
new file mode 100644
index 00000000..fa8c4154
--- /dev/null
+++ b/devdocs/docker/compose%2Fextends%2Findex.html
@@ -0,0 +1,192 @@
+<h1>Share Compose configurations between files and projects</h1>
+
+<p>Compose supports two methods of sharing common configuration:</p> <ol> <li>Extending an entire Compose file by <a href="index#multiple-compose-files">using multiple Compose files</a>
+</li> <li>Extending individual services with <a href="index#extending-services">the <code class="language-plaintext highlighter-rouge">extends</code> field</a> (for Compose file versions up to 2.1)</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 class="language-plaintext highlighter-rouge">docker-compose.yml</code> and an optional <code class="language-plaintext highlighter-rouge">docker-compose.override.yml</code> file. By convention, the <code class="language-plaintext highlighter-rouge">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 rules described in <a href="index#adding-and-overriding-configuration">Adding and overriding configuration</a>.</p> <p>To use multiple override files, or an override file with a different name, you can use the <code class="language-plaintext highlighter-rouge">-f</code> option to specify the list of files. Compose merges files in the order they’re specified on the command line. See the <a href="../reference/index"><code class="language-plaintext highlighter-rouge">docker-compose</code> command reference</a> for more information about using <code class="language-plaintext highlighter-rouge">-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 class="language-plaintext highlighter-rouge">-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, there 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> <div class="highlight"><pre class="highlight" data-language="">web:
+  image: example/my_web_app:latest
+  depends_on:
+    - db
+    - cache
+
+db:
+  image: postgres:latest
+
+cache:
+  image: redis:latest
+</pre></div> <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> <div class="highlight"><pre class="highlight" data-language="">web:
+  build: .
+  volumes:
+    - '.:/code'
+  ports:
+    - 8883:80
+  environment:
+    DEBUG: 'true'
+
+db:
+  command: '-d'
+  ports:
+    - 5432:5432
+
+cache:
+  ports:
+    - 6379:6379
+</pre></div> <p>When you run <code class="language-plaintext highlighter-rouge">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> <div class="highlight"><pre class="highlight" data-language="">web:
+  ports:
+    - 80:80
+  environment:
+    PRODUCTION: 'true'
+
+cache:
+  environment:
+    TTL: '500'
+</pre></div> <p>To deploy with this production Compose file you can run</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+</pre></div> <p>This deploys all three services using the configuration in <code class="language-plaintext highlighter-rouge">docker-compose.yml</code> and <code class="language-plaintext highlighter-rouge">docker-compose.prod.yml</code> (but not the dev configuration in <code class="language-plaintext highlighter-rouge">docker-compose.override.yml</code>).</p> <p>See <a href="../production/index">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> <div class="highlight"><pre class="highlight" data-language="">web:
+  image: example/my_web_app:latest
+  depends_on:
+    - db
+
+db:
+  image: postgres:latest
+</pre></div> <p>In a <strong>docker-compose.admin.yml</strong> add a new service to run the database export or backup.</p> <div class="highlight"><pre class="highlight" data-language="">    dbadmin:
+      build: database_admin/
+      depends_on:
+        - db
+</pre></div> <p>To start a normal environment run <code class="language-plaintext highlighter-rouge">docker-compose up -d</code>. To run a database backup, include the <code class="language-plaintext highlighter-rouge">docker-compose.admin.yml</code> as well.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose -f docker-compose.yml -f docker-compose.admin.yml \
+  run dbadmin db-backup
+</pre></div> <h2 id="extending-services">Extending services</h2> <blockquote> <p><strong>Note</strong></p> <p>The <code class="language-plaintext highlighter-rouge">extends</code> keyword is supported in earlier Compose file formats up to Compose file version 2.1 (see <a href="../compose-file/compose-file-v2/index#extends">extends in v2</a>), but is not supported in Compose version 3.x. See the <a href="../compose-file/compose-versioning/index#version-3">Version 3 summary</a> of keys added and removed, along with information on <a href="../compose-file/compose-versioning/index#upgrading">how to upgrade</a>. See <a href="https://github.com/moby/moby/issues/31101">moby/moby#31101</a> to follow the discussion thread on the possibility of adding support for <code class="language-plaintext highlighter-rouge">extends</code> in some form in future versions. The <code class="language-plaintext highlighter-rouge">extends</code> keyword has been included in docker-compose versions 1.27 and higher.</p> </blockquote> <p>Docker Compose’s <code class="language-plaintext highlighter-rouge">extends</code> keyword enables the 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 class="language-plaintext highlighter-rouge">extends</code> you can define a common set of service options in one place and refer to it from anywhere.</p> <p>Keep in mind that <code class="language-plaintext highlighter-rouge">volumes_from</code> and <code class="language-plaintext highlighter-rouge">depends_on</code> are never shared between services using <code class="language-plaintext highlighter-rouge">extends</code>. These exceptions exist to avoid implicit dependencies; you always define <code class="language-plaintext highlighter-rouge">volumes_from</code> locally. This ensures dependencies between services are clearly visible when reading the current file. Defining these locally also ensures that changes to the referenced file don’t break anything.</p> <h3 id="understand-the-extends-configuration">Understand the extends configuration</h3> <p>When defining any service in <code class="language-plaintext highlighter-rouge">docker-compose.yml</code>, you can declare that you are extending another service like this:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  web:
+    extends:
+      file: common-services.yml
+      service: webapp
+</pre></div> <p>This instructs Compose to re-use the configuration for the <code class="language-plaintext highlighter-rouge">webapp</code> service defined in the <code class="language-plaintext highlighter-rouge">common-services.yml</code> file. Suppose that <code class="language-plaintext highlighter-rouge">common-services.yml</code> looks like this:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  webapp:
+    build: .
+    ports:
+      - "8000:8000"
+    volumes:
+      - "/data"
+</pre></div> <p>In this case, you get exactly the same result as if you wrote <code class="language-plaintext highlighter-rouge">docker-compose.yml</code> with the same <code class="language-plaintext highlighter-rouge">build</code>, <code class="language-plaintext highlighter-rouge">ports</code> and <code class="language-plaintext highlighter-rouge">volumes</code> configuration values defined directly under <code class="language-plaintext highlighter-rouge">web</code>.</p> <p>You can go further and define (or re-define) configuration locally in <code class="language-plaintext highlighter-rouge">docker-compose.yml</code>:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  web:
+    extends:
+      file: common-services.yml
+      service: webapp
+    environment:
+      - DEBUG=1
+    cpu_shares: 5
+
+  important_web:
+    extends: web
+    cpu_shares: 10
+</pre></div> <p>You can also write other services and link your <code class="language-plaintext highlighter-rouge">web</code> service to them:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  web:
+    extends:
+      file: common-services.yml
+      service: webapp
+    environment:
+      - DEBUG=1
+    cpu_shares: 5
+    depends_on:
+      - db
+  db:
+    image: postgres
+</pre></div> <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> <div class="highlight"><pre class="highlight" data-language="">services:
+  app:
+    build: .
+    environment:
+      CONFIG_FILE_PATH: /code/config
+      API_KEY: xxxyyy
+    cpu_shares: 5
+</pre></div> <p>In a <strong>docker-compose.yml</strong> we define the concrete services which use the common configuration:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  webapp:
+    extends:
+      file: common.yml
+      service: app
+    command: /code/run_web_app
+    ports:
+      - 8080:8080
+    depends_on:
+      - queue
+      - db
+
+  queue_worker:
+    extends:
+      file: common.yml
+      service: app
+    command: /code/run_worker
+    depends_on:
+      - queue
+</pre></div> <h2 id="adding-and-overriding-configuration">Adding and overriding configuration</h2> <p>Compose copies configurations from the original service over to the local one. If a configuration option is defined in both the original service and the local service, the local value <em>replaces</em> or <em>extends</em> the original value.</p> <p>For single-value options like <code class="language-plaintext highlighter-rouge">image</code>, <code class="language-plaintext highlighter-rouge">command</code> or <code class="language-plaintext highlighter-rouge">mem_limit</code>, the new value replaces the old value.</p> <p>original service:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    command: python app.py
+</pre></div> <p>local service:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    command: python otherapp.py
+</pre></div> <p>result:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    command: python otherapp.py
+</pre></div> <p>For the <strong>multi-value options</strong> <code class="language-plaintext highlighter-rouge">ports</code>, <code class="language-plaintext highlighter-rouge">expose</code>, <code class="language-plaintext highlighter-rouge">external_links</code>, <code class="language-plaintext highlighter-rouge">dns</code>, <code class="language-plaintext highlighter-rouge">dns_search</code>, and <code class="language-plaintext highlighter-rouge">tmpfs</code>, Compose concatenates both sets of values:</p> <p>original service:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    expose:
+      - "3000"
+</pre></div> <p>local service:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    expose:
+      - "4000"
+      - "5000"
+</pre></div> <p>result:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    expose:
+      - "3000"
+      - "4000"
+      - "5000"
+</pre></div> <p>In the case of <code class="language-plaintext highlighter-rouge">environment</code>, <code class="language-plaintext highlighter-rouge">labels</code>, <code class="language-plaintext highlighter-rouge">volumes</code>, and <code class="language-plaintext highlighter-rouge">devices</code>, Compose “merges” entries together with locally-defined values taking precedence. For <code class="language-plaintext highlighter-rouge">environment</code> and <code class="language-plaintext highlighter-rouge">labels</code>, the environment variable or label name determines which value is used:</p> <p>original service:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    environment:
+      - FOO=original
+      - BAR=original
+</pre></div> <p>local service:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    environment:
+      - BAR=local
+      - BAZ=local
+</pre></div> <p>result</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    environment:
+      - FOO=original
+      - BAR=local
+      - BAZ=local
+</pre></div> <p>Entries for <code class="language-plaintext highlighter-rouge">volumes</code> and <code class="language-plaintext highlighter-rouge">devices</code> are merged using the mount path in the container:</p> <p>original service:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    volumes:
+      - ./original:/foo
+      - ./original:/bar
+</pre></div> <p>local service:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    volumes:
+      - ./local:/bar
+      - ./local:/baz
+</pre></div> <p>result:</p> <div class="highlight"><pre class="highlight" data-language="">services:
+  myservice:
+    # ...
+    volumes:
+      - ./original:/foo
+      - ./local:/bar
+      - ./local:/baz
+</pre></div> <h2 id="compose-documentation">Compose documentation</h2> <ul> <li><a href="../index">User guide</a></li> <li><a href="../install/index">Installing Compose</a></li> <li><a href="../gettingstarted/index">Getting Started</a></li> <li><a href="../reference/index">Command line reference</a></li> <li><a href="../compose-file/index">Compose file reference</a></li> <li><a href="../samples-for-compose/index">Sample apps with Compose</a></li> </ul> 
+<p><a href="https://docs.docker.com/search/?q=fig">fig</a>, <a href="https://docs.docker.com/search/?q=composition">composition</a>, <a href="https://docs.docker.com/search/?q=compose">compose</a>, <a href="https://docs.docker.com/search/?q=docker">docker</a>, <a href="https://docs.docker.com/search/?q=orchestration">orchestration</a>, <a href="https://docs.docker.com/search/?q=documentation">documentation</a>, <a href="https://docs.docker.com/search/?q=docs">docs</a></p>
+<div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
+    <a href="https://docs.docker.com/compose/extends/" class="_attribution-link">https://docs.docker.com/compose/extends/</a>
+  </p>
+</div>