Build is an optional part of the Compose Specification
A Compose implementation which focuses on running an application on a local machine needs to also support (re)building the application from source. The Compose Build Specification lets you define the build process within a Compose file in a portable way.
Only a subset of Compose file services can be defined under a
subsection, others may make use of the
image attribute. When a
build subsection is present for a service, Compose ignores the
image attribute for the corresponding service, as Compose
can build an image from source.
build can be either specified as a single string defining a context path, or as a detailed build definition.
In the former case, the whole path is used as a Docker context to execute a Docker build, looking for a canonical
Dockerfile at the root of the directory. The path can be absolute or relative. If it is relative, it is resolved
from the Compose file's parent folder. If it is absolute, the path prevents the Compose file from being portable so Compose displays a warning.
In the later case, build arguments can be specified, including an alternate
Dockerfile location. The path can be absolute or relative. If it is relative, it is resolved
from the Compose file's parent folder. If it is absolute, the path prevents the Compose file from being portable so Compose displays a warning..
When a service definition includes both the
image attribute and a
build section, Compose can't
guarantee a pulled image is strictly equivalent to building the same image from source. Without any explicit
user directives, Compose with
build support first tries to pull the image, then builds from source
if the image is not found on registry. Compose may offer options to customize this behaviour by user
build support offers an option to push built images to a registry. When doing so, it doesn't try to push service images without an
image attribute. Compose warns you about the missing
image attribute which prevents images being pushed.
A Compose implementation may offer a mechanism to compute an
image attribute for services when not explicitly
declared in a yaml file. In such cases, the resulting Compose configuration is considered to have a valid
attribute, whenever the actual raw yaml file doesn't explicitly declare one.
The following example illustrates Compose Build Specification concepts with a concrete sample application. The sample is non-normative.
services: frontend: image: example/webapp build: ./webapp backend: image: example/database build: context: backend dockerfile: ../backend.Dockerfile custom: build: ~/custom
When used to build service images from source, the Compose file creates three Docker images:
example/webapp: A Docker image is built using
webappsub-directory, within the Compose file's parent folder, as the Docker build context. Lack of a
Dockerfilewithin this folder throws an error.
example/database: A Docker image is built using
backendsub-directory within the Compose file parent folder.
backend.Dockerfilefile is used to define build steps, this file is searched relative to the context path, which means
..resolves to the Compose file parent folder, so
backend.Dockerfileis a sibling file.
- A Docker image is built using the
customdirectory with the user's HOME as the Docker context. Compose displays a warning about the non-portable path used to build image.
On push, both
example/database Docker images are pushed to the default registry. The
custom service image is skipped as no
image attribute is set and Compose displays a warning about this missing attribute.
build subsection defines configuration options that are applied by Compose to build Docker images from source.
build can be specified either as a string containing a path to the build context or as a detailed structure:
Using the string syntax, only the build context can be configured as either:
A relative path to the Compose file's parent folder. This path must be a directory and must contain a
services: webapp: build: ./dir
A git repository URL. Git URLs accept context configuration in their fragment section, separated by a colon (
:). The first part represents the reference that Git checks out, and can be either a branch, a tag, or a remote reference. The second part represents a subdirectory inside the repository that is used as a build context.
services: webapp: build: https://github.com/mycompany/example.git#branch_or_tag:subdirectory
build can be an object with fields defined as follows:
context defines either a path to a directory containing a Dockerfile, or a URL to a git repository.
When the value supplied is a relative path, it is interpreted as relative to the location of the Compose file. Compose warns you about the absolute path used to define the build context as those prevent the Compose file from being portable.
build: context: ./dir
services: webapp: build: https://github.com/mycompany/webapp.git
If not set explicitly,
context defaults to project directory (
dockerfile sets an alternate Dockerfile. A relative path is resolved from the build context.
Compose warns you about the absolute path used to define the Dockerfile as it prevents Compose files
from being portable.
dockerfile_inline attribute is not allowed and Compose
rejects any Compose file having both set.
build: context: . dockerfile: webapp.Dockerfile
dockerfile_inline defines the Dockerfile content as an inlined string in a Compose file. When set, the
attribute is not allowed and Compose rejects any Compose file having both set.
Use of YAML multi-line string syntax is recommended to define the Dockerfile content:
build: context: . dockerfile_inline: | FROM baseimage RUN some command
args define build arguments, i.e. Dockerfile
Using the following Dockerfile as an example:
ARG GIT_COMMIT RUN echo "Based on commit: $GIT_COMMIT"
args can be set in the Compose file under the
build key to define
args can be set as a mapping or a list:
build: context: . args: GIT_COMMIT: cdc3b19
build: context: . args: - GIT_COMMIT=cdc3b19
Values can be omitted when specifying a build argument, in which case its value at build time must be obtained by user interaction, otherwise the build arg won't be set when building the Docker image.
args: - GIT_COMMIT
ssh defines SSH authentications that the image builder should use during image build (e.g., cloning private repository).
ssh property syntax can be either:
default: Let the builder connect to the ssh-agent.
ID=path: A key/value definition of an ID and the associated path. It can be either a PEMopen_in_new file, or path to ssh-agent socket.
build: context: . ssh: - default # mount the default ssh agent
build: context: . ssh: ["default"] # mount the default ssh agent
Using a custom id
myproject with path to a local SSH key:
build: context: . ssh: - myproject=~/.ssh/myproject.pem
The image builder can then rely on this to mount the SSH key during build. For illustration, BuildKit extended syntaxopen_in_new can be used to mount the SSH key set by ID and access a secured resource:
RUN --mount=type=ssh,id=myproject git clone ...
cache_from defines a list of sources the image builder should use for cache resolution.
Cache location syntax follows the global format
NAME is actually a shortcut notation for
Compose Build implementations may support custom types, the Compose Specification defines canonical types which must be supported:
registryto retrieve build cache from an OCI image set by key
build: context: . cache_from: - alpine:latest - type=local,src=path/to/cache - type=gha
Unsupported caches are ignored and don't prevent you from building images.
cache_to defines a list of export locations to be used to share build cache with future builds.
build: context: . cache_to: - user/app:cache - type=local,dest=path/to/cache
Cache target is defined using the same
type=TYPE[,KEY=VALUE] syntax defined by
Unsupported caches are ignored and don't prevent you from building images.
additional_contexts defines a list of named contexts the image builder should use during image build.
additional_contexts can be a mapping or a list:
build: context: . additional_contexts: - resources=/path/to/resources - app=docker-image://my-app:latest - source=https://github.com/myuser/project.git
build: context: . additional_contexts: resources: /path/to/resources app: docker-image://my-app:latest source: https://github.com/myuser/project.git
When used as a list, the syntax follows the
NAME=VALUE format, where
VALUE is a string. Validation beyond that
is the responsibility of the image builder (and is builder specific). Compose supports at least
absolute and relative paths to a directory AND Git repository URLs, like
context does. Other context flavours
must be prefixed to avoid ambiguity with a
Compose warns you if the image builder does not support additional contexts and may list the unused contexts.
Illustrative examples of how this is used in Buildx can be found hereopen_in_new.
extra_hosts adds hostname mappings at build-time. Use the same syntax as
extra_hosts: - "somehost:184.108.40.206" - "otherhost:220.127.116.11"
Compose creates matching entry with the IP address and hostname in the container's network
configuration, which means for Linux
/etc/hosts will get extra lines:
18.104.22.168 somehost 22.214.171.124 otherhost
isolation specifies a build’s container isolation technology. Like
isolation, supported values
are platform specific.
privileged configures the service image to build with elevated privileges. Support and actual impacts are platform specific.
build: context: . privileged: true
labels add metadata to the resulting image.
labels can be set either as an array or a map.
It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with other software.
build: context: . labels: com.example.description: "Accounting webapp" com.example.department: "Finance" com.example.label-with-empty-value: ""
build: context: . labels: - "com.example.description=Accounting webapp" - "com.example.department=Finance" - "com.example.label-with-empty-value"
no_cache disables image builder cache and enforces a full rebuild from source for all image layers. This only
applies to layers declared in the Dockerfile, referenced images COULD be retrieved from local image store whenever tag
has been updated on registry (see
pull requires the image builder to pull referenced images (
FROM Dockerfile directive), even if those are already
available in the local image store.
Set the network containers connect to for the
RUN instructions during build.
build: context: . network: host
build: context: . network: custom_network_1
none to disable networking during build:
build: context: . network: none
shm_size sets the size of the shared memory (
/dev/shm partition on Linux) allocated for building Docker images. Specify
as an integer value representing the number of bytes or as a string expressing a
build: context: . shm_size: '2gb'
build: context: . shm_size: 10000000
target defines the stage to build as defined inside a multi-stage
build: context: . target: prod
secrets grants access to sensitive data defined by
secrets on a per-service build basis. Two
different syntax variants are supported: the short syntax and the long syntax.
Compose reports an error if the secret isn't defined in the
secrets section of this Compose file.
The short syntax variant only specifies the secret name. This grants the
container access to the secret and mounts it as read-only to
within the container. The source name and destination mountpoint are both set
to the secret name.
The following example uses the short syntax to grant the build of the
access to the
server-certificate secret. The value of
server-certificate is set
to the contents of the file
services: frontend: build: context: . secrets: - server-certificate secrets: server-certificate: file: ./server.cert
The long syntax provides more granularity in how the secret is created within the service's containers.
source: The name of the secret as it exists on the platform.
target: The name of the file to be mounted in
/run/secrets/in the service's task containers. Defaults to
sourceif not specified.
gid: The numeric UID or GID that owns the file within
/run/secrets/in the service's task containers. Default value is USER running container.
mode: The permissionsopen_in_new for the file to be mounted in
/run/secrets/in the service's task containers, in octal notation. Default value is world-readable permissions (mode
0444). The writable bit must be ignored if set. The executable bit may be set.
The following example sets the name of the
server-certificate secret file to
within the container, sets the mode to
0440 (group-readable) and sets the user and group
103. The value of
server-certificate secret is provided by the platform through a lookup and
the secret lifecycle not directly managed by Compose.
services: frontend: build: context: . secrets: - source: server-certificate target: server.cert uid: "103" gid: "103" mode: 0440 secrets: server-certificate: external: true
Service builds may be granted access to multiple secrets. Long and short syntax for secrets may be used in the
same Compose file. Defining a secret in the top-level
secrets must not imply granting any service build access to it.
Such grant must be explicit within service specification as
secrets service element.
tags defines a list of tag mappings that must be associated to the build image. This list comes in addition to
property defined in the service section
tags: - "myimage:mytag" - "registry/username/myrepos:my-other-tag"
platforms defines a list of target
build: context: "." platforms: - "linux/amd64" - "linux/arm64"
platforms attribute is omitted, Compose includes the service's platform
in the list of the default build target platforms.
platforms attribute is defined, Compose includes the service's
platform, otherwise users won't be able to run images they built.
Composes reports an error in the following cases:
When the list contains multiple platforms but the implementation is incapable of storing multi-platform images.
When the list contains an unsupported platform.
build: context: "." platforms: - "linux/amd64" - "unsupported/unsupported"
When the list is non-empty and does not contain the service's platform
services: frontend: platform: "linux/amd64" build: context: "." platforms: - "linux/arm64"