Getting Started¶

If you are new to Doco-CD, follow the pages in this order:

Set up Git authentication with either a token or an SSH key.
Choose how Doco-CD should detect changes: webhooks, polling, or both.
Deploy a repository using the sample docker-compose.yml file below.

Use this docker-compose.yml as your starting point

docker-compose.yml

## 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.y(a)ml
#      # Repository-based deployments require .doco-cd.y(a)ml (or .doco-cd.<target>.y(a)ml when target is set).

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:

Tip

To use a specific version, replace the latest tag with the desired release version without the leading v (e.g. 0.109.2): ghcr.io/kimdre/doco-cd:0.109.2

You can find the available tags/versions on the GitHub Container Registry.

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¶

Use a Git access token if your repository URL starts with http:// or https://. It lets doco-cd authenticate with your Git provider (GitHub, GitLab, Gitea, etc.) and clone or fetch repositories over HTTP.

Note

If you use an SSH URL for your Git repositories, the Git access token is not required. Instead, you need to generate an SSH key pair, see Setup SSH Key for more information.

Tip

You can use doco-cd without a Git Access Token if the repositories you want to use for your deployments are publicly accessible. However, it is still recommended to use one in that case to for example avoid rate limits.

Set GIT_ACCESS_TOKEN for a global fallback token, or use GIT_AUTH_DOMAINS / GIT_AUTH_DOMAINS_FILE for per-domain credentials. See Setup Access Token for examples.

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 a repository. They are the recommended trigger method because they are fast and efficient, but doco-cd must be reachable from your Git provider (for external services like GitHub this means from the internet) and you need to configure a webhook on the provider side.

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 repositories for changes at regular intervals. It does not require doco-cd to be reachable from the Git provider, which makes it useful for private networks, but it is 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.

Restricting Docker access¶

Mounting the Docker socket grants doco-cd full control over the Docker host. If you prefer to restrict this, see Docker API Permissions for the endpoints doco-cd uses and an example Docker socket proxy setup.

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:

docker-compose.yml

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:

.doco-cd.yml

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 Container Registry Authentication in the wiki.

Self-updating doco-cd¶

If you want doco-cd to update itself, see Self-Updating for a recommended two-instance setup.

Job Scheduling / Cron Jobs¶

Doco-CD supports job scheduling and cron jobs for running periodic tasks. See the Job Scheduling wiki page for more information on how to configure and use this feature.

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.