Docs

Docker Compose

Description

The Docker compose crawler looks recursively for all docker compose manifests from a specific root directory. Then, for each of them, it tries to update each Docker image tag found.

Updatecli looks for the following file patterns:

  • docker-compose*.y*ml

  • compose*.y*ml

Those cover docker-compose.yaml, docker-compose.override.yml, and the Compose Specification’s compose.yaml. Override them with the filematch parameter.

The automatic discovery behavior can be tuned by providing a YAML manifest with a dockercompose crawler in top-level directive autodiscovery as explained in the "Autodiscovery" page.

Usage

The dockercompose autodiscovery can be used with or without manifest.

Without manifest

Without manifest available, Updatecli will enable all default crawlers, including dockercompose.

updatecli diff to run updatecli in dryrun updatecli apply to apply the changes locally

With a manifest

If a manifest is provided, Updatecli will only execute crawlers specified in the manifest such as in the following example

  • updatecli diff --config updatecli.d/default.yaml to run updatecli in dryrun

  • updatecli apply --config updatecli.d/default.yaml to apply the changes

# updatecli.d/default.yaml
name: "Docker compose autodiscovery using git scm"
scms:
  updatemonitor:
    kind: git
    spec:
      url: https://github.com/updatecli/updatemonitor.git

autodiscovery:
  # scmid is applied to all crawlers
  scmid: updatemonitor
  crawlers:
    dockercompose:
      ignore:
       - path: 'docker-compose.yaml'
         services:
          -  traefik
      #only:
      #  # - path: <filepath relative to scm repository>
      #      services: <docker compoes service name to match>
      #      platform: <docker compose service platform to match>
      #      image: <docker compose image to match>

Generated manifests

Each service image produces a dockerimage source for the latest tag and a yaml target that rewrites the image reference in place. When digest pinning is enabled, a dockerdigest source is added and the digest is written alongside the tag.

digest defaults to true. Set digest: false to track the tag only.

Authentication

Use auths to reach private registries, keyed by registry URL without a scheme, accepting either a token or a username/password pair. When it is empty Updatecli falls back to the ambient OCI credentials, such as those written by docker login.

Manifest

Parameters

NameTypeDescriptionRequired
authsobject

“auths” defines the registry credentials, keyed by registry host without scheme.

remark:

  • when empty, Updatecli uses the local OCI credentials, such as the Docker ones.

example:

auths:
  "ghcr.io":
    token: "xxx"
  "index.docker.io":
    username: "admin"
    password: "password"
    passwordstring

“password” defines the container registry password used for authentication.

default: credentials are retrieved from the local environment, such as ~/.docker/config.json.

remark:

  • “password” requires “username”.
  • “token” cannot be combined with both “username” and “password”.
    tokenstring

“token” defines the container registry bearer token used for authentication.

default: credentials are retrieved from the local environment, such as ~/.docker/config.json.

remark:

  • “token” cannot be combined with both “username” and “password”.
    usernamestring

“username” defines the container registry username used for authentication.

default: credentials are retrieved from the local environment, such as ~/.docker/config.json.

remark:

  • “username” requires “password”.
  • “token” cannot be combined with both “username” and “password”.
digestboolean

“digest” defines whether the generated manifests pin the image digest in addition to the tag.

default: true

filematcharray

“filematch” defines the file name patterns used to identify Docker Compose files.

default:

filematch:
  - "docker-compose*.y*ml"
  - "compose*.y*ml"

remark:

  • the pattern is matched against the file name only, not against its path.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
ignorearray

“ignore” defines rules to exclude matching container images from the autodiscovery.

remark:

  • a container image is ignored when it matches at least one rule.
    archsarray

“archs” defines the image architectures to match.

remark:

  • an architecture must be identical to one of the entries.
  • the architecture is the middle part of the “platform” key of a service, so “linux/amd64” gives “amd64”. Entries must use that form, such as “amd64”.
  • a service without an architecture in its “platform” key is not checked against “archs”.

example:

  • archs: [“amd64”, “arm64”]
    imagesarray

“images” defines the container images to match.

remark:

  • an image matches when its name starts with one of the values.
    pathstring

“path” defines a Docker Compose file path pattern.

remark:

  • the pattern must match the whole path, not just a substring.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
    servicesarray

“services” defines the Docker Compose service names to match.

remark:

  • a service name must be identical to one of the entries.
onlyarray

“only” defines rules to restrict the autodiscovery to matching container images.

remark:

  • a container image is kept only when it matches at least one rule.
    archsarray

“archs” defines the image architectures to match.

remark:

  • an architecture must be identical to one of the entries.
  • the architecture is the middle part of the “platform” key of a service, so “linux/amd64” gives “amd64”. Entries must use that form, such as “amd64”.
  • a service without an architecture in its “platform” key is not checked against “archs”.

example:

  • archs: [“amd64”, “arm64”]
    imagesarray

“images” defines the container images to match.

remark:

  • an image matches when its name starts with one of the values.
    pathstring

“path” defines a Docker Compose file path pattern.

remark:

  • the pattern must match the whole path, not just a substring.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
    servicesarray

