Container specification

A container specification defines the runtime configuration of a single container. It is the common set of attributes shared by anything that runs a container: services, jobs, and run-to-completion init containers (pre_start hooks).

Attributes that only make sense for an orchestrated workload (build, ports, health checks, dependencies, …) are not part of the container specification: they are defined by the Workload specification shared by services and jobs.

annotations

Compose v2.18.0

annotations defines annotations for the container. annotations can use either an array or a map.

annotations:
  com.example.foo: bar

annotations:
  - com.example.foo=bar

blkio_config

blkio_config defines a set of configuration options to set block IO limits for a service.

services:
  foo:
    image: busybox
    blkio_config:
       weight: 300
       weight_device:
         - path: /dev/sda
           weight: 400
       device_read_bps:
         - path: /dev/sdb
           rate: '12mb'
       device_read_iops:
         - path: /dev/sdb
           rate: 120
       device_write_bps:
         - path: /dev/sdb
           rate: '1024k'
       device_write_iops:
         - path: /dev/sdb
           rate: 30

device_read_bps, device_write_bps

Set a limit in bytes per second for read / write operations on a given device. Each item in the list must have two keys:

device_read_iops, device_write_iops

Set a limit in operations per second for read / write operations on a given device. Each item in the list must have two keys:

weight

Modify the proportion of bandwidth allocated to a service relative to other services. Takes an integer value between 10 and 1000, with 500 being the default.

weight_device

Fine-tune bandwidth allocation by device. Each item in the list must have two keys:

cpu_count

cpu_count defines the number of usable CPUs for service container.

cpu_percent

cpu_percent defines the usable percentage of the available CPUs.

cpu_shares

cpu_shares defines, as integer value, a service container’s relative CPU weight versus other containers.

cpu_period

cpu_period configures CPU CFS (Completely Fair Scheduler) period when a platform is based on Linux kernel.

cpu_quota

cpu_quota configures CPU CFS (Completely Fair Scheduler) quota when a platform is based on Linux kernel.

cpu_rt_runtime

cpu_rt_runtime configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either an integer value using microseconds as unit or a duration.

 cpu_rt_runtime: '400ms'
 cpu_rt_runtime: 95000`

cpu_rt_period

cpu_rt_period configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either an integer value using microseconds as unit or a duration.

 cpu_rt_period: '1400us'
 cpu_rt_period: 11000`

cpus

cpus define the number of (potentially virtual) CPUs to allocate to service containers. This is a fractional number. 0.000 means no limit.

When both are set, cpus must be consistent with the cpus attribute in the Deploy Specification

cpuset

cpuset defines the explicit CPUs in which to allow execution. Can be a range 0-3 or a list 0,1

cap_add

cap_add specifies additional container capabilities as strings.

cap_add:
  - ALL

cap_drop

cap_drop specifies container capabilities to drop as strings.

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup

Compose v2.15.0

cgroup specifies the cgroup namespace to join. When unset, it is the container runtime’s decision to select which cgroup namespace to use, if supported.

cgroup_parent

cgroup_parent specifies an optional parent cgroup for the container.

cgroup_parent: m-executor-abcd

command

command overrides the default command declared by the container image, for example by Dockerfile’s CMD.

command: bundle exec thin -p 3000

Note

Unlike the CMD instruction of an image, the shell-form syntax for command does not implicitly run in the context of the SHELL instruction.

If you expect the command to rely on features of a shell environment such as environment variables, then ensure the command is run within a shell:

command: /bin/sh -c 'echo "hello $$HOSTNAME"'

The value can also be a list, in a manner similar to the exec-form syntax used by Dockerfile.

command: [ "bundle", "exec", "thin", "-p", "3000" ]

If the value is null, the default command from the image is used.

If the value is [] (empty list) or '' (empty string), the default command declared by the image is ignored, i.e. overridden to be empty.

configs

Configs allow services to adapt their behaviour without the need to rebuild a Docker image. Services can only access configs when explicitly granted by the configs attribute. Two different syntax variants are supported.

Compose reports an error if config doesn’t exist on the platform or isn’t defined in the configs top-level element in the Compose file.

There are two syntaxes defined for configs. To remain compliant to this specification, an implementation must support both syntaxes. Implementations must allow use of both short and long syntaxes within the same document.

You can grant a service access to multiple configs, and you can mix long and short syntax.

Short syntax

