Docker Repositories, Registries, and Image Names: The Big Picture

The Docker Hub Experience: "Create As You Go"

Imagine you're an artist uploading paintings to an online gallery. On Docker Hub, each artist (user) has their own collection of artwork (repositories). You don't need to reserve space beforehand—just upload your artwork, and a new gallery section (repository) will be created automatically.

In Docker terms:

  • Username: You (the artist)
  • Repository: A collection of images (art gallery)
  • Tag: A specific version of an image (a different version of the same painting)

Example: 

docker tag my-app:latest mibtisam/my-app:v1
docker push mibtisam/my-app:v1
👉 Here, Docker Hub automatically creates the repository mibtisam/my-app on your first push. You don’t have to set up the repo manually.

The AWS ECR & Nexus Experience: "Pre-Reserved Spaces"

Now, think of AWS ECR and a Nexus Private Repository as a high-security art museum. In these places, before you can display your artwork, you must reserve a specific exhibition space. You can't just push paintings randomly—the museum must have a designated area for it.

In Docker terms:

  • ECR/Nexus Registry: The entire museum
  • Repository: A specific exhibition room for one type of artwork (e.g., "Modern Art")
  • Tag: A version of the artwork (e.g., "Modern Art - 2024 Edition")

Example (AWS ECR):

Create a repository first in AWS ECR (manual step): 

aws ecr create-repository --repository-name my-ecr-repo

Tag and Push the Image: 

docker tag my-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-ecr-repo:v1
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-ecr-repo:v1
👉 Unlike Docker Hub, you must create the repository manually in AWS ECR before pushing an image.

Example (Nexus Private Repo - IP: 154.65.3.12:5000)

If your organization uses a private registry like Nexus, it works exactly like ECR:

Admin sets up the repository first (e.g., my-private-repo).

You tag and push the image: 

docker tag my-app:latest 154.65.3.12:5000/my-private-repo:v1
docker push 154.65.3.12:5000/my-private-repo:v1
👉 Again, you cannot push an image unless the repository already exists.

Key Differences: Docker Hub vs. ECR/Nexus

Feature Docker Hub AWS ECR / Nexus Private Registry
Repository Creation Automatic on first push Must be created manually before push
Structure username/repository:tag registry_url/repository:tag
Multi-Repo Per Account? Yes, multiple repositories under one Docker ID Yes, but each repo must be pre-created
Registry Domain docker.io Custom (e.g., 123456789012.dkr.ecr.us-east-1.amazonaws.com or 154.65.3.12:5000)

Now, Let's Clarify: What Are Repositories, Registries, and Image Names?

Docker can be confusing because we often mix up repositories, registries, and image names. Here’s the real breakdown:

1. What is a Registry?

The registry is just the storage service/warehouse (e.g., docker.io, 123456789012.dkr.ecr.us-east-1.amazonaws.com) for Docker images. It hosts multiple repositories and allows users to pull and push images.

  • You can call it username (in case of Docker) / Registry URL (in case of ECR & Nexus).

Examples:

  • Docker Hub (docker.io)
  • AWS ECR (123456789012.dkr.ecr.us-east-1.amazonaws.com)
  • Nexus Private Registry (154.65.3.12:5000)

Think of it like Google Drive—you store all your documents (repositories) in one place.

2. What is a Repository?

A repository is a collection of Docker images for a single application. It stores different versions of an image.

  • It acts as a namespace where Docker images are stored, organized, and managed.
  • Each repository is identified by a name that combines the repository name and the image name, forming a unique identifier.
  • The repository helps categorize and version images, making them easier to manage and retrieve.

Examples: - mibtisam/my-app (Docker Hub) - 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-ecr-repo (AWS ECR) - 154.65.3.12:5000/my-private-repo (Nexus)

Think of it like a Google Drive folder—it contains multiple versions of the same document.

3. What is an Image Name?

The image name includes the registry URL (if needed), repository name, and tag.

Examples: - mibtisam/my-app:v1 → Docker Hub - 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-ecr-repo:v1 → AWS ECR - 154.65.3.12:5000/my-private-repo:v1 → Nexus

Think of it like a file inside a Google Drive folder—it has a name and a version.

4. Repository vs Image Name

  • A repository itself is not the image; rather, it is the location or namespace where the image resides. The typical format for referencing a Docker image is:

  • Docker Hub: username/repository-name:tag

  • ECR/Nexus: registry/repository-name:tag

This includes: - username/registry URL: The Docker account or organization that owns the repository. - repository-name: The name of the repository where the image is stored. - tag: (Optional) A version or specific identifier for the image. If no tag is specified, Docker defaults to the latest tag.

Final Summary

  • Docker Hub lets you push images without pre-creating a repository.
  • ECR and Nexus require a repository to be created first before you push an image.
  • A Registry (e.g., Docker Hub, AWS ECR, Nexus) is a storage warehouse.
  • A Repository is a collection of versions of the same application.
  • An Image Name includes the registry, repository, and tag to uniquely identify it.
  • The image name is distinct from the repository name, with the repository serving as the storage location for images.
  • Repositories don’t have tags—only images do.