knowledge/technology/tools/Docker Compose.md

obj	source	repo	rev
application	https://docs.docker.com/compose	https://github.com/docker/compose	2024-07-15

Docker Compose

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application's services. Then, with a single command, you create and start all the services from your configuration.

Usage

Usage: docker-compose [-f ComposeFile] [COMMAND] [OPTION]...

docker-compose up

Create and start containers.

Options

Option	Description
--build	Build images before starting containers.
-d, --detach	Detached mode: Run containers in the background

docker-compose down

Stops containers and removes containers, networks, volumes, and images created by up.

docker-compose build

Build or rebuild services

Options

Option	Description
--no-cache	Do not use cache when building the image
--pull	Always attempt to pull a newer version of the image.

docker-compose cp

Copy files/folders between a service container and the local filesystem
Usage: docker compose cp [OPTIONS] SERVICE:SRC_PATH DEST_PATH|-

docker-compose exec

This is the equivalent of docker exec targeting a Compose service.

Options

Option	Description
-d, --detach	Detached mode: Run command in the background.
-e, --env	Set environment variables
-i, --interactive	Keep STDIN open even if not attached.
-t, --tty	Allocate a pseudo-TTY.
-u, --user	Run the command as this user.
-w, --workdir	Path to workdir directory for this command.

docker-compose logs

Displays log output from services.

Options

Option	Description
-f, --follow	Follow log output
--since ts	Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)
-n, --tail num	Number of lines to show from the end of the logs
--until	Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)

docker-compose kill

Force stop service containers.

docker-compose ps

List running containers

docker-compose pull

Pull service images

docker-compose restart

Restart service containers

Docker Compose file

The Compose file is a YAML file defining:

• Version (Optional)
• Services (Required)
• Networks
• Volumes
• Secrets

Service Configuration

build

Build specifies the image that should be build for the service instead of using an image directly.
build can be specified either as a string containing a path to the build context:

version: "3.8"
services:
  webapp:
    build: ./dir

Or, as an object with the path specified under context and optionally Dockerfile and args:

version: "3.8"
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1

command

Override the default command.

command: bundle exec thin -p 3000

The command can also be a list, in a manner similar to dockerfile:

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

depends_on

depends_on expresses startup and shutdown dependencies between services.

services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

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"

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.

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

entrypoint: /code/entrypoint.sh

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

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.

healthcheck

healthcheck declares a check that's run to determine whether or not the service containers are "healthy". It works in the same way, and has the same default values, as the HEALTHCHECK Dockerfile instruction

set by the service's Docker image. Your Compose file can override the values set in the Dockerfile.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
  start_interval: 5s

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

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"

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:

• none: Turns off all container networking.
• host: Gives the container raw access to the host's network interface.
• service:{name}: Gives the containers access to the specified service only.

    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

ports

Exposes container ports.

The short syntax is a colon-separated string to set the host IP, host port, and container port in the form:

[HOST:]CONTAINER[/PROTOCOL] where:

• HOST is [IP:](port | range)
• CONTAINER is port | range
• PROTOCOL to restrict port to specified protocol. tcp and udp values are defined by the Specification.

If host IP is not set, it binds to all network interfaces. Ports can be either a single value or a range. Host and container must use equivalent ranges.

Either specify both ports (HOST:CONTAINER), or just the container port. In the latter case, Compose automatically allocates any unassigned port of the host.

HOST:CONTAINER should always be specified as a (quoted) string, to avoid conflicts with yaml base-60 float

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "8000-9000:80"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/udp"

privileged

privileged configures the service container to run with elevated privileges.

restart

restart defines the policy that the platform applies on container termination.