The short syntax variant only specifies the config name. This grants the container access to the config and mounts it as files into a service’s container’s filesystem. The location of the mount point within the container defaults to /<config_name> in Linux containers, and C:\<config-name> in Windows containers.

The following example uses the short syntax to grant the redis service access to the my_config and my_other_config configs. The value of my_config is set to the contents of the file ./my_config.txt, and my_other_config is defined as an external resource, which means that it has already been defined in the platform. If the external config does not exist, the deployment fails.

services:
  redis:
    image: redis:latest
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

Long syntax

The long syntax provides more granularity in how the config is created within the service’s task containers.

Note

The uid, gid, and mode attributes are not implemented in Docker Compose when the source of the config is a file, as bind-mount used under the hood doesn’t allow uid remapping.

The following example sets the name of my_config to redis_config within the container, sets the mode to 0440 (group-readable) and sets the user and group to 103. The redis service does not have access to the my_other_config config.

services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        uid: "103"
        gid: "103"
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true

credential_spec

credential_spec configures the credential spec for a managed service account.

If you have services that use Windows containers, you can use file: and registry: protocols for credential_spec. Compose also supports additional protocols for custom use-cases.

The credential_spec must be in the format file://<filename> or registry://<value-name>.

credential_spec:
  file: my-credential-spec.json

When using registry:, the credential spec is read from the Windows registry on the daemon’s host. A registry value with the given name must be located in:

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

The following example loads the credential spec from a value named my-credential-spec in the registry:

credential_spec:
  registry: my-credential-spec

Example gMSA configuration

When configuring a gMSA credential spec for a service, you only need to specify a credential spec with config, as shown in the following example:

services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json|

device_cgroup_rules

device_cgroup_rules defines a list of device cgroup rules for this container. The format is the same format the Linux kernel specifies in the Control Groups Device Whitelist Controller.

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

devices

devices defines a list of device mappings for created containers in the form of HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS].

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"

devices can also rely on the CDI syntax to let the container runtime select a device:

devices:
  - "vendor1.com/device=gpu"

dns

dns defines custom DNS servers to set on the container network interface configuration. It can be a single value or a list.

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

dns_opt list custom DNS options to be passed to the container’s DNS resolver (/etc/resolv.conf file on Linux).

dns_opt:
  - use-vc
  - no-tld-query

dns_search defines custom DNS search domains to set on container network interface configuration. It can be a single value or a list.

dns_search: example.com

dns_search:
  - dc1.example.com
  - dc2.example.com

domainname

domainname declares a custom domain name to use for the service container. It must be a valid RFC 1123 hostname.

entrypoint

entrypoint declares the default entrypoint for the service container. This overrides the ENTRYPOINT instruction from the service’s Dockerfile.

If entrypoint is non-null, Compose ignores any default command from the image, for example the CMD instruction in the Dockerfile.

See also command to set or override the default command to be executed by the entrypoint process.

In its short form, the value can be defined as a string:

entrypoint: /code/entrypoint.sh

Alternatively, the value can also be a list, in a manner similar to the Dockerfile:

entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit

If the value is null, the default entrypoint from the image is used.

If the value is [] (empty list) or '' (empty string), the default entrypoint declared by the image is ignored, i.e. overridden to be empty.

env_file

env_file adds environment variables to the container based on the file content.

env_file: .env

env_file can also be a list. The files in the list are processed from the top down. For the same variable specified in two env files, the value from the last file in the list stands.

env_file:
  - ./a.env
  - ./b.env

Relative path are resolved from the Compose file’s parent folder. As absolute paths prevent the Compose file from being portable, Compose warns you when such a path is used to set env_file.

Environment variables declared in the environment section override these values. This holds true even if those values are empty or undefined.

List elements can also be declared as a mapping, which then lets you set an additional attributes

required

Compose v2.24.0

required attribute defaults to true. When required is set to false and the .env file is missing, Compose silently ignores the entry.

env_file:
  - path: ./default.env
    required: true # default
  - path: ./override.env
    required: false

format

Compose v2.30.0

format attribute lets you to use an alternative file formats for env_file. When not set, env_file is parsed according to Compose rules as described in next section.

raw format lets you use an env_file with key=value items, but without any attempt from Compose to parse the value for interpolation. This let you pass values as-is including quotes and $ signs.

env_file:
  - path: ./default.env
    format: raw

