path: root/devdocs/docker/compose%2Fcompose-file%2Fbuild%2Findex.html

<h1>Compose file build reference</h1>

<p>Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation focusing on development use-case to run application on local machine will obviously also support (re)building application from sources. The Compose Build specification allows to define the build process within a Compose file in a portable way.</p> <h2 id="definitions">Definitions</h2> <p>Compose Specification is extended to support an OPTIONAL <code class="language-plaintext highlighter-rouge">build</code> subsection on services. This section define the build requirements for service container image. Only a subset of Compose file services MAY define such a Build subsection, others being created based on <code class="language-plaintext highlighter-rouge">Image</code> attribute. When a Build subsection is present for a service, it is <em>valid</em> for a Compose file to miss an <code class="language-plaintext highlighter-rouge">Image</code> attribute for corresponding service, as Compose implementation can build image from source.</p> <p>Build can be either specified as a single string defining a context path, or as a detailed build definition.</p> <p>In the former case, the whole path is used as a Docker context to execute a docker build, looking for a canonical <code class="language-plaintext highlighter-rouge">Dockerfile</code> at context root. Context path can be absolute or relative, and if so relative path MUST be resolved from Compose file parent folder. As an absolute path prevent the Compose file to be portable, Compose implementation SHOULD warn user accordingly.</p> <p>In the later case, build arguments can be specified, including an alternate <code class="language-plaintext highlighter-rouge">Dockerfile</code> location. This one can be absolute or relative path. If Dockerfile path is relative, it MUST be resolved from context path. As an absolute path prevent the Compose file to be portable, Compose implementation SHOULD warn user if an absolute alternate Dockerfile path is used.</p> <h2 id="consistency-with-image">Consistency with Image</h2> <p>When service definition do include both <code class="language-plaintext highlighter-rouge">Image</code> attribute and a <code class="language-plaintext highlighter-rouge">Build</code> section, Compose implementation can’t guarantee a pulled image is strictly equivalent to building the same image from sources. Without any explicit user directives, Compose implementation with Build support MUST first try to pull Image, then build from source if image was not found on registry. Compose implementation MAY offer options to customize this behaviour by user request.</p> <h2 id="publishing-built-images">Publishing built images</h2> <p>Compose implementation with Build support SHOULD offer an option to push built images to a registry. Doing so, it MUST NOT try to push service images without an <code class="language-plaintext highlighter-rouge">Image</code> attribute. Compose implementation SHOULD warn user about missing <code class="language-plaintext highlighter-rouge">Image</code> attribute which prevent image being pushed.</p> <p>Compose implementation MAY offer a mechanism to compute an <code class="language-plaintext highlighter-rouge">Image</code> attribute for service when not explicitly declared in yaml file. In such a case, the resulting Compose configuration is considered to have a valid <code class="language-plaintext highlighter-rouge">Image</code> attribute, whenever the actual raw yaml file doesn’t explicitly declare one.</p> <h2 id="illustrative-sample">Illustrative sample</h2> <p>The following sample illustrates Compose specification concepts with a concrete sample application. The sample is non-normative.</p> <div class="highlight"><pre class="highlight" data-language="">services:
  frontend:
    image: awesome/webapp
    build: ./webapp

  backend:
    image: awesome/database
    build:
      context: backend
      dockerfile: ../backend.Dockerfile

  custom:
    build: ~/custom
</pre></div> <p>When used to build service images from source, such a Compose file will create three docker images:</p> <ul> <li>
<code class="language-plaintext highlighter-rouge">awesome/webapp</code> docker image is build using <code class="language-plaintext highlighter-rouge">webapp</code> sub-directory within Compose file parent folder as docker build context. Lack of a <code class="language-plaintext highlighter-rouge">Dockerfile</code> within this folder will throw an error.</li> <li>
<code class="language-plaintext highlighter-rouge">awesome/database</code> docker image is build using <code class="language-plaintext highlighter-rouge">backend</code> sub-directory within Compose file parent folder. <code class="language-plaintext highlighter-rouge">backend.Dockerfile</code> file is used to define build steps, this file is searched relative to context path, which means for this sample <code class="language-plaintext highlighter-rouge">..</code> will resolve to Compose file parent folder, so <code class="language-plaintext highlighter-rouge">backend.Dockerfile</code> is a sibling file.</li> <li>a docker image is build using <code class="language-plaintext highlighter-rouge">custom</code> directory within user’s HOME as docker context. Compose implementation warn user about non-portable path used to build image.</li> </ul> <p>On push, both <code class="language-plaintext highlighter-rouge">awesome/webapp</code> and <code class="language-plaintext highlighter-rouge">awesome/database</code> docker images are pushed to (default) registry. <code class="language-plaintext highlighter-rouge">custom</code> service image is skipped as no <code class="language-plaintext highlighter-rouge">Image</code> attribute is set and user is warned about this missing attribute.</p> <h2 id="build-definition">Build definition</h2> <p>The <code class="language-plaintext highlighter-rouge">build</code> element define configuration options that are applied by Compose implementations to build Docker image from source. <code class="language-plaintext highlighter-rouge">build</code> can be specified either as a string containing a path to the build context or a detailed structure:</p> <div class="highlight"><pre class="highlight" data-language="">services:
  webapp:
    build: ./dir
