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.
Creating a Repository on 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.
Building a New Image
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.
Using your Docker Hub name when building an image
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.
Building images for organizations
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 .
Logging in to Docker Hub
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.
Pushing Our Container
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
Pushing to a Non-Docker-Hub Registry
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.
Specifying the registry address in the tag name
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.
Log in to a non-Docker-Hub registry
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.
Use the full tag name with push
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.
| Reference: | Using Docker Push to Publish Images to Docker Hub from our WCG partner Ben Cane at the Codeship Blog blog. |
