Application Settings¶

This page describes the settings that can be used to configure the doco-cd application. The settings can be set via environment variables, a .env file, or Docker secrets.

GIT_ACCESS_TOKEN=<your Git token>

services:
  app:
    container_name: doco-cd
    image: ghcr.io/kimdre/doco-cd:latest
    restart: unless-stopped
    ports:
      - "80:80"
    env_file:
      - .env
    environment:
      TZ: Europe/Berlin
      LOG_LEVEL: INFO
      WEBHOOK_SECRET_FILE: /run/secrets/webhook_secret #(1)!
    secrets:
      - webhook_secret
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - data:/data

volumes:
  data:

secrets:
  webhook_secret:
    file: ./webhook_secret.txt

Runtime Settings¶

API and Webhook Settings¶

HTTP and Network Settings¶

Storage Settings¶

Artifact Garbage Collection Settings¶

Garbage collection only removes unreferenced immutable artifacts according to the retention settings above. Shared source directories, Git mirrors, submodule mirrors and mutable live/ data are not removed by the sweeper. Destroying a stack also keeps its shared source directory; see Source directory retention.

Source Garbage Collection Settings¶

OCI Registry Settings¶

Pulling images from a private registry¶

If you want to pull images from a private registry, see Container Registry Authentication.

Notification Settings¶

Doco-CD can be configured to send Notifications with Apprise to various services when a deployment is started, finished, failed, or triggered by reconciliation.

Reconciliation-triggered notifications use a short [R] marker in the title.
See Reconciliation notifications for configuration and format details.

Encrypting sensitive data¶

Doco-CD supports the encryption of sensitive data in your doco-cd app config and deployment files with SOPS.

See the Encryption wiki page for more information on how to use SOPS with Doco-CD.

Specifying the settings¶

You can set the settings directly in the docker-compose.yml file with the environment option or in a separate .env file with the env_file option.

Both options can be used at the same time.

With env_file¶

Example with env_file option:

services:
  app:
    env_file:
      - .env

The settings in the .env file must be in the format KEY=VALUE or KEY: VALUE, one setting per line.

Simple example¶

Example .env file:

GIT_ACCESS_TOKEN=xxx
WEBHOOK_SECRET=xxx

Multiline YAML options¶

For multiline YAML options like POLL_CONFIG, SOURCE_URL_REWRITES and SYNC_WINDOWS, the .env file format does not support multiline values. Instead, use the corresponding *_FILE environment variables to point to separate YAML files:

POLL_CONFIG_FILE=/mnt/poll-config.yaml
SOURCE_URL_REWRITES_FILE=/mnt/source-url-rewrites.yaml

Then create the YAML files:

- url: https://github.com/example/repo1.git
  interval: 300
- url: https://github.com/example/repo2.git
  reference: dev
  interval: 600

"https://forgejo.example.com/": "http://forgejo:3000/"
"git@forgejo.example.com:": "ssh://git@forgejo.internal:2222/"

services:
  app:
    volumes:
      - ./poll-config.yaml:/mnt/poll-config.yaml:ro
      - ./source-url-rewrites.yaml:/mnt/source-url-rewrites.yaml:ro

Alternatively, use the environment option in docker-compose.yml instead of .env to set multiline values directly (see below).

With environment¶

Simple example¶

Example with environment option:

services:
  app:
    environment:
      GIT_ACCESS_TOKEN: xxx
      WEBHOOK_SECRET: xxx

Multiline YAML options¶

For multiline YAML options like POLL_CONFIG, SOURCE_URL_REWRITES and SYNC_WINDOWS, use YAML's literal block scalar (|):

services:
  app:
    environment:
      POLL_CONFIG: |
        - url: https://github.com/example/repo1.git
          interval: 300
        - url: https://github.com/example/repo2.git
          reference: dev
          interval: 600
      SOURCE_URL_REWRITES: |
        "https://forgejo.example.com/": "http://forgejo:3000/"
        "git@forgejo.example.com:": "ssh://git@forgejo.internal:2222/"

Usage with Docker Secrets¶

The application can also be configured to use Docker secrets for sensitive information like the Git access token and the webhook secret.

To use Docker secrets, you need to create the secrets in Docker and then reference them in the docker-compose.yml file.

Create Docker Secrets¶

Create Docker secrets (only with Docker Swarm)

echo "<your Git token>" | docker secret create git_access_token -
echo "<random secret>" | docker secret create webhook_secret -

Reference Docker Secrets in docker-compose.yml¶

services:
  app:
    container_name: doco-cd
    image: ghcr.io/kimdre/doco-cd:latest
    restart: unless-stopped
    ports:
      - "80:80"
    environment:
      TZ: Europe/Berlin
      GIT_ACCESS_TOKEN_FILE: /run/secrets/git_access_token # (1)!
      WEBHOOK_SECRET_FILE: /run/secrets/webhook_secret
    secrets: # (2)!
      - git_access_token
      - webhook_secret
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - data:/data

volumes:
  data:

secrets:
  git_access_token:
    external: true
  webhook_secret:
    external: true

1. The file name after the /run/secrets/ path is the name of the secret
2. Secret names must match with the secrets: top-level section below

Deploy in Docker Swarm mode¶

To run the application in Docker Swarm mode, you need to use the docker stack deploy command instead of docker compose up.

docker stack deploy -c docker-compose.yml doco-cd

Check the logs¶

To check the logs of the application, you can use the following command:

docker service logs doco-cd_app

Check the status of the service¶

To check the status of the service, you can use the following command:

docker service ps doco-cd_app