</pre></div> <p>Using this string syntax, only the build context can be configured as a relative path to the Compose file’s parent folder. This path MUST be a directory and contain a <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <p>Alternatively <code class="language-plaintext highlighter-rouge">build</code> can be an object with fields defined as follow</p> <h3 id="context-required">context (REQUIRED)</h3> <p><code class="language-plaintext highlighter-rouge">context</code> defines either a path to a directory containing a Dockerfile, or a url to a git repository.</p> <p>When the value supplied is a relative path, it MUST be interpreted as relative to the location of the Compose file. Compose implementations MUST warn user about absolute path used to define build context as those prevent Compose file for being portable.</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: ./dir
</pre></div> <h3 id="dockerfile">dockerfile</h3> <p><code class="language-plaintext highlighter-rouge">dockerfile</code> allows to set an alternate Dockerfile. A relative path MUST be resolved from the build context. Compose implementations MUST warn user about absolute path used to define Dockerfile as those prevent Compose file for being portable.</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  dockerfile: webapp.Dockerfile
</pre></div> <h3 id="args">args</h3> <p><code class="language-plaintext highlighter-rouge">args</code> define build arguments, i.e. Dockerfile <code class="language-plaintext highlighter-rouge">ARG</code> values.</p> <p>Using following Dockerfile:</p> <div class="highlight"><pre class="highlight" data-language="">ARG GIT_COMMIT
RUN echo "Based on commit: $GIT_COMMIT"
</pre></div> <p><code class="language-plaintext highlighter-rouge">args</code> can be set in Compose file under the <code class="language-plaintext highlighter-rouge">build</code> key to define <code class="language-plaintext highlighter-rouge">GIT_COMMIT</code>. <code class="language-plaintext highlighter-rouge">args</code> can be set a mapping or a list:</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  args:
    GIT_COMMIT: cdc3b19
</pre></div> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  args:
    - GIT_COMMIT=cdc3b19
</pre></div> <p>Value can be omitted when specifying a build argument, in which case its value at build time MUST be obtained by user interaction, otherwise build arg won’t be set when building the Docker image.</p> <div class="highlight"><pre class="highlight" data-language="">args:
  - GIT_COMMIT
</pre></div> <h3 id="ssh">ssh</h3> <p><code class="language-plaintext highlighter-rouge">ssh</code> defines SSH authentications that the image builder SHOULD use during image build (e.g., cloning private repository)</p> <p><code class="language-plaintext highlighter-rouge">ssh</code> property syntax can be either:</p> <ul> <li>
<code class="language-plaintext highlighter-rouge">default</code> - let the builder connect to the ssh-agent.</li> <li>
<code class="language-plaintext highlighter-rouge">ID=path</code> - a key/value definition of an ID and the associated path. Can be either a <a href="https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail">PEM</a> file, or path to ssh-agent socket</li> </ul> <p>Simple <code class="language-plaintext highlighter-rouge">default</code> sample</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  ssh: 
    - default   # mount the default ssh agent
</pre></div> <p>or</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  ssh: ["default"]   # mount the default ssh agent
</pre></div> <p>Using a custom id <code class="language-plaintext highlighter-rouge">myproject</code> with path to a local SSH key:</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  ssh: 
    - myproject=~/.ssh/myproject.pem
