Docker Registry: the Ultimate Master Guide

This guide covers everything about storing and sharing Docker Images. It explains Public Registries (like Docker Hub), how to decipher complex image names, and how to set up your own Private Registry.

What is a Docker Registry?

Think of a Registry like "GitHub" but for Docker Images.

• Image: The application package (the code).

• Repository: A collection of different versions (tags) of the same image (e.g., nginx is a repo containing latest, 1.19, alpine).

• Registry: The server that stores these repositories.

Default Behavior

When you run docker run nginx, Docker assumes you mean the default public registry: Docker Hub.

Deciphering Image Names

An image name is actually a URL path. Let's break down the full structure: REGISTRY / USER_OR_ACCOUNT / IMAGE_NAME : TAG

Example A: Docker Hub (implicit)

Command: docker run nginx

• Full Name: docker.io/library/nginx:latest

• Registry: docker.io (Docker Hub).

• User: library (Official images live here).

• Image: nginx.

Example B: Docker Hub (user Image)

Command: docker run mmumshad/simple-webapp

• Registry: docker.io

• User: mmumshad

• Image: simple-webapp

Example C: Google Container Registry (gcr)

Image: gcr.io/kubernetes-e2e-test-images/dnsutils

• Registry: gcr.io (Google's Registry).

• Account: kubernetes-e2e-test-images (Project name).

• Image: dnsutils.

Working with Docker Hub (public)

To upload your own images to Docker Hub, you need to authenticate.

Login

Command:

docker login

• Action: Prompts for Username and Password.

• Important Warning: On Linux systems without a credentials store, Docker might warn you:

  WARNING! Your password will be stored unencrypted in /home/user/.docker/config.json.

  • Meaning: If someone hacks your laptop and reads this file, they get your password. Use "Docker Credential Helpers" for production security.

Tagging (renaming)

Before pushing, the image must start with your Docker ID. Command:

docker tag my-image:latest registry-user/my-image:v1

• my-image:latest: Source image on your laptop.

• registry-user: Your Docker Hub username.

Pushing (uploading)

Command:

docker push registry-user/my-image:v1

Private Registry (self-hosted)

Sometimes companies don't want to upload their code to the public Docker Hub. They want a Private Registry inside their own company network.

Good news: The Registry itself is just a Docker Container!

Step 1: Deploy the Registry

Command:

docker run -d -p 5000:5000 --name registry registry:2

Breakdown:

• -d: Run in background.

• -p 5000:5000: The Registry listens on port 5000 by default. We map it to port 5000 on the host.

• --name registry: Naming the container.

• registry:2: The official image from Docker meant to act as a registry server.

Step 2: Tagging for Local Registry

To push to this private registry, you must rename the image to include the Address of the registry (localhost:5000).

Command:

docker image tag my-image localhost:5000/my-image

• Explanation: Docker looks at the start of the tag. If it sees a domain or IP (like localhost:5000), it knows not to go to Docker Hub, but to that specific address.

Step 3: Pushing to Private Registry

Command:

docker push localhost:5000/my-image

• Action: Uploads the layers to your local registry container running on port 5000.

Step 4: Pulling (downloading)

From the same machine:

docker pull localhost:5000/my-image

From another machine (e.g., Server IP 192.168.56.100):

docker pull 192.168.56.100:5000/my-image

Important Note: Insecure Registries

By default, Docker enforces HTTPS (TLS) for all registries. If you set up a simple private registry (like above) using HTTP (IP address), Docker will block you with an error:

http: server gave HTTP response to HTTPS client

The Fix: You must edit /etc/docker/daemon.json on the client machine (the one trying to pull/push) to allow this specific insecure registry.

{
  "insecure-registries" : ["192.168.56.100:5000"]
}