Setting up private registry in Docker - Step-by-Step CLI Walkthrough

Introduction

Sometimes you want to store your Docker images privately instead of using public services. A private registry lets you keep your images safe and share them only with your team.

When you want to share Docker images only within your company without exposing them publicly

When you need faster image downloads inside your local network

When you want full control over image storage and access

When you want to avoid limits or costs of public registries

When you want to integrate image storage with your existing infrastructure

Config File - docker-compose.yml

docker-compose.yml

version: '3.8'
services:
  registry:
    image: registry:2
    ports:
      - "5000:5000"
    restart: always
    environment:
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /var/lib/registry
    volumes:
      - registry-data:/var/lib/registry
volumes:
  registry-data:

This file uses Docker Compose to start a private Docker registry service.

• image: Uses the official Docker registry image version 2.
• ports: Maps port 5000 on your machine to the registry container.
• volumes: Stores registry data persistently on your machine.
• environment: Sets the storage directory inside the container.

Commands

Starts the private Docker registry in the background using the docker-compose.yml file.

Terminal

docker-compose up -d

Expected Output

Creating network "default" with the default driver

Creating volume "registry-data" with default driver

Creating registry_registry_1 ... done

→

-d - Run containers in detached mode (in the background)

Checks that the registry container is running and listening on port 5000.

Terminal

docker ps

Expected Output

CONTAINER ID   IMAGE         COMMAND                  CREATED          STATUS          PORTS                    NAMES

abcdef123456   registry:2    "/entrypoint.sh /etc…"   10 seconds ago   Up 9 seconds    0.0.0.0:5000->5000/tcp   registry_registry_1

Downloads the busybox image from Docker Hub to your local machine to test pushing it to your private registry.

Terminal

docker pull busybox

Expected Output

Using default tag: latest

latest: Pulling from library/busybox

Digest: sha256:3b9e0a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1

Status: Downloaded newer image for busybox:latest

docker.io/library/busybox:latest

Tags the busybox image with the address of your private registry so you can push it there.

Terminal

docker tag busybox localhost:5000/busybox

Expected Output

No output (command runs silently)

Uploads the tagged busybox image to your private registry running on localhost port 5000.

Terminal

docker push localhost:5000/busybox

Expected Output

The push refers to repository [localhost:5000/busybox]

5a5ea0f1a7a1: Pushed 

latest: digest: sha256:3b9e0a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1 size: 527

Lists the repositories stored in your private registry to verify the push was successful.

Terminal

curl -X GET http://localhost:5000/v2/_catalog

Expected Output

{"repositories":["busybox"]}

Key Concept

If you remember nothing else from this pattern, remember: running a private Docker registry lets you store and share images securely on your own network.

Common Mistakes

Trying to push an image without tagging it with the registry address

Docker doesn't know where to send the image, so the push fails

Always tag your image with the private registry address before pushing, e.g., docker tag busybox localhost:5000/busybox

Not exposing the registry port 5000 on the host

You cannot connect to the registry from outside the container

Map port 5000 in docker-compose.yml using ports: - 5000:5000

Not running the registry container before pushing images

Push commands fail because the registry service is not available

Start the registry with docker-compose up -d before pushing images

Summary

Use docker-compose.yml to define and run a private Docker registry service on port 5000.

Start the registry with docker-compose up -d and verify it is running with docker ps.

Pull an image, tag it with your registry address, and push it to your private registry.

Verify the image is stored by querying the registry catalog with curl.

Practice

1. What is the main purpose of setting up a private Docker registry?

easy

A. To automatically update Docker images from Docker Hub

B. To speed up Docker container execution

C. To store Docker images securely within your own network

D. To monitor running Docker containers

Solution

1. Step 1: Understand what a Docker registry does

   A Docker registry stores Docker images so they can be shared and reused.

2. Step 2: Identify the benefit of a private registry

   A private registry keeps images secure and accessible only within your network.

3. Final Answer:

   To store Docker images securely within your own network -> Option C

