Docker Minimus Migration to Hardened Images

If your systems run images from Minimus, start your Docker Minimus migration now rather than waiting until the deadline approaches. Docker says the Minimus registry is expected to shut down on October 22, 2026; after that date, images that have already been pulled may continue to run, but they will no longer receive updates, leaving newly discovered vulnerabilities unpatched (according to Docker).

The least disruptive option is to move to the corresponding Docker Hardened Images (DHI) and then revalidate access permissions, the container runtime user, service ports, the entrypoint, CI/CD pipelines, and vulnerability scan results. For many applications, the initial change may be limited to the FROM, but this should not be treated as a blind replacement.

Why should Minimus registry end of life be addressed early?

A registry ceasing to provide images does not mean that running containers will stop immediately. The greater risk is disruption to release and security processes: new servers may be unable to pull images, pipelines may fail to build releases, and older images will continue accumulating CVEs over time.

During the transition period, Minimus will continue to receive updates, according to Docker’s announcement, until October 22, 2026. This provides a suitable window to inventory, test, and deploy services in stages rather than changing the entire system at once.

Docker describes Docker Hardened Images as minimal, hardened images that are maintained continuously. The DHI catalog includes Alpine and Debian bases, along with variants intended for build and runtime stages. DHI Community provides an open-source image catalog under the Apache 2.0 license; paid packages add CVE remediation SLAs, FIPS/STIG variants, customization, and extended lifecycle support (according to Docker Documentation).

Do not assume that a DHI is an exact copy of a Minimus image. Tag names, registry paths, entrypoints, default users, and available tools may differ. The plan’s objective is to preserve application behavior while improving provenance verification and vulnerability-remediation processes.

Inventory Docker images before migration

The first step in container image migration is to create a complete inventory, including images referenced indirectly in Dockerfiles, Docker Compose files, Helm charts, Kubernetes manifests, CI/CD pipelines, and deployment scripts.

Information to collect

The image name, registry, repository, and tag or digest currently in use.
The services using the image: production, staging, development, or internal tools.
The base platform: Alpine, Debian, Ubuntu, Wolfi, or a custom image.
Architectures that must be supported: linux/amd64, linux/arm64 , or multiple architectures.
The commands RUN, apt, apk, bash, curl and debugging tools that depend on the image.
The current user, group, listening ports, volumes, environment variables, and entrypoint.
The service owner, criticality, maintenance window, and rollback plan.

You can start by searching the source code for image references:

grep -RInE '(^|[[:space:]])(FROM|image:)[[:space:]]' 
  Dockerfile* docker-compose*.yml .github/ helm/ k8s/ 2>/dev/null

Next, use Docker to record the configuration of the running image:

docker ps --format '{{.Image}} {{.Names}}'
docker image ls
docker image inspect <image:tag>

Record the inventory in a tracking table with columns for the Minimus image, expected DHI image, tag/digest, service, owner, test status, deployment date, and rollback plan. This is the most important step for avoiding omissions such as workers, cron jobs, or images invoked only by an infrequently run pipeline.

If your systems run on dedicated servers or VPSs, also record how registry access is permitted through the firewall, proxy, and secrets. See the VPS selection guide if your deployment environment depends on self-managed servers.

Process for migrating to Docker Hardened Images

1. Choose a DHI from the same ecosystem

Prefer a DHI based on the same operating-system family as the current image. If the Minimus image is based on Alpine, choose the Alpine variant; if it is based on Debian, choose the Debian variant. This reduces the risk of differences in libraries, package managers, and runtime behavior.

docker login dhi.io
docker pull dhi.io/<repository>:<tag>

The specific repository name and tag must be looked up in the DHI catalog; do not infer them from the Minimus image name. For images that require dependency installation, choose the variant tagged dev or sdk for the build stage; runtime images typically do not include a package manager or shell (according to the DHI Migration Checklist).

2. Update the Dockerfile for a build-and-runtime model

A simple example in which the current image can be replaced directly:

