# Dockerfile<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

== Description

The Dockerfile crawler looks recursively for all Dockerfile from a specific root directory.
Then, for each of them, it tries to update each Docker image tag found in a 'FROM' instruction.

Updatecli looks for the following file patterns:

* `Dockerfile`
* `Dockerfile.*`

Override them with the `filematch` parameter.

The automatic discovery behavior can be tuned by providing a YAML manifest with a `dockerfile` crawler in top-level directive `autodiscovery` as explained in the link:/docs/core/autodiscovery/#_parameters["Autodiscovery" page].

=== Usage

The dockerfile autodiscovery can use with or without manifest.

**Without manifest**

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

`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

[source,yaml]
----
# updatecli.d/default.yaml
{{<include "assets/code_example/docs/plugins/autodiscovery/dockerfile/updatecli.d/default.yaml">}}
----

== Generated manifests

Each image produces a link:{{< ref "docker_image" >}}[`dockerimage`] source for the latest tag and a link:{{< ref "dockerfile" >}}[`dockerfile`] target that rewrites the instruction in place. When digest pinning is enabled, a link:{{< ref "docker_digest" >}}[`dockerdigest`] source is added and the digest is written alongside the tag.

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

Three details of how `FROM` instructions are read:

* **Build arguments are followed.** For `ARG GOVERSION=1.21` used as `FROM golang:${GOVERSION}`, the target writes to the `ARG` instruction rather than the `FROM` line, so the default stays authoritative.
* **Stage aliases are skipped.** A `FROM builder AS final` referring to an earlier stage is not an external image and yields no manifest.
* **Flags are ignored.** `FROM --platform=linux/amd64 alpine:3.18` is handled normally.

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

{{< autodiscoveryparameters "dockerfile" >}}

=== 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 dockerfile 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 link:https://github.com/updatecli/updatecli/issues/new/choose[issue] explaining the version pattern you are looking for.
2. Add a `+1` to an existing link:https://github.com/updatecli/updatecli/issues[issue] as it helps us to prioritise
3. Contribute to an existing one as it will move things faster.