Add container images reference docs

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

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

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:<version>`.
+See [Container images](../../reference/container-images.md) for registries and tag conventions.
 
 The examples below use the following shell alias for brevity:
 

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

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:

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.