Use this example docker-compose.yml as your starting point.

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.

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

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.

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.

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 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 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.

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.

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
    ...

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.

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

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

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

If you want to pull images from a private registry, see Accessing private container registries in the wiki.

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.

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

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