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.

Deployments for different stacks - even the same repository, or the same repository and reference - run in parallel, up to the configured concurrency limit. Only deployments of the same stack are ever serialized, so one repository can never block deployments of an unrelated stack.

App Configuration¶

Use the following environment variables to configure the behavior of the doco-cd application itself. These settings are global and affect all deployments.

Deployment Sources¶

Doco-CD supports deploying from the following sources:

Deployment Configuration File¶

The deployment configuration file must be placed in DEPLOY_CONFIG_BASE_DIR, relative to your Git repository or OCI artifact root, 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.

The default base directory is the source root. With DEPLOY_CONFIG_BASE_DIR=deploy/, place the configuration in deploy/.doco-cd.y(a)ml. Lookup does not fall back to the root. working_dir remains relative to the source root, and Compose file paths remain relative to working_dir.

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.

Editor autocomplete and validation¶

Doco-CD provides a JSON Schema for deployment YAML files. Compatible editors can suggest settings and values, display descriptions and defaults on hover, and flag unknown settings or incorrect value types. The schema is generated from the deployment configuration's Go types, field descriptions, and defaults. Its x-doco-cd-version metadata identifies the Doco-CD release or source revision used to generate it.

# yaml-language-server: $schema=https://doco.cd/latest/schemas/deploy.schema.json
name: my-app
working_dir: deploy

{
  "yaml.schemas": {
    "https://doco.cd/latest/schemas/deploy.schema.json": [
      "**/.doco-cd.yml",
      "**/.doco-cd.yaml",
      "**/.doco-cd.*.yml",
      "**/.doco-cd.*.yaml"
    ]
  }
}

# $schema: https://doco.cd/latest/schemas/deploy.schema.json
name: my-app

Schema association comments are ignored by doco-cd and do not change deployment behavior. The schema describes one deployment mapping per YAML document, including files that separate deployments with ---.

Choosing a schema version¶

Choose the release-series URL matching your doco-cd version when using an older release. Documentation URLs are versioned by major/minor series, not immutable patch releases. The next schema becomes available when these changes are published to the development docs; latest and release-series URLs become available with releases that include the schema. For offline use, download the schema and associate a local file instead of the URL.

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

Dotenv File Format¶

Doco-CD parses env_files using the same dotenv engine as Docker Compose itself (compose-go), so the syntax (comments, quoting, export, variable substitution, etc.) matches the Compose .env file reference.

One notable difference from a plain .env file: variables resolved from an earlier env_files entry (or from environment) can be referenced with ${VAR} in a later one, e.g. to conditionally override or pass through a value:

TEST_PATH=/data

TEST_PATH=${TEST_PATH} # keeps the value from base.env unless overridden here

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.

Doco-cd scans the revision the deployment job resolved, so the discovered stacks always match the deployed revision. If the deploy config scans another reference or repository_url (also supported in inline poll configs), doco-cd fetches and publishes that revision first and scans the published files, so nested config files may be encrypted with SOPS or be symlinks, just like in the job's own repository.

Scheduled runs and certificate-rotation reloads read the deployment configuration from its recorded config-source artifact. A deployment's reference may differ from that artifact's revision; discovery resolves that reference separately rather than assuming it points to the config-source revision.

When auto_discovery.delete is set to true and 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 remove the deployed project/stack from the docker host. See Removing obsolete stacks.

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

Removing obsolete stacks¶

Before deploying, doco-cd looks for stacks it auto-discovered from the same repository (for OCI artifacts, the same registry/repository and stable source tag) and deployment target that no deployment config of the run has anymore, neither a discovered nor an explicit one. Stopped stacks are included. An OCI tag moving to a new digest keeps its ownership, but independently polled tags cannot remove each other's stacks. Missing or ambiguous stable-reference ownership preserves the stack; see OCI cleanup ownership.

The delete, remove_volumes and remove_images settings of an obsolete stack are taken from the current auto-discovery config whose working_dir and depth cover the stack's directory. If several do, all of them must allow the removal. If none does, e.g. because the auto-discovery config was removed, the settings the stack was deployed with are used. They are stored in the cd.doco.deployment.auto_discovery.config label of the stack; a stack with an empty or unreadable label is kept. The current discovery settings still apply when a scan finds no stacks, including when the last stack was removed. Failed scans do not authorize removal.

