# community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose.

Note

This module is part of the community.docker collection (version 3.5.0).

To install it, use: `ansible-galaxy collection install community.docker`. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: `community.docker.docker_compose_v2`.

## Synopsis

- Uses Docker Compose to start and shutdown services.

- Swarm mode is not supported (thus secrets and configs are not supported).

- Configuration can be read from a Compose file or inline using the definition option.

- See the examples for more details.

## Requirements

The below requirements are needed on the host that executes this module.

- docker-compose >= 2.0.0

- PyYAML

## Parameters

Parameter | Comments
--- | ---

build

boolean

Use with state `present` to always build images prior to starting the application.

Equivalent to `docker-compose up --build`.

Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents.

If an existing image is replaced, services using the image will be recreated unless recreate is `never`.

Choices:

- `false` ← (default)

- `true`

definition dictionary | Compose file describing one or more services, networks and volumes. Mutually exclusive with files.

dependencies

boolean

When state is `present` specify whether or not to include linked services.

When false, equivalent to `docker-compose up --no-deps`.

When state is `pull` specify whether or not to also pull for linked services.

When true, equivalent to `docker-compose pull --include-deps`.

Choices:

- `false`

- `true` ← (default)

docker_host

aliases: docker_url

string

The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection string. For example, `tcp://192.0.2.23:2376`. If TLS is used to encrypt the connection, the module will automatically replace `tcp` in the connection URL with `https`.

If the value is not specified in the task, the value of environment variable `DOCKER_HOST` will be used instead. If the environment variable is not set, the default value will be used.

Default: `"unix://var/run/docker.sock"`

env_file path | By default environment files are loaded from a `.env` file located directly under the project_src directory. env_file can be used to specify the path of a custom environment file instead. The path is relative to the project_src directory. Equivalent to `docker-compose --env-file`.
files list / elements=path | List of Compose files. Files are passed to docker-compose in the order given. Equivalent to `docker-compose -f`.

nocache

boolean

Use with the build option to ignore the cache during the image build process.

Equivalent to `docker-compose build --no-cache`.

Choices:

- `false` ← (default)

- `true`

profiles list / elements=string | List of profiles to enable when starting services. Equivalent to `docker-compose --profile`.
project_name string | Provide a project name. Equivalent to `docker-compose --project-name`.
project_src path | Path to the root directory of the Compose project. Required when definition is provided.

pull

boolean

Use with state `present` to always pull images prior to starting the application.

Equivalent to `docker-compose up --pull always`.

When a new image is pulled, services using the image will be recreated unless recreate is `never`.

Choices:

- `false` ← (default)

- `true`

recreate

string

By default containers will be recreated when their configuration differs from the service definition.

Setting to `never` ignores configuration differences and leaves existing containers unchanged.

Setting to `always` forces recreation of all existing containers.

When set to `never`, equivalent to `docker-compose up --no-recreate`.

When set to `always`, equivalent to `docker-compose up --force-recreate`.

Choices:

- `"always"`

- `"never"`

- `"smart"` ← (default)

remove_images

string

Use with state `absent` to remove all images or only local images.

Equivalent to `docker-compose down --rmi all|local`.

Choices:

- `"all"`

- `"local"`

remove_orphans

boolean

Remove containers for services not defined in the Compose file.

Equivalent to `docker-compose up --remove-orphans` or `docker-compose down --remove-orphans`.

Choices:

- `false` ← (default)

- `true`

remove_volumes

boolean

Use with state `absent` to remove data volumes.

Equivalent to `docker-compose down --volumes`.

Choices:

- `false` ← (default)

- `true`

services list / elements=string | When state is `present` run `docker-compose up` resp. `docker-compose stop` (with stopped) resp. `docker-compose restart` (with restarted) on a subset of services. If empty, which is the default, the operation will be performed on all services defined in the Compose file (or inline definition).

state

string

Desired state of the project.

Specifying `pulled` is the same as running `docker-compose pull`.

Specifying `built` is the same as running `docker-compose build`.

Specifying `stopped` is the same as running `docker-compose stop`.

Specifying `present` is the same as running `docker-compose up`.

Specifying `restarted` is the same as running `docker-compose restart`.

Specifying `absent` is the same as running `docker-compose down`.

Choices:

- `"absent"`

- `"built"`

- `"present"` ← (default)

- `"pulled"`

- `"restarted"`

- `"stopped"`

timeout integer | Timeout in seconds for container shutdown when attached or when containers are already running. By default `compose` will use a `10s` timeout unless `default_grace_period` is defined for a particular service in the project_src.

## Attributes

Attribute | Support | Description
--- | --- | ---
check_mode | Support: none | Check mode is not supported because the `docker-compose` CLI doesn’t allow it.
diff_mode | Support: none | Diff mode is not supported.

