Application Settings¶

General Settings¶

The application can be configured using the following environment variables:

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 and SOURCE_URL_REWRITES, 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 and SOURCE_URL_REWRITES, 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

Pulling images from a private registry¶

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

Source URL Rewrites¶

SOURCE_URL_REWRITES (and SOURCE_URL_REWRITES_FILE) let you rewrite git source URLs before doco-cd clones them. Rules apply to both webhook- and poll-triggered deployments.

This is useful when your Git provider advertises a public URL (in webhook payloads or poll configs) but doco-cd should clone through an internal network path instead — for example when your Forgejo instance is behind a reverse proxy with a public domain, but is reachable directly over a Docker network.

Two match strategies are supported:

• URL/URI prefix — e.g. https://forgejo.example.com/ or git@forgejo.example.com:. The matched prefix in the source URL is replaced with the configured target, and the repository path is appended as-is.
  • HTTPS URLs should end with / to avoid partial host matches.
  • SCP-style SSH URLs (e.g. git@host:) must end with : — it is the mandatory separator between host and repository path in SCP syntax (user@host:path/repo.git).
  • SCP syntax cannot express a port number. Use ssh:// syntax when targeting a non-standard port (e.g. "ssh://git@forgejo.internal:2222/").
• Host/domain — e.g. forgejo.example.com. Only the host (and optional port) is replaced; scheme, credentials, and path are preserved.

Rules are matched in order of specificity (longest key first).

SOURCE_URL_REWRITES:
  # HTTPS → internal HTTP (key ends with / to avoid partial-host matches)
  "https://forgejo.example.com/": "http://forgejo:3000/"
  # Host-only match (replaces host+port, keeps scheme/path)
  "forgejo.example.com": "forgejo:3000"
  # SCP-style SSH → SCP-style SSH (the trailing : is required — it is the SCP host/path separator)
  # OR: SCP-style SSH → ssh:// with non-standard port (SCP syntax cannot carry a port number)
  # Pick one of these two, not both (YAML map keys must be unique):
  # "git@forgejo.example.com:": "git@forgejo.internal:"
  # "git@forgejo.example.com:": "ssh://git@forgejo.internal:2222/"

services:
  app:
    environment:
      SOURCE_URL_REWRITES: |
        # HTTP variant:
        "forgejo.example.com": "forgejo:3000"
        # SSH variant with explicit port:
        "git@forgejo.example.com:": "ssh://git@forgejo:2222/"