Docker tutorial: Get started with Docker Hub

The power of Docker images is that they’re lightweight and portable—they can be moved freely between systems. You can easily create a set of standard images, store them in a repository on your network, and share them throughout your organization. Or you could turn to Docker Inc., which has created various mechanisms for sharing Docker container images in public and private.

The most prominent among these is Docker Hub, the company’s public exchange for container images. Many open source projects provide official versions of their Docker images there, making it a convenient starting point for creating new containers by building on existing ones, or just obtaining stock versions of containers to spin up a project quickly. And you get one private Docker Hub repository of your own for free. 

Explore Docker Hub

The easiest way to explore Docker Hub is simply to browse it on the web. From the web interface, you can search for publicly available containers by name, tag, or description. From there, everything you need to download, run, and otherwise work with container images from Docker Hub comes included in the open source version of Docker—chiefly, the docker pull and docker push commands.

Docker Hub pricing

There is no charge for obtaining containers from Docker Hub. What’s more, if you want to host containers on Docker Hub and you have modest needs, you may not have to pay for that either. The free plan, which supports one private repository and one parallel build (more on that later), is typically enough for an individual developer. Pricing for other plans (more private repositories, more parallel builds) range from $7 to $100 per month.

Also, no matter what tier you’re using, Docker does not impose a hard limit for image sizes or pull requests. That said, anything larger than several gigabytes will become impractical to deal with—both for you to maintain and for others to pull for their projects.

Docker Hub organizations for teams

If you’re using Docker Hub with others, you can create an organization, which allows a group of people to share specific image repositories. Organizations can be further subdivided into teams, each with their own sets of repository privileges. Owners of an organization can create new teams and repositories, and assign repository read, write, and admin privileges to fellow users. 

Note that Docker Hub requires organization names be more than three characters in length. In other words, you can’t have an organization named “dev.” This is apparently an architectural limitation that Docker cannot work around. 

Docker Hub repositories

Docker Hub repositories can be public or private. Public repos can be searched and accessed by anyone, even those without a Docker Hub account. Private repos are available only to users you specifically grant access to, and they are not publicly searchable. Note that you can turn a private repo public and vice versa.

Note also that if you make a private repo public, you’ll need to ensure that the exposed code is licensed for use by all and sundry. Docker Hub does not offer any way to perform automatic license analysis on uploaded images; that’s all on you.

While it is often easiest to search a repository using the web interface, the Docker command line or shell also allows you to search for images. Use docker search to run a search, which returns the names and descriptions of matching images.

Certain repositories are tagged as official repositories. These provide curated Docker images intended to be the default, go-to versions of a container for a particular project or application (e.g. Nginx, Ubuntu, MySQL). Docker takes additional steps to verify the provenance and security of official images.

If you yourself maintain a project that you want to have tagged as an official repository on Docker Hub, make a pull request to get the process started. Note, however, that it is up to Docker to determine whether your project is worthy of being included.

Docker push and Docker pull

Before you can push and pull container images to and from the Docker Hub, you must connect to the Docker Hub with the docker login command, where you’ll submit your Docker Hub username and password. By default docker login takes you to Docker Hub, but you can use it to connect to any compatible repository, including privately hosted ones.

Generally, working with Docker Hub from the command line is fairly straightfoward. Use docker search as described above to find images, docker pull to pull an image by name, and docker push to store an image by name. A docker pull pulls images from Docker Hub by default, unless you specify a path to a different registry. 

Note that when you push an image, it’s a good idea to tag it beforehand. Tags are optional, but they help you and your team disambiguate image versions, features, and other characteristics. A common way to do this is to automate tagging as part of your image build process—for instance, by adding version or branch information as tags to images.

Automated builds on Docker Hub

Container images hosted on Docker Hub can be built automatically from their components hosted in a repository. With automated builds, any changes to the code in the repo are automatically reflected in the container; you don’t have to manually push a newly built image to Docker Hub.

Automated builds work by linking an image to a build context, i.e. a repo containing a Dockerfile that is hosted on a service like GitHub or Bitbucket. Although Docker Hub limits you to one build every five minutes, and there’s no support yet for Git large files or Windows containers, automated builds are nevertheless useful for projects updated daily or even hourly.

If you have a paid Docker Hub account, you can take advantage of parallel builds. An account eligible for five parallel builds can build containers from up to five different repositories at once. Note that each individual repository is allowed only one container build at a time; the parallelism is across repos rather than across images in a repo.

Another convenience mechanism for developers in Docker Hub is webhooks. Whenever a certain event takes place involving a repository—an image is rebuilt, or a new tag is added—Docker Hub can send a POST request to a given endpoint. You could use webhooks to automatically deploy or test an image whenever it is rebuilt, or to deploy the image only if it passes the test.