Getting Started¶

## Uncomment the poll configuration section here and in the service `environment:` section if you want to enable polling of a repository.
#x-poll-config: &poll-config
#  POLL_CONFIG: |
#    - url: https://github.com/kimdre/doco-cd.git  # This is the repository to poll
#      reference: main  # Optional: specify the branch or tag to poll, defaults to 'main'
#      interval: 180  # Optional: specify the interval in seconds to poll the repository, defaults to 180 seconds (3 minutes)
#      target: ""  # Optional: use to target a specific deployment config file, e.g., "test" -> .doco-cd.test.yaml

services:
  app:
    container_name: doco-cd
    # You can also pin to a specific tag (version)
    # Available tags can be found here: https://github.com/kimdre/doco-cd/pkgs/container/doco-cd
    image: ghcr.io/kimdre/doco-cd:latest
    restart: unless-stopped
    ports:
      - "80:80" # Webhook endpoint
      - "9120:9120" # Prometheus metrics
    # For all available environment variables and explanations, see https://doco.cd/latest/App-Settings/
    environment:
      TZ: Europe/Berlin
      GIT_ACCESS_TOKEN: xxx
      # WEBHOOK_SECRET: xxx  # Uncomment this line and the webhook port above and set a secure secret if you want to use webhooks.
      # <<: *poll-config  # Uncomment this line to use the poll configuration from above (the `x-poll-config` section).
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      # The data volume (left side) can also be replaced with a bind mount to a local directory, for example:
      # - ./data:/data
      - data:/data
    cap_drop:
      - ALL
    healthcheck:
      test: [ "CMD", "/doco-cd", "healthcheck" ]
      start_period: 15s
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  data:

Find out about the Core Concepts of Doco-CD to understand how the application works and how to configure it.

You can find all available app settings on the App Settings wiki page.

If you run the application with Docker Swarm, see the Swarm Mode wiki page for more information.

Create a Git Access Token¶

The Git access token is used to authenticate with your Git provider (GitHub, GitLab, Gitea, etc.) and to clone or fetch your repositories via HTTP.

If you set a Git access token, doco-cd will always use it to authenticate with your Git provider. See Setup Access Token to create this access token and set the GIT_ACCESS_TOKEN environment variable to the access token value.

Deployment triggers¶

Doco-CD can be triggered to check for changes to deploy via webhooks or by polling the Git repositories at regular intervals. You can use either method or both methods together.

Webhooks¶

Webhooks are event-based triggers that notify doco-cd when there are changes in the repositories. This is the recommended way to trigger deployments as it is more efficient and faster than polling but requires doco-cd to be reachable from the internet (or local network if you self-host your Git provider) and some setup on your Git provider.

If you want to use webhooks, you need to set the WEBHOOK_SECRET environment variable to a secure secret and publish the webhook port. See Setup Webhook for more information.

Polling¶

Polling is a time-based trigger that checks the repositories for changes at regular intervals. This method does not require doco-cd to be reachable from the internet but is less efficient and slower than webhooks.

If you want to use polling, you need to set a poll configuration for each repository you want to use for deployments. See Poll Settings for more information.

Run doco-cd¶

After you have created the docker-compose.yml file, you can run doco-cd with the following command:

docker compose up -d

You can check the logs of the application with the following command:

docker compose logs -f

To be able to reach the application from external Git providers like GitHub or Gitlab, you need to expose the http endpoint of the application to the internet. You can use a reverse proxy like NGINX, Traefik or Caddy for this purpose.

Notes for Podman users¶

If you are using Podman instead of Docker, you may need to adjust the docker-compose.yml file to use the Podman socket instead of the Docker socket:

services:
  app:
    ...
    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
+      - /var/run/podman/podman.sock:/var/run/docker.sock
    ...

Deploy your first application¶

To deploy your first application, you need to configure the deployment settings in your Git repository. These settings are defined in a .doco-cd.yml file in the root of your repository and specify how the deployment should be performed. See Deploy Settings for more information on how to configure the deployment of your applications.

Example¶

A simple example of a .doco-cd.yml file that deploys a Docker Compose application:

name: my-app
working_dir: my-app/
compose_files: 
  - docker-compose.yml

More information¶

Using encrypted secrets¶

Doco-CD supports the encryption of sensitive data in your Git repository files with SOPS.

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

Fetch secrets from external secret providers¶

Doco-CD supports fetching secrets from various external secret management providers like OpenBao, AWS Secrets Manager, Bitwarden, and many more. See the External Secrets wiki page for more information on how to use external secret management providers with Doco-CD.

Pulling images from a private registry¶

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

Sending Notifications¶

Doco-CD supports sending notifications about deployment events to various services. See the Notifications wiki page for more information on how to set up notifications.

Rest API¶

Doco-CD provides a REST API that allows you to interact with the application programmatically. See the Rest API wiki page.

Prometheus Metrics¶

Doco-CD exposes Prometheus metrics that can be used to monitor the application. See the Prometheus Metrics wiki page.