Skip to content

Tips and Tricks

Some Tips and Tricks for using application.

Using include with remote compose files

Docker Compose's include directive lets you pull in compose files from remote Git repositories or OCI artifacts directly:

docker-compose.yml
include:
  - https://github.com/example/app.git#v1.0.0:docker/docker-compose.yml

Compose file reference

See the full include syntax documentation in the Docker Compose documentation.

Resolving .env and other relative paths

When a remote compose file references relative paths, most commonly env_file: .env in a service definition, Docker Compose resolves those paths against the remote include's own directory inside doco-cd's internal cache, not against your deployment repository.

This means a deployment like the following will fail with "env file … not found" even if .env exists in your repository:

docker-compose.yml
include:
  - https://github.com/immich-app/immich.git#v3.0.3:docker/docker-compose.yml

env file /var/lib/.../compose-git-cache/.../docker/.env not found

Fix: use the long include form and set project_directory: .. This tells Docker Compose to resolve relative paths in the included file against your deployment working directory:

docker-compose.yml
include:
  - path: https://github.com/immich-app/immich.git#v3.0.3:docker/docker-compose.yml
    project_directory: .  # resolve .env and other relative paths from your repo root

With project_directory: ., any .env file you place in your repository root (or the directory configured as working_dir in .doco-cd.yml) will be picked up correctly by the included compose file.

Removing a container service

You can add the scale: 0 option in the docker-compose.yml file to remove a service (container). The scale option sets the number of containers to run for the service. Setting it to 0 will scale the service down to zero containers.

docker-compose.yml
services:
  webserver:
    scale: 0
    image: nginx

Add the following line to the deploy section of the service in the docker-compose.yml file to remove a service (container) in Docker Swarm mode:

docker-compose.yml
services:
  webserver:
    deploy:
      replicas: 0
    image: nginx

Note

If you scale down all services in a Docker project or Swarm stack, the entire project will be stopped, but the volumes, configs, secrets, and networks will still exist.

Tip

To delete volumes, networks, and images, you can use destroy: true for the default destructive cleanup behavior, or the full destroy object for custom removal options (See Destroy settings).

Using a plain Git server (no forge)

Doco-CD does not need a Git hosting platform (forge) like GitHub, GitLab or Forgejo. It only needs a clone URL it can reach, so it also works with bare Git repositories served by a plain Git server, e.g. via SSH, smart HTTP (git http-backend), native Git (git daemon), or the local filesystem.

Plain Git servers do not send webhook payloads, so use polling or use a post-receive hook to trigger deployments after a push via the REST API for webhook-like behavior.

Polling via SSH

Add the public key of doco-cd to the authorized_keys of the user on the Git server (see Setup SSH Key) and point a poll job at the SSH URL of the repository:

docker-compose.yml
services:
  app:
    environment:
      SSH_PRIVATE_KEY_FILE: /run/secrets/git_key
      POLL_CONFIG: |
        - url: ssh://me@myserver.org/home/me/myrepo.git
          reference: main
          interval: 5m

Use the ssh:// URL format

SCP-like URLs (user@host:path) are only recognized as SSH URLs when they start with git@. For any other user, use the ssh://user@host/path format (e.g. ssh://me@myserver.org/home/me/myrepo.git).

For repositories served via HTTP(S), set GIT_ACCESS_TOKEN to the password and GIT_ACCESS_TOKEN_USER to the username required by your server.

Polling via native Git

For a repository served by git daemon, configure an anonymous clone URL:

poll-config.yaml
- url: git://git.internal/myrepo.git
  reference: main
  interval: 5m

The default port is 9418. For a custom port, use git://git.internal:19418/myrepo.git. The daemon must export the repository and be reachable from doco-cd. No access token or SSH key is needed. Doco-CD does not send configured Git credentials over native Git.

Prefer HTTPS or SSH

Native Git has no encryption or authentication. An attacker on the network can replace deployment content. Use it only when you accept this risk; a private network alone does not protect the transport. HTTP proxy and TLS verification settings do not apply. See Supported transports.

Deploy on push with a post-receive hook

To deploy immediately after a push instead of waiting for the next poll interval, let a post-receive hook in the bare repository trigger a poll run via the REST API. This requires API_SECRET to be set (see App Settings), otherwise the REST API is disabled.

hooks/post-receive
#!/bin/sh
curl -s -X POST "https://cd.example.com/v1/api/poll/run?wait=false" \
  -H 'x-api-key: your-api-key' \
  -H 'content-type: application/json' \
  -d '[{"url": "ssh://me@myserver.org/home/me/myrepo.git", "reference": "main"}]'

Make the hook executable with chmod +x hooks/post-receive.

Repository on the same host

If doco-cd runs on the same machine as the bare repository, you don't need SSH or a hook at all: bind-mount the repository into the container (read-only is fine) and use its path as the poll URL, e.g. url: /local-repos/myrepo.git. doco-cd watches local repositories for new commits and deploys right after a push. See Polling Local Filesystem Repositories.