Env_file format

Each line in an .env file must be in VAR[=[VAL]] format. The following syntax rules apply:

VAL may be omitted, in such cases the variable value is an empty string. =VAL may be omitted, in such cases the variable is unset.

# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"

environment

environment defines environment variables set in the container. environment can use either an array or a map. Any boolean values; true, false, yes, no, should be enclosed in quotes to ensure they are not converted to True or False by the YAML parser.

Environment variables can be declared by a single key (no value to equals sign). In this case Compose relies on you to resolve the value. If the value is not resolved, the variable is unset and is removed from the service container environment.

Map syntax:

environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:

Array syntax:

environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT

When both env_file and environment are set for a service, values set by environment have precedence.

extra_hosts

extra_hosts adds hostname mappings to the container network interface configuration (/etc/hosts for Linux).

Short syntax

Short syntax uses plain strings in a list. Values must set hostname and IP address for additional hosts in the form of HOSTNAME=IP.

extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"

IPv6 addresses can be enclosed in square brackets, for example:

extra_hosts:
  - "myhostv6=[::1]"

The separator = is preferred Compose v2.24.1 but : can also be used. For example:

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

Long syntax

Alternatively, extra_hosts can be set as a mapping between hostname(s) and IP(s)

extra_hosts:
  somehost: "162.242.195.82"
  otherhost: "50.31.209.229"
  myhostv6: "::1"

Compose creates a matching entry with the IP address and hostname in the container’s network configuration, which means for Linux /etc/hosts get extra lines:

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

gpus

Compose v2.30.0

gpus specifies GPU devices to be allocated for container usage. This is equivalent to a device request with an implicit gpu capability.

services:
  model:
    gpus: 
      - driver: 3dfx
        count: 2

gpus also can ge set as string all to allocate all aviable GPU devices to container.

services:
  model:
    gpus: all

group_add

group_add specifies additional groups, by name or number, which the user inside the container must be a member of.

An example of where this is useful is when multiple containers (running as different users) need to all read or write the same file on a shared volume. That file can be owned by a group shared by all the containers, and specified in group_add.

services:
  myservice:
    image: alpine
    group_add:
      - mail

Running id inside the created container must show that the user belongs to the mail group, which would not have been the case if group_add were not declared.

hostname

hostname declares a custom host name to use for the service container. It must be a valid RFC 1123 hostname.

image

image specifies the image to start the container from. image must follow the Open Container Specification addressable image format, as [<registry>/][<project>/]<image>[:<tag>|@<digest>].

    image: redis
    image: redis:5
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    image: library/redis
    image: docker.io/library/redis
    image: my_private.registry:5000/redis

If the image does not exist on the platform, Compose attempts to pull it based on the pull_policy. If you are also using the Compose Build Specification, there are alternative options for controlling the precedence of pull over building the image from source, however pulling the image is the default behavior.

image may be omitted from a Compose file as long as a build section is declared. If you are not using the Compose Build Specification, Compose won’t work if image is missing from the Compose file.

init

init runs an init process (PID 1) inside the container that forwards signals and reaps processes. Set this option to true to enable this feature for the service.

services:
  web:
    image: alpine:latest
    init: true

The init binary that is used is platform specific.

ipc

ipc configures the IPC isolation mode set by the service container. Available values are platform specific, but Compose defines specific values which must be implemented as described if supported:

    ipc: "shareable"
    ipc: "service:[service name]"

isolation

isolation specifies a container’s isolation technology. Supported values are platform specific.

labels

labels add metadata to containers. You can use either an array or a map.

It’s recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

Compose creates containers with canonical labels:

The com.docker.compose label prefix is reserved. Specifying labels with this prefix in the Compose file results in a runtime error.

label_file

Compose v2.32.0

The label_file attribute lets you load labels for a service from an external file or a list of files. This provides a convenient way to manage multiple labels without cluttering the Compose file.

The file uses a key-value format, similar to env_file. You can specify multiple files as a list. When using multiple files, they are processed in the order they appear in the list. If the same label is defined in multiple files, the value from the last file in the list overrides earlier ones.

services:
  one:
    label_file: ./app.labels

  two:
    label_file: 
      - ./app.labels
      - ./additional.labels

If a label is defined in both the label_file and the labels attribute, the value in labels takes precedence.

logging

logging defines the logging configuration for the service.

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