4. Quick Check:

   Private registry = secure image storage [OK]

Hint: Private registry means secure image storage inside your network [OK]

Common Mistakes:

• Confusing registry with container runtime
• Thinking it speeds up container execution
• Assuming it automatically updates images

2. Which command correctly starts a private Docker registry on port 5000?

easy

A. docker start registry -p 5000:5000

B. docker build -t registry:5000 .

C. docker create registry -p 5000:5000

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

Solution

1. Step 1: Identify the correct Docker command to run a container

   The command to start a container is 'docker run' with port mapping.

2. Step 2: Check the syntax for running the registry image

   docker run -d -p 5000:5000 --name registry registry:2 uses 'docker run -d -p 5000:5000 --name registry registry:2' which is correct.

3. Final Answer:

   docker run -d -p 5000:5000 --name registry registry:2 -> Option D

4. Quick Check:

   Run container with port 5000 mapped = docker run -d -p 5000:5000 --name registry registry:2 [OK]

Hint: Use 'docker run -d -p 5000:5000' to start registry container [OK]

Common Mistakes:

• Using 'docker start' instead of 'docker run'
• Confusing 'docker create' with 'docker run'
• Trying to build instead of run the registry image

3. After running a private registry on localhost:5000, what is the correct command to tag an image named myapp for pushing to this registry?

medium

A. docker tag myapp localhost:5000/myapp

B. docker push myapp localhost:5000/myapp

C. docker tag localhost:5000/myapp myapp

D. docker run myapp localhost:5000/myapp

Solution

1. Step 1: Understand tagging for private registry

   To push an image to a private registry, you must tag it with the registry address first.

2. Step 2: Identify the correct tag command

   docker tag myapp localhost:5000/myapp uses 'docker tag myapp localhost:5000/myapp' which correctly tags the image.

3. Final Answer:

   docker tag myapp localhost:5000/myapp -> Option A

4. Quick Check:

   Tag image with registry address before push = docker tag myapp localhost:5000/myapp [OK]

Hint: Tag image as 'localhost:5000/name' before pushing [OK]

Common Mistakes:

• Trying to push without tagging first
• Reversing tag source and target
• Using 'docker run' instead of 'docker tag'

4. You tried to push an image to your private registry but got an error: denied: requested access to the resource is denied. What is the most likely cause?

medium

A. The registry container is not running

B. The image was not tagged with the private registry address

C. Docker daemon is not installed

D. The image name contains invalid characters

Solution

1. Step 1: Understand the error meaning

   The error means Docker cannot find the image at the specified registry path.

2. Step 2: Check tagging before pushing

   If the image is not tagged with the private registry address, push will fail with this error.

3. Final Answer:

   The image was not tagged with the private registry address -> Option B

4. Quick Check:

   Push denied = missing correct tag [OK]

Hint: Check if image is tagged with registry address before push [OK]

Common Mistakes:

• Assuming registry container is stopped without checking
• Thinking Docker daemon is missing
• Blaming image name format without evidence

5. You want to secure your private Docker registry with TLS. Which of these steps is necessary to enable HTTPS access?

hard

A. Mount your TLS certificate and key into the registry container and configure the registry to use them

B. Run the registry container with the --tls flag without any certificates

C. Tag images with https:// prefix before pushing

D. Use Docker Hub instead of a private registry

Solution

1. Step 1: Understand TLS setup for private registry

   To enable HTTPS, the registry needs valid TLS certificates mounted and configured.

2. Step 2: Identify correct method to provide TLS certs

   Mounting the certificate and key files into the container and configuring the registry is required.

3. Final Answer:

   Mount your TLS certificate and key into the registry container and configure the registry to use them -> Option A

4. Quick Check:

   TLS requires certs mounted and configured [OK]

Hint: Mount TLS certs into registry container for HTTPS [OK]

Common Mistakes:

• Expecting a --tls flag to work without certs
• Tagging images with https:// prefix
• Using Docker Hub instead of securing private registry