Deployment Settings¶

Deployments in Doco-CD run as concurrent tasks. Each deployment is defined by a deployment configuration file (e.g. .doco-cd.yml) that controls how it runs. Enable auto_discover to generate multiple deployments from a single config by scanning subdirectories for Docker Compose files.

Concurrent tasks are grouped by repository and Git reference (e.g. branch or tag). Deployments from the same repository but different references run sequentially, while those with the same repository and reference run in parallel. See the App Settings documentation for more information on how to configure the number of concurrent deployments.

Deployment Configuration File¶

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

If you use polling, you can also specify inline deployment configurations in the poll configuration file. See Poll Settings and this example for more information.

Available Settings¶

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

Example¶

With default values¶

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

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

With custom values¶

name: some-project # name of the deployed stack/project
reference: other-branch # use this branch for deployment
working_dir: myapp/deployment # move to this subdirectory 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)

From remote repository¶

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 subdirectory of the other repository that contains the docker compose files.

You can use the env_files setting to define which dotenv files will be loaded from the local and which from the remote repository. To specify, that a dotenv file should be loaded from the remote repository, use the remote:<filepath> syntax. Entries/Keys, that appear in multiple files, get overwritten by the next occurrence and remote dotenv files have higher priority than local ones.

name: some-project # name of the deployed stack/project
repository_url: https://github.com/my-org/myapp.git # use this repository for deployment
reference: main # use this branch in the my-org/myapp repository for deployment
working_dir: myapp/docker # move to this subdirectory in the my-org/myapp repository for deployment
env_files: # List of dotenv files to use
  - base.env # from local repository
  - remote:test.env # from other/remote repository

TEST=base
HELLO=world

TEST=changed

This will result in the following environment variables being set for the deployment in the remote repository:

TEST=changed
HELLO=world

Auto discover settings¶

If auto_discover is set to true, doco-cd will try to auto-discover projects/stacks to deploy by searching for docker-compose.y(a)ml or compose.y(a)ml files in subdirectories in the working directory (working_dir). Doco-cd will internally generate new deploy configs based on the directory name and inherits all other settings from the base deploy config inside the .doco-cd.yml file or the inline deployment config inside the poll config. When an app is no longer available in the working_dir (e.g. deleted or moved to another directory outside the working dir), doco-cd will automatically remove the deployed project/stack from the docker host.

Specify all auto-discover settings in a nested auto_discover_opts object in the deployment configuration file (See example below).

Example¶

With a file structure like this

.doco-cd.yml
apps/
├── wordpress/
│   ├── docker-compose.yml
│   └── .env
├── nginx/
│   ├── docker-compose.yaml
│   └── configs/
│       └── nginx.conf
└── misc/
    └── image.png

and a .doco-cd.yml with the following content:

working_dir: apps/
auto_discover: true
auto_discover_opts:
  depth: 1

doco-cd would deploy 2 stacks to the docker host: - wordpress - nginx

Build settings¶

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 in the deployment configuration file (See example below).

Example¶

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

Destroy settings¶

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 in the deployment configuration file (See example below).

Example¶

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

Webhook Filter¶

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.

Explicit examples¶

• 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]+$)

Loose examples¶

• Must contain stable somewhere in the reference: stable

E.g. refs/heads/main (without ^ and $) also allows refs/heads/main-something

Service Labels¶

Avoid service recreation when configs, secrets or bind mounts change¶

When using docker compose with configs, secrets or bind mounts, changes to these resources will trigger a recreation of the service containers by default. To avoid this, you can set the cd.doco.deployment.recreate.ignore service label to a YAML list of scopes that should be ignored for recreation.

It's a map of scope → items to ignore; null or an empty value tells doco-cd to ignore all items in that scope. It accepts one or more of the following scopes: configs, secrets, bindMounts.

1. configs and secrets items refer to names defined in the top-level configs and secrets sections.
2. bindMounts items refer to the target paths of bind mounts (not the source paths).

Example¶

# Quotes are required to prevent YAML parsing errors due to the colons and brackets in the value
cd.doco.deployment.recreate.ignore: "{configs: [app, nginx], secrets: [db], bindMounts: [/etc/caddy]}"

Or as a multiline YAML for better readability:

cd.doco.deployment.recreate.ignore: >-
  {
    configs: [app, nginx],
    secrets: [db],
    bindMounts: [/etc/caddy]
  }

Add the cd.doco.deployment.recreate.ignore.signal label to send a signal to a service when it is ignored. By default, no signal is sent. This requires cd.doco.deployment.recreate.ignore to be set.

Both labels must not be empty if they are present.

services:
  caddy:
    image: caddy:2.11.2@sha256:1e40b251ca9639ead7b5cd2cedcc8765adfbabb99450fe23f130eefabf50f4bc
    container_name: caddy
    restart: always
    user: "1000:1000"
    environment: {}
    labels:
      cd.doco.deployment.recreate.ignore: "{bindMounts: [/etc/caddy]}"
      cd.doco.deployment.recreate.ignore.signal: "SIGHUP"
    ports:
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./conf:/etc/caddy"
      - "/data/certs:/certs:ro"
    command:
      [
        "caddy",
        "run",
        "--watch",
        "--config",
        "/etc/caddy/Caddyfile",
        "--adapter",
        "caddyfile",
      ]
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE

Multiple service deployments¶

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

Example¶

Same directory¶

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

Sub-directories¶

When docker compose files are located in subdirectories.

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

Multiple deployment targets¶

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.

Running pre- and post-deployment scripts¶

Doco-CD does not provide a shell environment for security reasons. Therefore, running shell scripts inside the Doco-CD container is not supported. Instead, you can use init containers, sidecar containers, or compose lifecycle hooks to run scripts in the context of the deployed containers. See the Pre- and Post-Deployment Scripts page for more information on how to set this up.