• Home
  • Blog
  • Creating a local Docker registry

Creating a local Docker registry

This document explains how to create a local registry to store container images locally.
It can also be used to make Kubernetes use container images only from this registry.


  • A simple registry
  • Docker Registry with restricted access
  • For AirGap environments



Anything bracketed in greater than or less than characters is to be assigned by the user.

For example:

--name <registry>


If you now want to name the registry e.g. k8s.registry, replace this with the following:

--name k8s.registry


Everything else should only be modified when you know what you are doing! Further, everything what was bracketed as clearly as a placeholder selected. So if it reappears somewhere, in this example, you have to replace it with k8s.registry.


A simple registry

The following command is sufficient

docker run -d -p 5000:5000 --restart=always --name registry:2


The images, which are needed, have to be pulled now

docker pull <nginx>

and now tag the images as you want them to be named with

docker tag localhost:5000/<k8s.nginx>

To have the images now in the local registry, you have to push accordingly

docker push localhost:5000/<k8s.nginx>

and remove as follows

docker image remove localhost:5000/<k8s.nginx>

With the command

curl localhost:5000/v2/_catalog

it is now possible to see all images that are in the local registry.


Docker Registry with restricted access

First you need to create a user and a corresponding password for the registry:

mkdir /etc/docker-registry/

docker run \

--entrypoint htpasswd \

registry:2.7.0 -Bbn <testuser> <testpassword> > /etc/docker-registry/ htpasswd


Note that now registry:2.7.0 is needed not registry:2!

Further, if a registry already exists, this must be stopped for it first and is not accessible then also in this time!


docker stop <registry>

Now the registry is started again, but with authentication:

docker run -d \

-p 5000:5000 \

--restart=always \

--name <registry>\

-v /etc/docker-registry/:/auth \

-e "REGISTRY_AUTH=htpasswd" \





Lastly, log in with the following command for the registry:

docker login localhost:5000

Now user and password must be entered. These are the entries in
<user> and <testpwd>.


You can now populate images into the registry like in section 1, but to see the images you now have to use the command

curl -u <user>:<testpwd> localhost:5000/v2/_catalog

must be executed.


In some cases the error code X509 may appear.

Then the daemon.json in the /etc/docker/ directory must be extended as follows

"insecure-registries" : ["localhost:5000"]


AirGap environments

The daemon.json in the /etc/docker/ directory needs the following additional line:

"allow-nondistributable-artifacts" : ["localhost:5000"]

At the end, docker needs to be restarted and possibly the registry container as well.


Check out our latest blogpost

Maximizing Kubernetes Efficiency with eBPF Networking Solutions

Elevate your Kubernetes networking with eBPF, offering powerful solutions for real-time monitoring, secure traffic filtering, and efficient load balancing.
Design Escapes