The driver name specifies a logging driver for the service’s containers. The default and available values are platform specific. Driver specific options can be set with options as key-value pairs.

mac_address

Compose v2.23.2

mac_address sets a MAC address for the service container.

Note Container runtimes might reject this value (ie. Docker Engine >= v25.0). In that case, you should use networks.mac_address instead.

mem_limit

mem_limit configures a limit on the amount of memory a container can allocate, set as a string expressing a byte value.

When both are set, mem_limit must be consistent with the limits.memory attribute in the Deploy Specification

mem_reservation

mem_reservation configures a reservation on the amount of memory a container can allocate, set as a string expressing a byte value.

When both are set, mem_reservation must be consistent with the reservations.memory attribute in the Deploy Specification

mem_swappiness

mem_swappiness defines as a percentage, a value between 0 and 100, for the host kernel to swap out anonymous memory pages used by a container.

The default value is platform specific.

memswap_limit

memswap_limit defines the amount of memory the container is allowed to swap to disk. This is a modifier attribute that only has meaning if memory is also set. Using swap lets the container write excess memory requirements to disk when the container has exhausted all the memory that is available to it. There is a performance penalty for applications that swap memory to disk often.

models

Compose v2.38.0](https://github.com/docker/compose/releases/v2.38.0)

models defines the AI models that the service containers use at runtime, referencing entries under the top-level models key

services:
  short_syntax:
    image: app
    models:
      - my_model

  long_syntax:
    image: app
    models:
      my_model:
        endpoint_var: MODEL_URL
        model_var: MODEL

When using the long syntax,

(*) variable name is generated from model key by making string uppercase and replacing - characters by _ to conform to POSIX environment variable conventions.

network_mode

network_mode sets a service container’s network mode. Available values are platform specific, but Compose defines specific values which must be implemented as described if supported:

    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[service name]"

When set, the networks attribute is not allowed and Compose rejects any Compose file containing both attributes.

networks

networks defines the networks that service containers are attached to, referencing entries under the top-level networks key.

services:
  some-service:
    networks:
      - some-network
      - other-network

implicit default network

If networks is empty or absent from the Compose file, Compose considers an implicit definition for the service to be connected to the default network:

services:
  some-service:
    image: foo

This example is actually equivalent to:

services:
  some-service:
    image: foo  
    networks:
      default: {}

If you want the service to be connected to none of the networks, you must set network_mode: none

aliases

aliases declares alternative hostnames for the service on the network. Other containers on the same network can use either the service name or an alias to connect to one of the service’s containers.

Since aliases are network-scoped, the same service can have different aliases on different networks.

Note A network-wide alias can be shared by multiple containers, and even by multiple services. If it is, then exactly which container the name resolves to is not guaranteed.

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

In the following example, service frontend is able to reach the backend service at the hostname backend or database on the back-tier network. The service monitoring is able to reach same backend service at backend or mysql on the admin network.

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: example/monitoring
    networks:
      - admin

  backend:
    image: example/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier: {}
  back-tier: {}
  admin: {}

use_service_name_alias

Compose NEXT

use_service_name_alias controls whether the service name is registered as an alias of the service’s containers on the network. It defaults to true. It requires the long syntax of networks.

When set to false, the service name is not an alias on this network. The values listed in aliases are not affected, and neither are the other networks of the service.

Implementations must distinguish an unset value from false, so that a Compose file merged on top of another can set the attribute back to true.

This is useful when a network is shared by several Compose applications that each define a service with the same name: the name would otherwise resolve to a container of any of them. Give each service a distinct alias instead:

networks:
  shared:
    external: true

services:
  database:
    networks:
      shared:
        aliases:
          - project1-database
        use_service_name_alias: false

Note If the service is attached to no other network where its name is registered, other services can no longer reach it by service name. Use aliases to give it a name on that network. links are not affected.

Note use_service_name_alias only affects name resolution. It does not isolate the network: containers attached to it can still reach the service by IP address or by any of its aliases.

interface_name

Compose v2.36.0](https://github.com/docker/compose/releases/v2.36.0)

interface_name can be used to declare the network interface name used to connect to a target network. This allows you to enforce a deterministic assignment of network interface names for configured networks.

services:
  backend:
    image: alpine
    command: ip link show
    networks:
      back-tier:
        interface_name: eth0

Running this Compose application shows:

backend-1  | 11: eth0@if64: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP

ipv4_address, ipv6_address

Specify a static IP address for a service container when joining the network.

The corresponding network configuration in the top-level networks section must have an ipam attribute with subnet configurations covering each static address.

services:
  frontend:
    image: example/webapp
    networks:
      front-tier:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  front-tier:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

link_local_ips specifies a list of link-local IPs. Link-local IPs are special IPs which belong to a well known subnet and are purely managed by the operator, usually dependent on the architecture where they are deployed. Implementation is platform specific.

Example:

services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge

mac_address

Compose v2.24.0

mac_address sets the MAC address used by the service container when connecting to this particular network.

driver_opts

Compose v2.27.1

driver_opts specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent. Consult the driver’s documentation for more information.

services:
  app:
    networks:
      app_net:
        driver_opts:
          foo: "bar"
          baz: 1

gw_priority

Compose v2.33.0

The network with the highest gw_priority is selected as the default gateway for the service container. If unspecified, the default value is 0.

In the following example, app_net_2 will be selected as the default gateway.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
      app_net_2:
        gw_priority: 1
      app_net_3:
networks:
  app_net_1:
  app_net_2:
  app_net_3:

priority

priority indicates in which order Compose connects the service’s containers to its networks. If unspecified, the default value is 0.

If the container runtime accepts a mac_address attribute at service level, it is applied to the network with the highest priority. In other cases, use attribute networks.mac_address.

priority does not affect which network is selected as the default gateway. Use the gw_priority field for that.

priority does not control the order in which networks connections are added to the container, it cannot be used to determine the device name (eth0 etc.) in the container.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

oom_kill_disable

If oom_kill_disable is set, Compose configures the platform so it won’t kill the container in case of memory starvation.

oom_score_adj

oom_score_adj tunes the preference for containers to be killed by platform in case of memory starvation. Value must be within [-1000,1000] range.

pid

pid sets the PID mode for container created by Compose. Supported values are platform specific.

pids_limit

pids_limit tunes a container’s PIDs limit. Set to -1 for unlimited PIDs.

pids_limit: 10

When both are set, pids_limit must be consistent with the pids attribute in the Deploy Specification

platform

platform defines the target platform the containers for the service run on. It uses the os[/arch[/variant]] syntax.

The values of os, arch, and variant must conform to the convention used by the OCI Image Spec.

Compose uses this attribute to determine which version of the image is pulled and/or on which platform the service’s build is performed.

platform: darwin
platform: windows/amd64
platform: linux/arm64/v8

privileged

privileged configures the service container to run with elevated privileges. Support and actual impacts are platform specific.

pull_policy

pull_policy defines the decisions Compose makes when it starts to pull images. Possible values are:

read_only

read_only configures the service container to be created with a read-only filesystem.

runtime

runtime specifies which runtime to use for the service’s containers.

The value of runtime is specific to the implementation. For example, runtime can be the name of an implementation of OCI Runtime Spec, such as “runc”.

web:
  image: busybox:latest
  command: true
  runtime: runc

secrets

secrets grants access to sensitive data defined by secrets on a per-service basis. Two different syntax variants are supported; the short syntax and the long syntax.

Compose reports an error if the secret doesn’t exist on the platform or isn’t defined in the secrets section of the Compose file.

Services can 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 access to it. Such grant must be explicit within service specification as secrets service element.

Short syntax

The short syntax variant only specifies the secret name. This grants the container access to the secret and mounts it as read-only to /run/secrets/<secret_name> 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 frontend service access to the server-certificate secret. The value of server-certificate is set to the contents of the file ./server.cert.

services:
  frontend:
    image: example/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

Long syntax

The long syntax provides more granularity in how the secret is created within the service’s containers.

Note

The uid, gid, and mode attributes are not implemented in Docker Compose when the secret source of the secret is a file, as bind-mount used under the hood doesn’t allow uid remapping.

The following example sets the name of the server-certificate secret file to server.crt within the container, sets the mode to 0440 (group-readable), and sets the user and group to 103. The value of server-certificate secret is provided by the platform through a lookup and the secret’s lifecycle is not directly managed by Compose.

services:
  frontend:
    image: example/webapp
    secrets:
      - source: server-certificate
        target: server.cert
        uid: "103"
        gid: "103"
        mode: 0o440
secrets:
  server-certificate:
    external: true

security_opt

security_opt overrides the default labeling scheme for each container.

security_opt:
  - label:user:USER
  - label:role:ROLE

For further default labeling schemes you can override, see Security configuration.

shm_size

shm_size configures the size of the shared memory (/dev/shm partition on Linux) allowed by the service container. It’s specified as a byte value.

stop_grace_period

stop_grace_period specifies how long Compose must wait when attempting to stop a container if it doesn’t handle SIGTERM (or whichever stop signal has been specified with stop_signal), before sending SIGKILL. It’s specified as a duration.

    stop_grace_period: 1s
    stop_grace_period: 1m30s

Default value is 10 seconds for the container to exit before sending SIGKILL.

stop_signal

stop_signal defines the signal that Compose uses to stop the service containers. If unset containers are stopped by Compose by sending SIGTERM.

stop_signal: SIGUSR1

storage_opt

storage_opt defines storage driver options for a service.

storage_opt:
  size: '1G'

sysctls

sysctls defines kernel parameters to set in the container. sysctls can use either an array or a map.

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0

sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

You can only use sysctls that are namespaced in the kernel. Docker does not support changing sysctls inside a container that also modify the host system. For an overview of supported sysctls, refer to configure namespaced kernel parameters (sysctls) at runtime.

tmpfs

tmpfs mounts a temporary file system inside the container. It can be a single value or a list.

tmpfs: 
 - <path>
 - <path>:<options>

Available options:

services:
  app:
    tmpfs:
      - /data:mode=755,uid=1009,gid=1009
      - /run

ulimits

ulimits overrides the default ulimits for a container. It’s specified either as an integer for a single limit or as mapping for soft/hard limits.

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

use_api_socket

Compose v2.37.1

When use_api_socket is set, the container is able to interact with the underlying container engine through the API socket. User’s credentials are mounted inside container, so container acts as a pure delegate for user’s command regarding container engine. Typically, commands ran by container can pull and push on user’s registry.

user

user overrides the user used to run the container process. The default is set by the image (i.e. Dockerfile USER). If it’s not set, then root.

userns_mode

userns_mode sets the user namespace for the service. Supported values are platform specific and may depend on platform configuration.

userns_mode: "host"

uts

Compose v2.15.1

uts configures the UTS namespace mode set for the service container. When unspecified it is the runtime’s decision to assign a UTS namespace, if supported. Available values are:

    uts: "host"

volumes

volumes define mount host paths or named volumes that are accessible by service containers. You can use volumes to define multiple types of mounts; volume, bind, tmpfs, image or npipe.

If the mount is a host path and is only used by a single service, it can be declared as part of the service definition. To reuse a volume across multiple services, a named volume must be declared in the top-level volumes key.

The following example shows a named volume (db-data) being used by the backend service, and a bind mount defined for a single service.

services:
  backend:
    image: example/backend
    volumes:
      - type: volume
        source: db-data
        target: /data
        volume:
          nocopy: true
          subpath: sub
      - type: bind
        source: /var/run/postgres/postgres.sock
        target: /var/run/postgres/postgres.sock

volumes:
  db-data:

Short syntax

The short syntax uses a single string with colon-separated values to specify a volume mount (VOLUME:CONTAINER_PATH), or an access mode (VOLUME:CONTAINER_PATH:ACCESS_MODE).

Note

The SELinux re-labeling bind mount option is ignored on platforms without SELinux.

Note Relative host paths are only supported by Compose that deploy to a local container runtime. This is because the relative path is resolved from the Compose file’s parent directory which is only applicable in the local case. When Compose deploys to a non-local platform it rejects Compose files which use relative host paths with an error. To avoid ambiguities with named volumes, relative paths should always begin with . or ...

Note

For bind mounts, short syntax creates a directory at the source path on the host if it doesn’t exist. This is for backward compatibility with docker-compose legacy. It can be prevented by using long syntax and setting create_host_path to false.

Long syntax

The long form syntax allows the configuration of additional fields that can’t be expressed in the short form.

volumes_from

volumes_from mounts all of the volumes from another service or container. You can optionally specify read-only access ro or read-write rw. If no access level is specified, then read-write access is used.

You can also mount volumes from a container that is not managed by Compose by using the container: prefix.

volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw

working_dir

working_dir overrides the container’s working directory which is specified by the image, for example Dockerfile’s WORKDIR.