Deploy Settings

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

Warning

DEPRECATED: These file names are deprecated and will be removed in a future release. Please use the new file names above instead.

• .compose-deploy.yaml
• .compose-deploy.yml

Deployment Settings

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

Note

Settings without a default value are required.

Key	Type	Description	Default value
name	string	Name of the deployed stack / project / application.
reference	string	Git reference to the deployment, e.g. branch refs/heads/main or tag refs/tags/v1.0.0	refs/heads/main
working_dir	string	The working directory for the deployment.	.
compose_files	array of strings	List of docker-compose and overwrite files to use (in descending order, first file gets read first and following files overwrite previous configs). Unknown/Non-existing files get skipped.	[compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml]
remove_orphans	boolean	Remove containers for services that are not (or no longer) defined in the Compose file.	true
force_recreate	boolean	Forces the recreation/redeployment of containers even if the configuration has not changed.	false
force_image_pull	boolean	Always pulls the latest version of the image tags you've specified if a newer version is available.	false
timeout	number	The time in seconds to wait for the deployment to finish before timing out.	180

Build settings

The following settings can be used to build docker images before deployment:

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

Key	Type	Description	Default value
force_image_pull	boolean	Always attempt to pull a newer version of the image	false
quiet	boolean	Quiet suppresses the build output	false
args	map of strings	A map of build-time arguments to pass to the build process	null
no_cache	boolean	Disables the use of the cache when building images	false

Multiple service deployments

Note

Since v0.11.0

Multiple service deployments can be configured in a single deploy 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

Further examples can be found in the examples section below.

Multiple deployment targets

Note

Since v0.12.0

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.

If a webhook payload gets sent to a custom path suffix /v1/webhook/<custom_name>, the application will look for a deployment configuration file with the same pattern in its name .doco-cd.<custom_name>.yaml.

Examples:

webhook target: /v1/webhook/gitea
deployment config file: .doco-cd.gitea.yaml

webhook target: /v1/webhook/paperless-ngx
deployment config file: .doco-cd.paperless-ngx.yaml

webhook target: /v1/webhook/my.server.com
deployment config file: .doco-cd.my.server.com.yaml

Example settings usage

With default values

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

name: some-project

With custom values

name: some-project
reference: refs/heads/other-branch
working_dir: myapp/deployment
compose_files: 
  - prod.compose.yml
  - service-overwrite.yml

With build settings

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

Multiple deployments in same directory

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

Multiple deployments in sub-directories

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