</pre></div> <p>Image builder can then rely on this to mount SSH key during build. For illustration, <a href="#">BuildKit extended syntax</a> can be used to mount ssh key set by ID and access a secured resource:</p> <p><code class="language-plaintext highlighter-rouge">RUN --mount=type=ssh,id=myproject git clone ...</code></p> <h3 id="cache_from">cache_from</h3> <p><code class="language-plaintext highlighter-rouge">cache_from</code> defines a list of sources the Image builder SHOULD use for cache resolution.</p> <p>Cache location syntax MUST follow the global format <code class="language-plaintext highlighter-rouge">[NAME|type=TYPE[,KEY=VALUE]]</code>. Simple <code class="language-plaintext highlighter-rouge">NAME</code> is actually a shortcut notation for <code class="language-plaintext highlighter-rouge">type=registry,ref=NAME</code>.</p> <p>Compose Builder implementations MAY support custom types, the Compose Specification defines canonical types which MUST be supported:</p> <ul> <li>
<code class="language-plaintext highlighter-rouge">registry</code> to retrieve build cache from an OCI image set by key <code class="language-plaintext highlighter-rouge">ref</code>
</li> </ul> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  cache_from:
    - alpine:latest
    - type=local,src=path/to/cache
    - type=gha
</pre></div> <p>Unsupported caches MUST be ignored and not prevent user from building image.</p> <h3 id="cache_to">cache_to</h3> <p><code class="language-plaintext highlighter-rouge">cache_to</code> defines a list of export locations to be used to share build cache with future builds.</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  cache_to: 
   - user/app:cache
   - type=local,dest=path/to/cache
</pre></div> <p>Cache target is defined using the same <code class="language-plaintext highlighter-rouge">type=TYPE[,KEY=VALUE]</code> syntax defined by <a href="#cache_from"><code class="language-plaintext highlighter-rouge">cache_from</code></a>.</p> <p>Unsupported cache target MUST be ignored and not prevent user from building image.</p> <h3 id="extra_hosts">extra_hosts</h3> <p><code class="language-plaintext highlighter-rouge">extra_hosts</code> adds hostname mappings at build-time. Use the same syntax as <a href="../index#extra_hosts">extra_hosts</a>.</p> <div class="highlight"><pre class="highlight" data-language="">extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"
</pre></div> <p>Compose implementations MUST create matching entry with the IP address and hostname in the container’s network configuration, which means for Linux <code class="language-plaintext highlighter-rouge">/etc/hosts</code> will get extra lines:</p> <div class="highlight"><pre class="highlight" data-language="">162.242.195.82  somehost
50.31.209.229   otherhost
</pre></div> <h3 id="isolation">isolation</h3> <p><code class="language-plaintext highlighter-rouge">isolation</code> specifies a build’s container isolation technology. Like <a href="../index#isolation">isolation</a> supported values are platform-specific.</p> <h3 id="labels">labels</h3> <p><code class="language-plaintext highlighter-rouge">labels</code> add metadata to the resulting image. <code class="language-plaintext highlighter-rouge">labels</code> can be set either as an array or a map.</p> <p>reverse-DNS notation SHOULD be used to prevent labels from conflicting with those used by other software.</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  labels:
    com.example.description: "Accounting webapp"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""
</pre></div> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  labels:
    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"
</pre></div> <h3 id="shm_size">shm_size</h3> <p><code class="language-plaintext highlighter-rouge">shm_size</code> set the size of the shared memory (<code class="language-plaintext highlighter-rouge">/dev/shm</code> partition on Linux) allocated for building Docker image. Specify as an integer value representing the number of bytes or as a string expressing a <a href="../index#specifying-byte-values">byte value</a>.</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  shm_size: '2gb'
</pre></div> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  shm_size: 10000000
</pre></div> <h3 id="target">target</h3> <p><code class="language-plaintext highlighter-rouge">target</code> defines the stage to build as defined inside a multi-stage <code class="language-plaintext highlighter-rouge">Dockerfile</code>.</p> <div class="highlight"><pre class="highlight" data-language="">build:
  context: .
  target: prod
</pre></div> <h2 id="implementations">Implementations</h2> <ul> <li><a href="../../index">docker-compose</a></li> <li><a href="https://docs.docker.com/buildx/working-with-buildx/">buildX bake</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></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/compose-file/build/" class="_attribution-link">https://docs.docker.com/compose/compose-file/build/</a>
  </p>
</div>