An obsolete stack is also kept if

• the webhook filter of its auto-discovery config does not match the webhook event,
• it runs a newer commit than the one doco-cd scanned, e.g. because a newer deployment finished first,
• its ownership or Git ancestry cannot be established, e.g. because the mirror lacks the deployed commit,
• it is redeployed while doco-cd removes obsolete stacks, or
• a sync window blocks the removal.

When several references scan the same directory, the newer-commit guard uses the scan of the stack's deployed reference, not an older scan of a different reference. Missing reference metadata, or no current scan of the deployed reference, retains the conservative ancestry guard. All covering configs must still permit removal.

Reconciliation uses the latest request's discovery ownership and removal settings, even when a webhook filter or sync window defers deployment. Recovery of a deferred stack still uses its previously deployed config and source.

Failed removals, inconclusive revision checks, and sync-window deferrals are retried automatically with capped backoff, even without another webhook or source change. Each retry reads the current source configuration and checks Docker state and removal permissions again. Restoring a stack or disabling deletion prevents the pending removal. Actual cleanup errors fail the triggering run but do not stop unrelated deployments.

Pending retries are kept only in memory. Restarting doco-cd clears them until the source is processed again. Cleanup retries do not deploy newly discovered stacks or restore missing workloads.

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 key is set in the nested config, even to false, 0 or an empty string. Keys set to null keep the base value.
• Nested objects (such as build, destroy, retry, reconciliation) are merged recursively. The boolean shorthand for destroy, auto_discovery, and reconciliation only sets the object's enabled field.
• YAML merge keys (<<) are resolved before these overrides are applied: explicit keys replace merged values, and earlier entries in a merge sequence take precedence over later ones. A replacement does not retain the shadowed mapping's children; an explicit null shadows the merged value and keeps the base setting.

remove_orphans: false
destroy:
  remove_volumes: false # (1)!

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.

doco-cd only destroys a stack that it deployed from the same source: the repository containing the deployment configuration file, the repository set in repository_url, or, for OCI artifacts, the same artifact repository regardless of its tag or digest. The ownership check includes the canonical source URL, registry/host, and source type. Legacy labels without a source URL must include both a source type and the full host-qualified repository name; hostless names alone are ambiguous. Missing, conflicting, or ambiguous ownership skips destruction and is reported as a conflict.

name: some-project
destroy: true

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

Pause Settings¶

Use pause: true to freeze deployment changes without stopping or removing existing workloads.

With reconciliation.enabled, doco-cd still restores the last-deployed configuration and revision. It never deploys a newer revision or a changed configuration while paused. Pause does not enable reconciliation or change its behavior when it is disabled. For a full deployment-and-recovery freeze, combine pause: true with reconciliation: false:

name: production
pause: true
reconciliation: false

Triggers and operational boundaries¶

• Pause takes effect on the next trigger that successfully resolves a valid, trusted configuration, not immediately when a Git file changes. The configuration source continues to be fetched so a cleared flag can be detected.
• All deployment triggers honor pause: polling, webhooks, local watchers, and manual REST/MCP polls. It blocks first deployment, updates, mode migration, deployment-driven destruction and cleanup, and automatic certificate reissuance/redeployment. Manual retry privileges, force_recreate, image-pull settings, and destroy do not bypass pause. Effective inline deployment definitions replace repository definitions and remain authoritative.
• Operations already admitted to mutation finish normally. Pause does not abort a running replacement or destruction halfway through.
• Pause is independent of sync windows; an open window or manual bypass does not override it. After resume, normal change detection, source trust, sync windows, and retry policies apply; paused revisions are not queued or replayed.
• Existing scheduled jobs keep running from their deployed definitions, even with pause: true. Updates to those definitions wait while deployment updates are paused.
• Explicit Docker, REST API, and MCP lifecycle controls (start, stop, restart, scale, destroy, or remove) remain available. Docker restart policies and native Swarm healing are unchanged, including with reconciliation: false.

Pause differs from preserving a service's running state, stopping workloads, retry suppression, or time-based sync windows. Runs whose deployments are all paused are reported as skipped, not failed; mixed runs succeed if active work succeeds, and real failures take precedence.