## Examples

    # Examples use the django example at https://docs.docker.com/compose/django. Follow it to create the
    # flask directory

    - name: Run using a project directory
      hosts: localhost
      gather_facts: false
      tasks:
        - name: Tear down existing services
          community.docker.docker_compose:
            project_src: flask
            state: absent

        - name: Create and start services
          community.docker.docker_compose:
            project_src: flask
          register: output

        - ansible.builtin.debug:
            var: output

        - name: Run `docker-compose up` again
          community.docker.docker_compose:
            project_src: flask
            build: false
          register: output

        - ansible.builtin.debug:
            var: output

        - ansible.builtin.assert:
            that: not output.changed

        - name: Stop all services
          community.docker.docker_compose:
            project_src: flask
            build: false
            stopped: true
          register: output

        - ansible.builtin.debug:
            var: output

        - ansible.builtin.assert:
            that:
              - "'stopped' in containers['flask_web_1'] | default([])"
              - "'stopped' in containers['flask_db_1'] | default([])"

        - name: Restart services
          community.docker.docker_compose:
            project_src: flask
            build: false
            restarted: true
          register: output

        - ansible.builtin.debug:
            var: output

        - ansible.builtin.assert:
            that:
              - "'started' in containers['flask_web_1'] | default([])"
              - "'started' in containers['flask_db_1'] | default([])"

    - name: Run with inline Compose file version 2
      # https://docs.docker.com/compose/compose-file/compose-file-v2/
      hosts: localhost
      gather_facts: false
      tasks:
        - community.docker.docker_compose:
            project_src: flask
            state: absent

        - community.docker.docker_compose:
            project_name: flask
            definition:
              version: '2'
              services:
                db:
                  image: postgres
                web:
                  build: "{{ playbook_dir }}/flask"
                  command: "python manage.py runserver 0.0.0.0:8000"
                  volumes:
                    - "{{ playbook_dir }}/flask:/code"
                  ports:
                    - "8000:8000"
                  depends_on:
                    - db
          register: output

        - ansible.builtin.debug:
            var: output

        - ansible.builtin.assert:
            that:
              - "'started' in containers['flask_web_1'] | default([])"
              - "'started' in containers['flask_db_1'] | default([])"

    - name: Run with inline Compose file version 1
      # https://docs.docker.com/compose/compose-file/compose-file-v1/
      hosts: localhost
      gather_facts: false
      tasks:
        - community.docker.docker_compose:
            project_src: flask
            state: absent

        - community.docker.docker_compose:
            project_name: flask
            definition:
                db:
                  image: postgres
                web:
                  build: "{{ playbook_dir }}/flask"
                  command: "python manage.py runserver 0.0.0.0:8000"
                  volumes:
                    - "{{ playbook_dir }}/flask:/code"
                  ports:
                    - "8000:8000"
                  links:
                    - db
          register: output

        - ansible.builtin.debug:
            var: output

        - ansible.builtin.assert:
            that:
              - "'started' in containers['flask_web_1'] | default([])"
              - "'started' in containers['flask_db_1'] | default([])"

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Description
--- | ---
containers dictionary | A dictionary mapping containers to the various status they went through during `docker-compose` operation. A dict of lists, where dict keys are containers names and lists elements are statuses. Returned: always, unless when `docker-compose` was not given the chance to run Sample: `{"container_1": ["stopped", "removed"], "container_2": ["running"]}`

images

dictionary

A dictionary mapping images to the various status they went through during `docker-compose` operation.

A dict of lists, where dict keys are services names and lists elements are statuses.

`docker-compose` does not report images by their names, but by the name of the service which require them.

Returned: always, unless when `docker-compose` was not given the chance to run

Sample: `{"service_1": ["pulled"], "service_2": ["pulled"]}`

networks dictionary | A dictionary mapping networks to the various status they went through during `docker-compose` operation. A dict of lists, where dict keys are networks names and lists elements are statuses. Returned: always, unless when `docker-compose` was not given the chance to run Sample: `{"network1": ["created"], "network2": ["removed"]}`
stderr string | The stderr from docker-compose. Returned: always, unless when `docker-compose` was not given the chance to run
stdout string | The stdout from docker-compose. Returned: always, unless when `docker-compose` was not given the chance to run
volumes dictionary | A dictionary mapping volumes to the various status they went through during `docker-compose` operation. A dict of lists, where dict keys are volumes names and lists elements are statuses. Returned: always, unless when `docker-compose` was not given the chance to run Sample: `{"volume_1": ["created"], "volume_2": ["removed"]}`

### Authors

- Léo El Amri (@lel-amri)

### Collection links

Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication