Recovering a container deployment after a name conflict

A container image can build successfully while deployment fails during recreation. We encountered repeated container-name conflicts after an interrupted deployment. The recovery lesson was to identify the resource that blocked the next run and make cleanup specific to its owner.

Understand the conflicting resource

A leftover container may retain a name that the next deployment expects to use. Inspect the conflicting container's identity, Compose project and service labels, running state, mounts and relationship to the current release. A similar name alone does not establish that a container is safe to remove.

What orphan cleanup covers

Docker documents --remove-orphans as removing containers for services absent from the Compose file. It can help when the conflict is an orphan in that sense. It does not guarantee removal of every renamed or interrupted container, particularly one still associated with a defined service. Check the behavior of the deployed Compose version before relying on it.

Make recovery deliberate

1. Confirm which deployment owns the conflicting resource and whether it is serving traffic.
2. Preserve required data and establish the recovery path before cleanup.
3. Remove only the confirmed stale resource under the deployment procedure.
4. Retry the deployment and verify the running release and public health checks.
5. Exercise the interruption scenario in a test environment before automating the recovery.

A deployment should report clearly whether it installed the new release, restored the previous one or needs operator attention. A successful build does not answer that question.

Reference: Docker Compose up.