“services” defines the Docker Compose service names to match.

remark:

  • a service name must be identical to one of the entries.
rootdirstring

“rootdir” defines the directory where the crawler starts searching for Docker Compose files.

default: the scm directory when “scmid” is set, otherwise the directory relative paths resolve from, by default the working directory.

remark:

  • a relative path is resolved from the default directory.
  • an absolute path is used as is, instead of the scm directory.
versionfilterobject

“versionfilter” defines the version filter used by the generated manifests.

default: kind “semver” with pattern “>=”, combined with a tag filter derived from the current tag.

remark:

  • with kind “semver”, “pattern” accepts:
    • “prerelease”: the latest prerelease of the current version.
    • “patch”: patch updates only.
    • “minor”: patch and minor updates.
    • “minoronly”: minor updates only.
    • “major”: patch, minor and major updates.
    • “majoronly”: major updates only.
    • a version constraint, such as “>= 1.0.0”.
  • with kind “regex”, “pattern” accepts a regular expression.
  • more examples at https://www.updatecli.io/docs/core/versionfilter/

example:

versionfilter:
  kind: semver
  pattern: minor
    kindstring

“kind” defines the versioning scheme used to select a version.

default: latest

remark:

  • accepted values are “latest”, “semver”, “regex”, “regex/semver”, “time”, “regex/time”, “lex” and “pep440”.
  • “latest” returns the last version of the list.
  • “lex” sorts the versions lexicographically and returns the last one.
  • “pep440” follows https://peps.python.org/pep-0440/

example:

  • kind: semver
    patternstring

“pattern” defines the version pattern, according to “kind”.

default:

  • latest: “latest”
  • semver and pep440: “*”
  • regex: “.*”
  • time and regex/time: “2006-01-02”

remark:

  • for “latest”, “latest” returns the last version, any other value must match a version exactly.
  • for “semver” and “regex/semver”, it is a semantic versioning constraint.
  • for “pep440”, it is a pep440 version specifier.
  • for “regex”, it is a regular expression.
  • for “time” and “regex/time”, it is a Go date layout.
  • ignored by “lex”.

example:

  • pattern: ~1.2
  • pattern: “>=1.0.0 <2.0.0”
  • pattern: ^v\d+.\d+.\d+$
    regexstring

“regex” defines the regular expression extracting the version from each entry.

remark:

  • only used by the kinds “regex/semver” and “regex/time”.
  • the value of the first capture group is used as the version.

example:

  • regex: ^v(\d+.\d+.\d+)$
    replaceallobject

“replaceall” applies a regular expression replacement to each version before filtering.

remark:

  • only used by the kinds “regex”, “regex/semver” and “regex/time”.
  • the replacement runs before “pattern” or “regex” is evaluated.

example:

replaceall:
  pattern: "_"
  replacement: "."

turns “curl-8_15_0” into “curl-8.15.0”.

        patternstring

“pattern” defines the regular expression matching the text to replace.

example:

  • pattern: “_”
        replacementstring

“replacement” defines the text replacing each match of “pattern”.

remark:

  • capture groups can be referenced with $1, $2, and so on.

example:

  • replacement: “.”
    strictboolean

“strict” enforces strict semantic versioning rules when parsing versions.

default: false

remark:

  • only used by the kinds “semver” and “regex/semver”.
⚠ This table is generated from the Updatecli codebase and may contain inaccurate data. Feel free to report them on github.com/updatecli/updatecli
Note
The crawler key is dockercompose, without a hyphen.

Docker Image Tag

The Docker ecosystem has no versioning guidelines. This means that it’s the wild west out there and pretty much impossible to detect all cases. Hence why Updatecli manifest was created.

That being said we are still interested in an autodiscovery feature that would detect as many cases as possible. This section is about documentation what is covered and what’s missing. Do not hesitate to look at the contributing section

Semantic Versioning

In the Docker ecosystem, many tags look like semver but are not. For instance, node:18.12.1-alpine would match the semver regular expression but the prerelease -alpine is not a prerelease information as per semver convention but a variant of node:18.12.1-buster or node:18.12.1. This means that we would expect a newer version with the -alpine such as node:19.0.0-alpine.

The dockercompose autodiscovery will handle the following scenarios

  • 1 will suggest a version such 2 otherwise stick to 1

  • 1-alpine will suggest a version such 2-alpine otherwise stick to 1-alpine

  • 1.0 will suggest a version such 2.1 otherwise stick to 1.0

  • 1.0-alpine will suggest a version such 2.1-alpine otherwise stick to 1.0-alpine

  • 1.0.0 will suggest a version such 2.1.0 otherwise stick to 1.0.0

  • 1.0.0-alpine will suggest a version such 2.1.0-alpine otherwise stick to 1.0.0-alpine

Any other version pattern such as PEP 440 are ignored in the current state. We are planning to add new versionFilter kinds in the future as the need raise.

Feel free to:

  1. Open an issue explaining the version pattern you are looking for.

  2. Add a +1 to an existing issue as it helps us to prioritise

  3. Contribute to an existing one as it will move things faster.

Last updated on August 2, 2026
Prev
Cargo
Next
Dockerfile