Image Tagging and Registry Push with Semantic Versioning

1. The Art of Tagging: Why and How

Before you can push an image, you need to give it a proper name and version. This is done through tagging.

A Docker tag is a label that points to a specific image version (identified by its unique digest or hash). You can have multiple tags pointing to the same image. While Docker defaults to the latest tag if you don't specify one, relying on it is a common anti-pattern in production environments because it's mutable and can lead to confusion about which version of the code is actually running.

Semantic Versioning (SemVer)

To bring order to versioning, the industry standard is Semantic Versioning (SemVer). It provides a clear, consistent framework for communicating the nature of changes between releases.

As the article explains, SemVer uses a MAJOR.MINOR.PATCH format:

• MAJOR version for incompatible API changes.
• MINOR version for adding functionality in a backward-compatible manner.
• PATCH version for backward-compatible bug fixes.

Using explicit tags like my-app:1.2.1 ensures that you are deploying a precise, immutable version of your application, which is critical for stable and predictable systems.

Applying Tags

There are two primary ways to tag an image:

1. During the build process using the -t flag:

   docker build -t your-app-name:1.0.0 .
   

2. After the build by tagging an existing image:

   # First, build the image (it gets the 'latest' tag by default if none is specified)
   docker build -t your-app-name .
   
   # Then, apply a specific tag to it
   docker tag your-app-name:latest your-app-name:1.0.0
   

   The docker tag command is also what you'll use to prepare an image for pushing to a registry, which we'll see next.

2. Pushing Images to Docker Hub

A container registry is a storage and distribution system for Docker images. Docker Hub is the default, public registry that the Docker client is configured to use.

To push an image to Docker Hub, you must tag it with a specific format:
<your-docker-hub-username>/<repository-name>:<tag>

Let's walk through the entire workflow: build, tag, login, and push.

To summarize the workflow shown in the video:

1. Build your image:
   docker build -t my-cool-app:1.0.0 .

2. Log in to Docker Hub:
   docker login
   You'll be prompted for your Docker Hub username and password.

3. Re-tag the image for the registry:
   docker tag my-cool-app:1.0.0 yourusername/my-cool-app:1.0.0
   Notice that both my-cool-app:1.0.0 and yourusername/my-cool-app:1.0.0 will now appear in your docker images list, but they point to the exact same image ID, taking up no extra disk space.

4. Push the image:
   docker push yourusername/my-cool-app:1.0.0

5. Verify (optional but recommended): You can now go to hub.docker.com and see your repository. You can also test it by removing the local images and pulling it from the hub:

   docker rmi my-cool-app:1.0.0 yourusername/my-cool-app:1.0.0
   docker pull yourusername/my-cool-app:1.0.0
   

3. A Professional Alternative: GitHub Container Registry (GHCR)

While Docker Hub is common, many organizations and open-source projects use the GitHub Container Registry (ghcr.io) because it integrates seamlessly with GitHub repositories and Actions. As a DevOps engineer, you'll almost certainly encounter this in the wild.

The process is very similar, with two key differences:

1. Authentication: You use a Personal Access Token (PAT) instead of your password. This is more secure and is standard practice for programmatic access.
2. Image Naming: The format is ghcr.io/<your-github-username>/<repository-name>:<tag>.

Using a PAT is a great habit to get into, as it aligns with the principle of least privilege and is essential for setting up the CI/CD pipelines you'll be building professionally. The latter part of that same video (which you don't need to watch now) even demonstrates how to automate this entire process with GitHub Actions, which directly connects to the future "Docker in a CI/CD Pipeline" module.

Conclusion

In this lesson, you've taken a critical step from building images to distributing them. You now have a framework for versioning your containerized applications and the practical skills to share them with the world via public registries.

Key Takeaways:

• Use Semantic Versioning (MAJOR.MINOR.PATCH) to tag your images. Avoid the latest tag for anything beyond local development.
• To push to a registry, an image must be tagged in the format <registry-url>/<username>/<repository>:<tag>.
• The standard workflow is docker login, docker tag, and docker push.
• For Docker Hub, the registry URL is implicit. The format is <username>/<repository>:<tag>.
• For GitHub Container Registry (GHCR), the format is ghcr.io/<username>/<repository>:<tag>, and authentication uses a Personal Access Token (PAT).

In our next lesson, we will address a common requirement in corporate settings: authenticating with, using, and running a private container registry for secure image distribution. This will build directly on the concepts you've learned today, applying them to a secure, internal context.