Skip to content

Docker image tagging and pushing workflow

The Docker image tagging and pushing workflow refers to the standard procedure for assigning identification tags to built Docker images and distributing them to a Docker Registry, such as the public Docker Hub or a private registry server.

Core Concepts

Image Tagging

Tagging an image effectively creates a reference alias to the image's specific ID (IMAGE ID). A common use case is preparing a locally built image for distribution by re-tagging it with the target registry's address^[600-developer__docker__Dockerfile__Dockerfile-01.md]. For example, an image named mytomcat can be tagged for a private repository hosted on localhost:5000 or a user's namespace on Docker Hub^[600-developer__docker__Dockerfile__Dockerfile-01.md].

Tagging does not duplicate the underlying layers of the image; therefore, multiple tags (e.g., mytomcat:latest and 127.0.0.1:5000/mytomcat:latest) will point to the same IMAGE ID and occupy the same disk space^[600-developer__docker__Dockerfile__Dockerfile-01.md].

Private Registry

While Docker Hub is the default public registry, a Docker Registry server can be deployed locally or within a private network to host images^[600-developer__docker__Dockerfile__Dockerfile-01.md]. This setup requires running the registry service (typically registry:2) and mapping a host volume to persist image data^[600-developer__docker__Dockerfile__Dockerfile-01.md].

Workflow Steps

The following steps outline the process of building, tagging, and pushing an image to a registry.

1. Build the Image

Create the image from a Dockerfile using the docker build command^[600-developer__docker__Dockerfile__Dockerfile-01.md].

docker build -t mytomcat .

2. Tag for Registry

Before pushing, the image must be tagged with the registry's location^[600-developer__docker__Dockerfile__Dockerfile-01.md].

  • For Docker Hub: Format is username/repository:tag.
  • For Private Registry: Format is registry-host:port/repository:tag.
# Example for local registry
docker tag mytomcat 127.0.0.1:5000/mytomcat

3. Push the Image

Upload the tagged image to the registry^[600-developer__docker__Dockerfile__Dockerfile-01.md].

docker push 127.0.0.1:5000/mytomcat

4. Verify and Pull

To verify the workflow, one can list the images to confirm the new tag exists, and then pull the image from the registry on a different machine or after removing the local image^[600-developer__docker__Dockerfile__Dockerfile-01.md].

  • Verify: docker images
  • Pull: docker pull 127.0.0.1:5000/mytomcat

Verification Commands

You can interact with the private registry API to check the contents of the repository^[600-developer__docker__Dockerfile__Dockerfile-01.md].

  • List Repositories: 
    curl -X GET http://127.0.0.1:5000/v2/_catalog
  • List Tags: 
    curl -X GET http://127.0.0.1:5000/v2/mytomcat/tags/list

Sources

^[600-developer__docker__Dockerfile__Dockerfile-01.md]