• no: The default restart policy. It does not restart the container under any circumstances.
• always: The policy always restarts the container until its removal.
• on-failure: The policy restarts the container if the exit code indicates an error.
• unless-stopped: The policy restarts the container irrespective of the exit code but stops restarting when the service is stopped or removed.

    restart: "no"
    restart: always
    restart: on-failure
    restart: unless-stopped

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.

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

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 container, or absolute path of the file if an alternate location is required. Defaults to source if not specified.
• uid and 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 permissions for the file to be mounted in /run/secrets/ in the service's task containers, in octal notation. The 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 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: 0440
secrets:
  server-certificate:
    external: true

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, or npipe.

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).

• VOLUME: Can be either a host path on the platform hosting containers (bind mount) or a volume name.
• CONTAINER_PATH: The path in the container where the volume is mounted.
• ACCESS_MODE: A comma-separated , list of options:
• • rw: Read and write access. This is the default if none is specified.
• • ro: Read-only access.

volumes:
  - ./volume:/mnt

Secrets

The top-level secrets declaration defines or references sensitive data that is granted to the services in your Compose application. The source of the secret is either file or environment.

• file: The secret is created with the contents of the file at the specified path.
• environment: The secret is created with the value of an environment variable.
• external: If set to true, external specifies that this secret has already been created. Compose does not attempt to create it, and if it does not exist, an error occurs.

secrets:
  server-certificate:
    file: ./server.cert

Docker Compose Deploy

The Compose Deploy Specification lets you declare additional metadata on services so Compose gets relevant data to allocate adequate resources on the platform and configure them to match your needs. Docker Swarm respects these specifications.

mode

mode defines the replication model used to run the service on the platform. Either global, exactly one container per physical node, or replicated, a specified number of containers. The default is replicated.

services:
  frontend:
    image: example/webapp
    deploy:
      mode: global

replicas

If the service is replicated (which is the default), replicas specifies the number of containers that should be running at any given time.

services:
  frontend:
    image: example/webapp
    deploy:
      mode: replicated
      replicas: 6

restart_policy

restart_policy configures if and how to restart containers when they exit. If restart_policy is not set, Compose considers the restart field set by the service configuration.

• condition. When set to:
• • none, containers are not automatically restarted regardless of the exit status.
• • on-failure, the container is restarted if it exits due to an error, which manifests as a non-zero exit code.
• • any (default), containers are restarted regardless of the exit status.
• delay: How long to wait between restart attempts, specified as a duration. The default is 0, meaning restart attempts can occur immediately.
• max_attempts: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not succeed within the configured window, this attempt doesn't count toward the configured max_attempts value. For example, if max_attempts is set to '2', and the restart fails on the first attempt, more than two restarts must be attempted.
• window: How long to wait before deciding if a restart has succeeded, specified as a duration (default: decide immediately).

deploy:
  restart_policy:
    condition: on-failure
    delay: 5s
    max_attempts: 3
    window: 120s

placement

placement specifies constraints and preferences for the platform to select a physical node to run service containers.
constraints

constraints defines a required property the platform's node must fulfill to run the service container. It can be set either by a list or a map with string values.

deploy:
  placement:
    constraints:
      - node.labels.disk == ssd
      - node.role == manager

deploy:
  placement:
    constraints:
      disktype: ssd

preferences defines a property the platform's node should fulfill to run service container. It can be set either by a list or a map with string values.

deploy:
  placement:
    preferences:
      - datacenter=us-east

deploy:
  placement:
    preferences:
      datacenter: us-east

resources

resources configures physical resource constraints for container to run on platform. Those constraints can be configured as:

• limits: The platform must prevent the container to allocate more.
• reservations: The platform must guarantee the container can allocate at least the configured amount.

The following can be configured:

• cpus: cpus configures a limit or reservation for how much of the available CPU resources, as number of cores, a container can use.
• memory: memory configures a limit or reservation on the amount of memory a container can allocate, set as a string expressing a byte value.
• pids: pids tunes a container’s PIDs limit, set as an integer.

deploy:
  resources:
    limits:
      cpus: 0.5
      memory: 128MiB
    reservations:
      cpus: 0.3
      memory: 64MiB