Local Container Registry Setup

Overview

A local Docker registry allows you to store and distribute container images within your development environment without relying on external services like Docker Hub.

Prerequisites

Docker installed and running
Basic understanding of Docker images and tags

Quick Setup

Run Local Registry

Start a registry container on port 5000:
Terminal window
```
docker run -d -p 5000:5000 --name registry registry:2
```
Verify Registry is Running
Terminal window
```
docker ps | grep registry
```
Tag an Image

Tag an existing image for your local registry:
Terminal window
```
docker tag my-app:latest localhost:5000/my-app:latest
```

Push to Local Registry

docker push localhost:5000/my-app:latest

Pull from Local Registry

docker pull localhost:5000/my-app:latest

Persistent Storage

By default, the registry stores images in the container. To persist data, use a volume:

docker run -d \
  -p 5000:5000 \
  --name registry \
  -v /path/to/registry:/var/lib/registry \
  registry:2

Configuration Options

With Authentication

Create a password file:

mkdir auth
docker run --entrypoint htpasswd httpd:2 -Bbn myuser mypassword > auth/htpasswd

Run registry with authentication:

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

docker login localhost:5000

With TLS/SSL

For production-like environments, configure TLS:

docker run -d \
  -p 5000:5000 \
  --name registry \
  -v "$(pwd)"/certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  registry:2

Using with Docker Compose

version: '3'
services:
  registry:
    image: registry:2
    ports:
      - "5000:5000"
    volumes:
      - ./registry-data:/var/lib/registry
    restart: always

Start the registry:

docker-compose up -d

List Images in Registry

View all images stored in your local registry:

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

View tags for a specific image:

curl http://localhost:5000/v2/my-app/tags/list

Cleanup

Stop and Remove Registry

docker stop registry
docker rm registry

Remove Registry Data

rm -rf /path/to/registry

Troubleshooting

Connection Refused

Ensure the registry container is running:

docker ps | grep registry

Push/Pull Fails

If using a non-localhost address, you may need to configure Docker to allow insecure registries. Edit /etc/docker/daemon.json:

{
  "insecure-registries": ["myregistry.local:5000"]
}

Restart Docker after making changes.