Using Docker Push to Publish Images to Docker Hub

In previous articles, we explored building and running Docker containers locally using custom Dockerfiles. What we don't explore very often is one of the most useful features of Docker and arguably the feature that has led to Docker's success:

The ability to build a Docker image and upload that image to a Docker repository.

The reason I say this has led to Docker's success is because the ability to share container images on Docker Hub (Docker's public/private registry) is what allows users to quickly share and build upon preexisting images.

In today's article, we are going to use this feature while learning the docker push command and using it to upload our Docker container image to Docker Hub.

Before we can push an image to Docker Hub, we will first need an account on Docker Hub. The signup process is simple and available on the front page of Docker Hub.

Once we have an account, our next step will be to create a new repository for this article. This process is fairly self-explanatory, however the following screenshot shows the type of information we need to provide.

Once the repository is created, we can start creating our Docker image and upload that image to Docker Hub.

For this article, we will be creating an image named push-example. Typically, if we were building this image for local deployment, we would simply run the following docker build command.

$ docker build -t push-example .

The above command will create a new image tagged as push-example. In local deployments, we would simply just issue a docker run, specifying this image by its tag name.

While this works for local deployment, this naming convention doesn't work when creating a image for Docker Hub.

When pushing an image to Docker Hub, we must specify our Docker Hub username as part of the image name. For the example above, I will need to create the image with the tag name of madflojo/push-example.

The madflojo part of the name is my personal user name for Docker Hub. In order for my image to be uploaded to the push-example repository under my user, I must include this username in the image name with the format of (username/image_name).

The reason for this is because Docker Hub organizes repositories by user name. Any repository created under my account includes my username in the Docker image name. For example, in an earlier article, we created a redis-tls Docker container that was also made available on Docker Hub. If we wanted to use that same image, we would need to reference that image as madflojo/redis-tls.

This same approach is used when building images for an organization's repository. For example, Codeship has an alpine-docker repository underneath its organization account. If we wanted to use this image, we would reference this image as codeship/alpine-docker. Organization-account names replace the username in the Docker image tag name.

Now that we understand how to name our container, let's go ahead and build the container again with the appropriate tag name.

$ docker build -t madflojo/push-example .

Before we push and upload our container to Docker Hub, we will first need to log in to Docker Hub from our command-line interface. To do this, we will use the docker login command.

$ docker login
Username: madflojo
Password:
Login Succeeded

Once we have logged in, we can now push our container to Docker Hub.

With the most complicated steps already completed, our next step is fairly simple. All we need to do is issue the docker push command specifying our image tag name.

$ docker push madflojo/push-example
The push refers to a repository [docker.io/madflojo/push-example]
4393194860cb: Pushed
0011f6346dc8: Pushed
340dc52ed535: Pushed
72073bf3dbb2: Pushed
627a5019997b: Pushed
62924cac48de: Pushed
33f1a94ed7fc: Pushed
b27287a6dbce: Pushed
47c2386f248c: Pushed
2be95f0d8a0c: Pushed
2df9b8def18a: Pushed
latest: digest: sha256:f483e14a1c6b7a13bb7ec0ab1c69f4588da2c253e87652329e615d2f8c439abe size: 2606

With the above command complete, our image is now pushed and available on Docker Hub. To see it, we can simply navigate to our newly created repository.

!Sign up for a free Codeship Account

So far in this article, we've learned how to create a new image with our username included in the Docker image tag name. We also learned how to log in and push that image to Docker Hub.

While this is useful for those who use the Docker Hub registry service, the steps change a little when trying to push to an internally hosted Docker registry. Luckily, the process doesn't change very much.

Just like we had to specify our username when building an image for Docker Hub, we must first include that name in the tag name for the Docker image when we want to build an image for a non-Docker-Hub registry.

The below command shows building an image for a registry running at registry.example.com.

$ docker build -t registry.example.com/madflojo/push-example .

The name follows a similar format as to the above, with the difference being the inclusion of the Docker registry address.

The docker login command will change a bit as well. Rather than simply running docker login, we will need to specify the registry address to tell Docker which registry to sign in to.

$ docker login registry.example.com

After logging in, our docker push command changes as well, however not very much.

Earlier when we performed the docker build step, we specified a image name of registry.example.com/madflojo/push-example. When we execute the docker push command, we will need to specify this image name as well.

As docker push is executed, Docker will look at the image name specified to determine what registry to upload the image to. When we specify registry.example.com/madflojo/push-example, it knows that we are pushing a container named push-example to a user's repository (madflojo), at the registry of registry.example.com. We can see this when executing the docker push command.

$ docker push registry.example.com/madflojo/push-example
The push refers to a repository [registry.example.com/madflojo/push-example]

With the above, we now know how to not only push images to Docker Hub but also any other registry we may need to push to, whether that registry is public or private.