Docker Registry

Modern applications often use Docker containers, with images pulled from cloud registries such as Docker Hub or other public sources. However, relying on external services can lead to failures due to registry unavailability. To set up a local storage (registry) for Docker images, you can use a local Docker Registry.

1. Starting a local Docker Registry

Docker provides an official registry image for creating a local registry.

docker run -d -p 5000:5000 --name registry registry:2
  • -d — runs the container in detached mode (in the background).
  • -p 5000:5000 — maps port 5000 (the default port for the registry).
  • –name registry — sets the container name.
  • registry:2 — the official Docker Registry image.

Now the local registry is available at localhost:5000.

2. Configuring storage

By default, images are stored in the container’s memory. To enable persistent storage, add a volume:

docker run -d -p 5000:5000 --name registry -v registry-data:/var/lib/registry registry:2

-v registry-data:/var/lib/registry — Mounts the registry-data volume to store images.

3. Working with the local registry

Tagging an image:

  1. To push an image to the local registry, you need to tag it with the prefix localhost:5000/. 
    docker tag my-image:latest localhost:5000/my-image:latest
  2. Pushing an image to the registry: 
    docker push localhost:5000/my-image:latest

  3. Pulling an image from the registry:

    docker pull localhost:5000/my-image:latest

4. Configuring Docker to work with a local registry

If you’re using HTTPS or working on a remote machine, make sure Docker is configured to work with insecure registries. Add the following to the /etc/docker/daemon.json file:

{

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

}

Restart Docker:

sudo systemctl restart docker

5. Additional settings (optional)

Authentication: To secure the registry, set up HTTP authentication using htpasswd:

docker run -d -p 5000:5000 --name registry \
  -v $(pwd)/auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" registry:2

Create an htpasswd file using the following command:

htpasswd -Bc auth/htpasswd <username>

TLS: For a production environment, configure TLS certificates to ensure a secure connection.

6. Checking the contents of the registry

To view the available images, use the registry API:

curl http://localhost:5000/v2/_catalog

Conclusion

Dependence on cloud registries and public Docker images can become a weak point for your service. However, proper strategies — such as using a local registry, caching, custom images, and redundancy — help minimize risks. Setting up a local mirror and using private registries give you control over your infrastructure, while monitoring and automation ensure stability. These measures help prevent service interruptions even in case of issues with external resources.

Tagged: