Tagging and Versioning: Mastering Docker Image Releases

Previously in this course, we discussed Understanding Image Layers: Docker Caching and File Systems and Optimizing the Build Cache: A Guide to Faster Docker Builds to make our build processes efficient. Now that you can build images reliably, it’s time to learn how to manage them as they evolve.

In professional environments, "it works on my machine" isn't a deployment strategy. To manage software releases effectively, you need a system to track exactly which version of your code is running inside a container. That system is tagging and versioning.

The Concept of Image Tagging

When you run docker build, you create an image. By default, that image has no name or tag—it's just a hash ID. As we covered in Building Your First Image: Mastering the Docker Build Command, assigning a tag is essential for identifying and referencing your work.

A Docker tag is essentially a label or pointer to a specific image ID. Think of it like a Git branch or a release tag; the image content doesn't change, but the label allows you to track "what" version you are currently working with.

Semantic Versioning (SemVer)

In DevOps, we use Semantic Versioning (MAJOR.MINOR.PATCH) to communicate the nature of changes in our releases:

• MAJOR: Breaking changes (e.g., changing the API).
• MINOR: New features that are backward compatible.
• PATCH: Backward-compatible bug fixes.

By tagging your images with these numbers (e.g., myapp:1.0.2), you gain the ability to roll back to a specific known-good state if a new release introduces a bug.

Understanding the 'latest' Tag

If you don't provide a tag, Docker automatically assigns the tag latest. Many beginners assume latest automatically tracks the absolute newest version, but it’s actually just a mutable label.

It is simply a tag that points to whatever image was most recently built or pulled without an explicit version. Relying on latest in production is a dangerous anti-pattern because it makes it impossible to know exactly which version of your code is running, leading to unpredictable behavior during deployments.

Worked Example: Tagging and Versioning

Let’s take our running project and apply versioning to it. Suppose we are building our web application image.

1. Build with a specific version:

   Bash
   docker build -t my-web-app:1.0.0 .
   

2. Add a secondary tag: If you want to keep the current version as 1.0.0 but also want to mark it as the current stable release, you can use docker tag:

   Bash
   docker tag my-web-app:1.0.0 my-web-app:stable
   

3. Verify the tags: Run docker images to see your work:

   Bash
   REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
   my-web-app    1.0.0     a1b2c3d4e5f6   1 minute ago   150MB
   my-web-app    stable    a1b2c3d4e5f6   1 minute ago   150MB
   

   Notice that both tags share the same IMAGE ID. They are aliases for the same underlying build.

Hands-on Exercise

1. Build your current project image and tag it as 0.1.0.
2. Use docker tag to create a new tag for the same image called v1-beta.
3. List your images and confirm that both tags point to the same Image ID.
4. Attempt to run a container using the v1-beta tag.

Common Pitfalls

• Overwriting 'latest': If you build a new version and tag it latest without thinking, you might overwrite a stable production image. Always use explicit version numbers.
• Assuming 'latest' is smart: latest is not a "rolling" tag that automatically updates; it is just a label. If you pull my-app:latest today, you get the version that was tagged as latest at the moment of the build. It won't magically refresh when a new version is released.
• Ignoring the Registry: Remember that tags are local unless you push them to a registry. We will cover this in detail in the next lesson.

FAQ

Q: Can I change a tag after I've pushed an image? A: No. Tags are immutable once pushed to most registries (like Docker Hub). You should always build a new image with a new version number.

Q: Should I use git commit hashes as tags? A: Yes, this is a common best practice in CI/CD pipelines (e.g., my-app:git-a1b2c3d). It allows you to trace a running container back to the exact line of code in your repository.

Recap

Tagging is your primary mechanism for release management. By moving away from the default latest tag and adopting semantic versioning, you ensure that your deployments are repeatable, traceable, and stable. Always treat image tags as snapshots of your application at a specific point in time.

Up next: Pushing to Docker Hub.