Change the base image, then replace every running container

01Does this apply to you?

02Steps

Treat the base image as the runtime. Find it, pin it, rebuild, replace, and verify the running digest rather than the declared tag.

1. Platform engineer

   Find the image that provides PHP

   Look for the FROM line that supplies PHP, not the line that copies application code. A multi-stage build can hide the runtime in an earlier stage; follow the final stage's base.

   Check whether the image is the official php image, a framework image built on it, or a vendor image with PHP baked in. The fix must come from a rebuilt base, not from a PHP package installed at container start.

   List every workload that uses the image: web, queue workers, cron jobs, one-off admin tasks and init containers. Some of them may run PHP even if they do not serve HTTP.

   You should see Every workload is mapped to the image that supplies its PHP runtime.

   If it fails If a workload builds PHP at startup, it is not reproducible and cannot be verified by digest. Record it as an exception and fix the build.
2. Platform engineer

   Resolve the patched tag to a digest

   The official PHP image feed lists 8.2.35, 8.3.36, 8.4.27 and 8.5.12. A tag existing does not prove a running container uses it, and tags can be moved.

   A tag can point to a manifest list (index) for several platforms, not to one image. docker buildx imagetools inspect shows the index digest and a digest for each platform manifest. Record both, and record the target architecture and variant.

   Pin the platform-specific manifest digest in the build input for the architecture you deploy. Keep the index digest as distribution metadata, not as a substitute for the platform digest.

   Resolve a tag to a digest (example) Copy

   docker buildx imagetools inspect php:8.4.27-fpm   # record index and per-platform manifest digests

   You should see A version, tag, index digest, target-platform manifest digest and architecture are recorded for the patched base image.

   If it fails If the registry cannot resolve the tag, check the image variant and architecture. Do not substitute a different variant just to get a digest, and do not call the index digest a platform image digest.
3. Platform engineer

   Rebuild the application image on the patched base

   Update the FROM reference to the patched digest and rebuild. Pin the digest in the build definition so a later tag move cannot silently change the runtime.

   Run the application's own build and test steps. A base image change can affect extensions, ICU data, OpenSSL or the default php.ini; these are common sources of production surprises.

   Record the previous image digest before overwriting it. If your registry deletes old tags, keep the digest or export the image.

   You should see A new application image built from the patched base, with the previous digest retained.

   If it fails If the build depends on an unpinned base or a floating latest, fix the build definition first. Otherwise the next deployment can undo this one.
4. Platform engineer

   Deploy and drain the old replicas

   Roll out the new image using your normal strategy. Make sure the orchestrator terminates old replicas rather than leaving them attached to the service.

   Check connection draining and grace periods. A PHP-FPM container can finish in-flight requests after the orchestrator starts the new replica; that is expected, but it must not keep taking new traffic indefinitely.

   For a single Docker host, stop and remove the old container and create a new one from the new image. docker restart reuses the existing container image and is not a runtime change.

   You should see Only the new image is receiving new traffic, and old replicas are terminating or gone.

   If it fails If old replicas remain, inspect the deployment's rollout status and the service selector. A manifest update that did not trigger a rollout is a common cause.
5. Platform engineer

   Confirm the running application image, at the right layer

   Three identifiers are involved, and they are not interchangeable. The base image digest is a build input. The rebuilt application image has its own local image ID and, after a push or pull, its own repository manifest digest. The running container records the image it was created from. A rebuilt app image is a different object from its base, so their hashes will not match.

   On current engines, docker inspect --format '{{.Image}}' <container> returns the image ID used at creation; newer API output also exposes .ImageID and, when available, .ImageManifestDescriptor for the platform-specific manifest. Compare that with the application image ID from docker image inspect --format '{{.Id}}' app:local. Compare image ID with image ID, not with a registry digest.

   If the application image was pulled or pushed, docker image inspect --format '{{index .RepoDigests 0}}' app:local gives a repository-level manifest digest such as registry.example/app@sha256:…. For a multi-platform app image, use the manifest digest for the platform the container runs on, and keep the index digest separately. A lengthened short ID is not a repository digest.

   This evidence proves which application artifact is deployed. It does not prove which PHP patch is inside it. Pair it with the build log, base manifest digest, package source and regression result.

   Compare the running container with the application image (example) Copy

   docker inspect --format '{{.Image}}' <container>
   docker image inspect --format '{{.Id}}' app:local
   docker image inspect --format '{{index .RepoDigests 0}}' app:local

   You should see The running image ID matches the expected application image ID; any repository digest and platform manifest are recorded at their own layer. Separate build evidence shows which PHP patch the application image contains.

   If it fails If .Image is a tag or a short ID, resolve it without treating it as a repository digest. On newer engines check .ImageID. Do not compare the base image digest with the application image ID and call a mismatch a failed rollout.
6. Application owner

   Run the business regression and keep the rollback

   Test the same critical paths as any other runtime change: authentication, the primary transaction, uploads, queues and scheduled work. A container that starts is not a container that works.

   Record the previous digest, the new digest and the rollback command in the change record. Rehearse the rollback if the service is critical.

   Remove unused old images only after the rollback window closes. Disk pressure is not a reason to delete the only rollback artefact.

   You should see A regression result, a rollback digest and a date when the old image can be retired.

   If it fails If the rollback fails in rehearsal, treat the deployment as unverified and fix the rollback before closing the change.

03What usually goes wrong

05Where to go next

06Sources and revision

Every operational claim on this page was checked against the documents below on 24 October 2026. This page was last substantively changed on 24 October 2026.

See the full revision log for what changed on this site.