# Trước
FROM minimus/base-image:1.2

# Sau, cần thay bằng repository/tag DHI đã xác minh
FROM dhi.io/<dhi-image>:<tag>

For applications that require compilation or package installation, use a multi-stage build:

FROM dhi.io/<runtime>:dev AS build
WORKDIR /src
COPY . .
RUN <lệnh cài dependency và build>

FROM dhi.io/<runtime>:latest
WORKDIR /app
COPY --from=build /src/<artifact> /app/<artifact>
USER 65532
EXPOSE 8080
ENTRYPOINT ["/&app/<artifact>"]

DHI runtime images run as non-root by default with UID 65532. Therefore, any directories that must be writable should be created and assigned the appropriate permissions during the build stage or when the volume is initialized. Applications should also avoid listening on privileged ports below 1024; switch to a port of 1025 or higher, such as 8080.

DHI images include standard TLS certificates, so many Dockerfiles no longer need to install ca-certificates. However, enterprise-internal certificates must still be added through a separate process. Runtime images may also not contain a shell, so inspection or modification commands using /bin/sh should be moved to the build stage or run from outside the container (see Docker Documentation).

Testing, Deployment, and Safe Rollback

A migration should not be judged solely by whether the image pulls successfully. A new image meets requirements when the application starts correctly, handles requests, produces logs normally, connects to its dependencies, and satisfies the defined security controls.

Minimum Test Suite

Build test: Build the image from scratch in a clean environment without using cached layers from the Minimus image.
Runtime test: Run the container with the default user, volumes, environment variables, and resource limits used in production.
Functional test: Call the health check, primary API, background jobs, database connection, and queueing system.
Security test: Scan the image with the tools currently in use and verify its software bill of materials (SBOM), signature, provenance, and digest.
Deployment test: Test the pipeline, registry mirror, secrets, and pull permissions on Kubernetes or the target host.
Rollback test: Retain the tested Minimus image digest during the transition, but do not treat it as a long-term security solution.

Roll out in small groups: the development environment, staging, a low-risk service, and only then critical production workloads. Monitor error rates, startup time, CPU and RAM usage, logs, and alerts for at least one release cycle before expanding the rollout.

If you use Kubernetes, create or update the image pull secret for the DHI registry. Docker notes that authentication is required when pulling images from dhi.io, a Docker Hub mirror, or a third-party registry (see Use a Docker Hardened Image).

For software supply-chain security, this migration should be tied to policies that allow images only by digest, require scanning before release, and restrict access to approved registries. See also the supply-chain protection article for controls that extend from the image to the host.

Common Errors

Build fails because the shell or package manager is missing: Move installation commands to the dev/sdk image and use a multi-stage build.
The application cannot write files: Check directory permissions for UID 65532, volumes, and temporary directories.
The container starts and then exits: Compare the ENTRYPOINT, CMD and environment variables with those of the old image.
The health check fails because the port has changed: Check whether the application is bound to port 1025 or higher and whether the manifest points to the correct port.
The pipeline cannot pull the image: Update the secret, registry permissions, firewall allowlist, and credential helper.
The scanner reports different results: Determine how the scanner interprets CVEs, the SBOM, and VEX; do not compare results solely by a single aggregate number.

The completion checklist includes: all Minimus references have been catalogued; each image has a replacement DHI image; the Dockerfile builds successfully; functional tests pass; non-root permissions have been verified; registry credentials work; the digest has been recorded; the rollback plan has been approved; and no production pipeline will depend on Minimus after October 22, 2026.

Conclusion: The Minimus registry end of life is an infrastructure change that should be handled as a supply-chain governance project, not merely as a one-line Dockerfile edit. Inventory Docker images during the first week, test a low-risk service the following week, and then expand by digest after testing. DHI can reduce technical changes by preserving Alpine and Debian foundations, but non-root policies, minimal runtimes, and registry authentication still require deliberate validation.

Docker Minimus Migration: Move to Docker Hardened Images