diff --git a/docs/guides/administration/deploying-to-kubernetes.md b/docs/guides/administration/deploying-to-kubernetes.md index 6384948..822842b 100644 --- a/docs/guides/administration/deploying-to-kubernetes.md +++ b/docs/guides/administration/deploying-to-kubernetes.md @@ -9,7 +9,8 @@ platform, and you should read it alongside the chart documentation. The `dependency-track` chart is not yet compatible with v5. As a safety mechanism against silent misconfiguration, the chart fails during rendering when it detects a v5 image tag. A v5-compatible release is in progress and ships soon. Until then, you can either wait for the chart, or roll your - own manifests based on the v5 container images. + own manifests based on the v5 container images. See + [Container images](../../reference/container-images.md) for image coordinates and tag conventions. !!! warning "The `hyades` chart goes away soon" A separate `hyades` chart exists from the period when the project developed v5 under the Hyades diff --git a/docs/guides/administration/deploying-to-production.md b/docs/guides/administration/deploying-to-production.md index a3df012..edd3aa9 100644 --- a/docs/guides/administration/deploying-to-production.md +++ b/docs/guides/administration/deploying-to-production.md @@ -6,6 +6,13 @@ of how the components fit together, see [Scaling](scaling.md). For Kubernetes-specific guidance, see [Deploying to Kubernetes](deploying-to-kubernetes.md). +## Pin container image versions + +Pin every Dependency-Track container to a full `X.Y.Z` release tag (or an image +digest). Do not deploy snapshot tags or the `latest` tag to production. See +[Container images](../../reference/container-images.md) for the available +registries, image coordinates, and tag conventions. + ## Provision compute and database ### API server instances diff --git a/docs/guides/administration/migrating-from-v4.md b/docs/guides/administration/migrating-from-v4.md index 5df39c6..c75fbbd 100644 --- a/docs/guides/administration/migrating-from-v4.md +++ b/docs/guides/administration/migrating-from-v4.md @@ -110,6 +110,7 @@ Configure them on the target before running, and revert afterward if you like. ## Run the migration The migrator ships as a container image published at `ghcr.io/dependencytrack/v4-migrator:`. +See [Container images](../../reference/container-images.md) for registries and tag conventions. The examples below use the following shell alias for brevity: diff --git a/docs/guides/administration/upgrading-instances.md b/docs/guides/administration/upgrading-instances.md index 414952f..91b6125 100644 --- a/docs/guides/administration/upgrading-instances.md +++ b/docs/guides/administration/upgrading-instances.md @@ -21,6 +21,8 @@ If any of these conditions fail, plan a full-stop upgrade window instead. - Back up the database and verify the backup. See [Backing up](backing-up.md). - Read the release notes for every version between the running and target version. Stop and plan a full-stop upgrade if any release calls for one. +- Pick the new image tag. Pin a full `X.Y.Z` release tag rather than a snapshot or `latest`. See + [Container images](../../reference/container-images.md). - If you run schema migrations in a dedicated container (recommended for large deployments and PgBouncer in transaction mode), plan to run it before any new-version API server starts. See [init-only containers](../../reference/configuration/init-tasks.md#init-only-containers). diff --git a/docs/reference/.pages b/docs/reference/.pages index 2077766..0f73104 100644 --- a/docs/reference/.pages +++ b/docs/reference/.pages @@ -4,6 +4,7 @@ nav: - Projects: projects.md - API: api - Configuration: configuration + - Container images: container-images.md - Datasources: datasources - Notifications: notifications - Vulnerability analysis: diff --git a/docs/reference/container-images.md b/docs/reference/container-images.md new file mode 100644 index 0000000..be43057 --- /dev/null +++ b/docs/reference/container-images.md @@ -0,0 +1,65 @@ +# Container Images + +Dependency-Track ships as a set of container images. Each component has its own +image. Releases go to GitHub Container Registry first and then mirror to Docker +Hub asynchronously. + +## Components + +| Component | Description | +|:----------|:------------| +| API server | Backend service. Exposes the REST API and runs analysis. | +| Frontend | Web UI. Serves the static single-page app. | +| v4 migrator | One-shot tool for migrating a v4 database to v5. See [Migrating from v4](../guides/administration/migrating-from-v4.md). | + +Dependency-Track v4 published a "bundled" image combining API server and +frontend. v5 does not. Operators must run the two components as separate +containers. + +## Registries + +Two registries host the images: + +| Registry | Role | +|:---------|:-----| +| `ghcr.io` | Primary. Receives new tags first. | +| `docker.io` | Mirror. Updated asynchronously from `ghcr.io`. | + +A newly published tag appears on `ghcr.io` immediately and on `docker.io` once +the mirror job completes. If a tag is missing from Docker Hub shortly after a +release, pull it from `ghcr.io` or retry after the mirror catches up. + +## Image coordinates + +| Component | GHCR | Docker Hub | +|:----------|:-----|:-----------| +| API server | `ghcr.io/dependencytrack/apiserver` | `docker.io/dependencytrack/apiserver` | +| Frontend | `ghcr.io/dependencytrack/frontend` | `docker.io/dependencytrack/frontend` | +| v4 migrator | `ghcr.io/dependencytrack/v4-migrator` | `docker.io/dependencytrack/v4-migrator` | + +## Tags + +| Tag pattern | Example | Description | +|:------------|:--------|:------------------------------------------------------------| +| `X.Y.Z` | `5.0.0` | Stable release. | +| `X.Y.Z-rc.N` | `5.1.0-rc.1` | Release candidate. | +| `X-snapshot` | `5-snapshot` | Latest build from the `main` branch. Moves with each merge. | + +Always pin deployments to a full `X.Y.Z` tag, or to an image digest. This keeps +rollouts reproducible and avoids accidental upgrades. + +!!! warning + Do not use the `latest` tag. It points to the most recent v4 release and + keeps pointing there until v4 reaches end of life in December 2026. v5 + users that pull `latest` get a v4 image. + +## Immutability + +Release tags (`X.Y.Z`, `X.Y.Z-rc.N`) on Docker Hub are +[immutable](https://docs.docker.com/docker-hub/repos/manage/hub-images/immutable-tags/). +Once published, the digest a release tag points to cannot change. This +guarantees that a deployment pinned to `5.0.0` resolves to the same image +forever, regardless of mirror state or registry caches. + +Snapshot tags (`5-snapshot`) are mutable by design. They move with each new +build.