The deployment configuration file must be placed in the root/base directory of your repository and named one of the following:

• .doco-cd.yaml
• .doco-cd.yml

The docker compose deployment can be configured inside the deployment configuration file using the following settings:

When using the default values, most settings can be omitted.

name: some-project # name of the deployed stack/project

name: some-project # name of the deployed stack/project
reference: other-branch # use this branch for deployment
working_dir: myapp/deployment # move to this sub-directory for deployment
compose_files: # List of docker compose files to use in descending order
  - prod.compose.yml
  - service-overwrite.yml
profiles:
  - debug # Deploys debug services in addition to the core/main services (that have no profiles)

When deploying your docker compose stack from a different repository, the repository_url setting must be specified. The reference and working_dir are used in this case to specify the branch/tag and sub-directory of the other repository that contains the docker compose files.

name: some-project # name of the deployed stack/project
repository_url: https://github.com/my-org/myapp.git # use this repository for deployment
reference: other-branch # use this branch in the my-org/myapp repository for deployment
working_dir: myapp/docker # move to this sub-directory in the my-org/myapp repository for deployment

The following settings can be used to build docker images during a deployment (Like docker compose build or docker compose up --build).

Specify all build-settings in a nested build_opts object (See example) in the deployment configuration file.

name: some-project
build_opts:
  force_image_pull: true
  args:
    BUILD_DATE: 2021-01-01
    VCS_REF: 123456
  no_cache: true

The following settings can be used to configure further how the deployed compose stack/project will be removed (if destroy is set to true):

Specify all destroy-settings in a nested destroy_opts object (See example) in the deployment configuration file.

name: some-project
destroy: true
destroy_opts:
  remove_volumes: true
  remove_images: false
  remove_dir: false

Set webhook_filter to a regular expression to whitelist deployment triggers based on the webhook event payload.

Depending on the event, the reference in a webhook payload has a pattern of

• refs/heads/<branch> for branches
• refs/tags/<tag> for tags
• Or no reference at all if the event is not associated with a tag or a branch event

You can specify the filter explicitly or in a loose form. Explicit regular expressions are recommended.
See Go Regular Expressions for more information on the syntax.

• Only on events on the main branch: ^refs/heads/main$
• Only on tag events with semantic versioning: ^refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$)

• Must contain stable somewhere in the reference: stable

Multiple service deployments can be configured in a single deployment config file by specifying multiple YAML documents (separated by ---).

name: app1
working_dir: app1
---
name: app2
working_dir: app2
timeout: 600
---
name: app3
working_dir: app3
compose_files:
  - custom.yml

All docker compose files are located in the same base directory.

name: gitea
compose_files: 
  - gitea.yml
---
name: paperless-ngx
compose_files:
  - paperless.yml
  - paperless-overwrite.yml

When docker compose files are located in sub-directories.

name: gitea
working_dir: gitea
---
name: paperless-ngx
working_dir: paperless-ngx
compose_files:
  - docker-compose.yml
  - docker-compose.overwrite.yml

Further examples can be found in the examples section below.

You can specify multiple deployment target configurations in a mono-repo style setup using the application's dynamic webhook path. This allows you to deploy to different targets/locations from a single repository. See Webhook Listener with custom Target for more information.