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.