If you build container images for a living, or you are learning to, there is one habit that quietly separates calm engineers from stressed ones: keeping a clear version history of your container images. In plain terms, that means every image you ship gets a meaningful label, a date and a short note about what changed, and nothing you might need to return to is ever overwritten. This explainer walks through it for people who are new to the idea, in friendly language and without jargon dumps.
Start with the problem
Imagine you have a web application packaged as an image. It runs well for weeks. One afternoon you rebuild it with a small fix, push it to the same name as before, and by evening the site misbehaves. You reach for the old image to put things back, and it is gone, because the new build took over the name. Now you are rebuilding from memory and hoping you get the same result.
This happens constantly, and it is entirely avoidable. Nobody is being careless here; the default way of naming images invites overwriting.
What an image tag really is
An image has a name and a tag, written together like “app:1.4”. The tag is just a label that points at a specific build. The trap is a tag such as “latest”, which is a moving label: whatever you built most recently gets it, and the previous holder loses it. Using “latest” as your only label is like saving every document as “final” and overwriting the last one.
A tag that never moves, such as a version number or a build date, behaves differently. It points at one specific build forever, so you can always return to it. That is the core of version history for images.
A simple labelling scheme
You do not need anything elaborate. Pick a scheme and stick to it:
- A version number that increases with each release, such as 1.4.0, 1.4.1 and so on.
- A date stamp for builds you want to sort easily, written year-month-day.
- A short note stored with your release record, saying what changed and why.
Some teams add the identifier of the source change that produced the image, so any running container can be traced back to the exact code. That is a nice extra once the basics are in place.
The one-line note
Labels tell you which build is which. They do not tell you why it exists. For that, write a single sentence for each release: “reduced the image size by removing build tools from the final stage; startup is quicker”. When something misbehaves later, the sentence tells you what to suspect. It costs thirty seconds and spares you an hour of guesswork. If you want to see how clean builds are structured in the first place, the walkthrough on how engineering teams manage container images well covers the groundwork.
Comparing two versions
When you suspect a new image is the cause of a problem, run the previous one and the new one side by side with the same settings. Differences in behaviour point to differences in the build. You can also compare what each image contains, such as the base layer, installed packages and configuration files. The note you wrote tells you which differences were intended; anything else is a candidate for the cause.
Rolling back in a calm way
Because earlier versions still exist under their own fixed tags, rolling back means pointing your deployment at the previous tag. That is a small change you can make in a minute. Record it as its own entry: “returned to 1.4.0 while we investigate slow responses in 1.4.1”. Nothing is erased, and the next engineer sees the whole story.
Differences between development and production
Development can be a little looser, with throwaway tags, but production should never rely on moving labels. A deployment that says “run latest” cannot be reproduced next week, because “latest” will mean something else. Our guide on sensible Docker habits across development and production setups goes further into where the two environments should differ.
What goes wrong without the habit
Teams that skip all this tend to meet the same three surprises. First, a hotfix is built on a developer’s laptop with slightly different dependencies, and nobody can reproduce the image later. Second, two environments run “the same” image that turn out to be different builds under one moving label, so a bug appears in one place and not the other. Third, an audit or customer question arrives, asking what exactly was running on a given date, and the honest answer is a shrug.
Fixed tags and a short release note defuse all three. The hotfix gets its own number, the environments name the exact build they run, and the question about a particular date can be answered from your records in a couple of minutes.
Cleaning up without losing history
Registries fill up, so you will want to remove old images eventually. Do it deliberately: keep every version that was deployed to production, every version that introduced a significant change, and the last few builds of anything in active development. Delete the rest on a schedule, but keep the release notes forever, since text takes almost no room and the reasons outlive the images.
A career angle
This habit also shows well in a portfolio or interview. Being able to describe how you version, label and roll back an image tells a hiring manager you think about operations, not just building. A short public write-up of your own scheme, with a few real examples from a practice project, is a modest but convincing piece of personal branding.
Reusable text deserves labels too
The same idea applies to text you reuse. Some engineers keep reusable prompt instructions for documentation and review tasks on Promptosia, an online library for reusable prompt instructions with revision tracking and public pages. It is the same philosophy of labels and notes, pointed at wording.
A starter routine
- Stop using a moving label as your only tag.
- Adopt version numbers and add a date where helpful.
- Write one sentence per release.
- Keep every production version until you are sure you will never need it.
- Practise a rollback on a test project, so the real one is boring.
Once these steps become routine, you will find releases less nerve-racking. The history does not prevent mistakes; it simply makes every mistake small, visible and easy to undo, which is as good a definition of professional calm as I know.