Retry Settings¶

retry controls automatic retries after a failure in the deploy, post-deploy, or cleanup stage for both Compose projects and Swarm stacks. Omitting retry preserves unlimited automatic retries without an additional delay.

Use a finite budget together with a positive delay to limit repeated interruptions from a broken release.

name: example
retry:
  limit: 2
  delay: 5m

Once the budget is exhausted, automatic deployment attempts for that same desired revision/configuration remain paused. The budget does not refill after the retry delay expires. Doco-CD continues resolving the source so a new Git revision, OCI digest, effective configuration, or desired image identity can receive a fresh budget without the old delay. A different error message does not reset the budget. Complete deployment success clears the failure and retry state.

The retry object inherits omitted settings from the base config.
For example, a nested retry: {limit: 0} disables automatic retries for that discovered deployment while retaining the base delay. An explicit delay: 0 removes the inherited delay.

Manual retry¶

An explicit deployment trigger through the REST polling endpoint or the MCP trigger_poll tool bypasses both delay and exhaustion for that attempt only, including when limit: 0. This applies with either wait: true or wait: false. A failed manual attempt updates the failure details and retry-delay deadline but neither consumes nor refills the automatic retry budget; an exhausted budget stays exhausted and a successful manual attempt clears the state. Manual retries still obey sync windows, source trust checks, and other deployment safety checks.

Polling, webhooks, local watcher triggers, and full redeploy reconciliation share the automatic budget for the affected target. Webhooks and reconciliation are not manual retries. Setting force_recreate: true does not bypass the policy. While an automatic retry is suppressed, the desired release remains failed even if Swarm has rolled back to a healthy older release.

Scope¶

Source-fetch, initialization, and pre-deploy failures retain their existing retry behavior and do not consume this budget. Direct container restarts, scheduled jobs, and destroy operations are outside this policy. In particular, retry.limit is separate from reconciliation's container restart_limit and restart_window.

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. Full redeploy reconciliation obeys the deployment's retry policy but direct container restarts do not.

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.

Preserve a service's running state¶

Docker Compose services are started automatically after they are created or updated. To let an external tool control a service's lifecycle, set the cd.doco.deployment.autostart service label to false.

services:
  on-demand:
    image: example/on-demand:latest
    labels:
      cd.doco.deployment.autostart: "false"

The label defaults to true. When it is false:

• A service without an existing container is created but not started.
• A stopped service remains stopped when it is recreated or updated.
• An existing stopped service does not cause a deployment on an otherwise unchanged poll, unless some of its containers are missing.
• A running service is restarted normally when it is recreated or updated.
• A service that remains stopped is excluded from deployment readiness checks.

The label controls only deployment-triggered startup; manual actions, restart policies, reconciliation, and external lifecycle tools can still start or stop the service.

Dependencies on an opted-out stopped service are not started or waited for during deployment. Ensure dependent services can tolerate that service being unavailable until an external tool starts it.

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

Ignored files and directories from the repository are mounted from a live copy that doco-cd updates in place on each deployment, so the service sees the changed content without being recreated (e.g. to reload it on a signal or by watching the files). A service is recreated once when it starts or stops using live copies, e.g. after adding or changing this label.

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

Swarm settings¶

The following settings can be configured in the nested swarm object:

Use swarm.enabled to select the deployment type for one stack:

name: netbird
swarm:
  enabled: false

When the value of enabled changes for a doco-cd-managed deployment, doco-cd removes the previous-mode project or stack before deploying the new mode. Its volumes are retained during this migration.

Keep old Swarm configs/secrets¶

In Swarm mode, doco-cd creates content-hashed config/secret names and rotates them when content changes.

Use swarm.config_retention and swarm.secret_retention to keep old revisions:

• 0 keeps no old revisions (only active ones remain)
• 1 keeps one old revision per resource type
• -1 disables automatic pruning for that resource type
• if unset, the corresponding global Docker setting is used:
  • DOCKER_SWARM_CONFIG_RETENTION
  • DOCKER_SWARM_SECRET_RETENTION

name: some-project
swarm:
  config_retention: 2
  secret_retention: 1

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.