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.

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 Sources¶

Doco-CD supports deploying from the following sources:

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

When using a custom target (for example nas), the file name must match .doco-cd.<target>.y(a)ml.

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:

name: some-project # (1)!

name: some-project # (1)!
reference: other-branch # (2)!
working_dir: myapp/deployment # (3)!
compose_files: # (4)!
  - prod.compose.yml
  - service-overwrite.yml
profiles:
  - debug # (5)!

name: some-project # (1)!
repository_url: https://github.com/my-org/myapp.git # (2)!
reference: main # (3)!
working_dir: myapp/docker # (4)!
env_files: # (5)!
  - base.env # (6)!
  - remote:test.env # (7)!

TEST=base
HELLO=world

TEST=changed

TEST=changed
HELLO=world

Auto-Discovery¶

If auto_discovery is enabled, doco-cd will try to find projects/stacks to deploy by searching for docker compose files (see the compose_files setting) 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.

Auto-Discovery settings¶

auto_discovery accepts either a boolean or a nested object in the deployment configuration file. Use auto_discovery: true to enable it with defaults, or use the object form below to customize the settings.

Controlling resource cleanup on stack deletion¶

When auto-discovered stacks are deleted (e.g., because the compose file was removed from the repository), you can control whether volumes and images are removed using the remove_volumes and remove_images settings in the auto_discovery configuration:

working_dir: apps/
auto_discovery:
  enabled: true
  delete: true
  remove_volumes: false # (1)!
  remove_images: true # (2)!

1. Keep volumes when stacks are auto-deleted
2. Remove images when stacks are auto-deleted

Nested config overrides¶

For each auto-discovered compose directory, doco-cd also checks for a local deployment config file in that directory.

If a nested config file exists, doco-cd merges it on top of the discovered deployment config. When using custom webhook targets, nested config files always use the standard naming convention (.doco-cd.y(a)ml), not the custom target name.

Merge behavior¶

• Maps are merged key-by-key (external_secrets, environment, build.args)
• Slices replace the base value when the nested value is non-empty
• Scalar values override the base value when the nested value is non-zero/non-empty
• Nested objects (such as build, destroy, reconciliation) are merged recursively

Non-overridable Fields¶

The following fields are always inherited from the base/root deployment config:

• reference
• repository_url
• auto_discovery
• git_depth

Example¶

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

working_dir: apps/
auto_discovery:
  enabled: true
  depth: 1
external_secrets:
  SHARED_SECRET: "op://vault/shared/field"

name: wordpress-prod
external_secrets:
  WORDPRESS_SECRET_1: "op://vault/item/field"
environment:
  WP_ENV: production

Build settings¶

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

See also the Compose Build Specification for more information on building docker images with compose.

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

name: some-project
build:
  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 how the deployed compose stack/project will be removed.

destroy accepts either a boolean or a nested object in the deployment configuration file. Use destroy: true to enable destructive removal with default options, or use the object form below to customize which resources are removed.

name: some-project
destroy: true

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

Reconciliation Settings¶

Reconciliation is an optional event-driven check that compares the currently running Docker services/containers with the expected deployment state. When configured container events occur, doco-cd either reapplies the deployment or directly restarts the affected container, depending on the event type.

reconciliation accepts either a boolean or a nested object in the deployment configuration file. Use reconciliation: true to enable it with defaults, or use the object form below to customize the settings.

The following settings can be used to configure reconciliation triggers.

Supported Events¶

Events can be triggered by changes in the container state, configuration updates outside Doco-CD (e.g. via Docker CLI), or health status changes. The following events are supported as reconciliation triggers in Docker (Standalone) and Docker Swarm deployments:

Examples¶

name: some-project
reconciliation: true

name: some-project
reconciliation:
  enabled: true
  restart_timeout: 30
  restart_signal: SIGQUIT
  restart_limit: 5
  restart_window: 300
  events:
    - destroy
    - unhealthy

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.

Prevent recreation on config, secret or bind mount changes¶

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

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

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

Send signal on ignored recreation¶

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

Wait for running scheduled jobs before deployment¶

By default, deployments wait for currently running scheduled jobs to finish before recreating/updating containers. This helps prevent long-running jobs from being interrupted by a deployment.

Use wait_running_jobs (default: true) in the deployment config to control the default behavior for that deployment target.

name: some-project
wait_running_jobs: true

You can override this per scheduled job service with the cd.doco.job.wait_running_jobs label (see Job Scheduling).

Precedence:

• Service label cd.doco.job.wait_running_jobs (if set)
• Deployment default wait_running_jobs

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

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

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.