Why would you want to run a local registry?

  • If you are using vagrant to mimic your qa/staging/prod environments and want to make sure you run the same host OS
  • If you want to test multi-host deployments with Rancher, Kubernetes, Mesos or any other orchestration framework

Without a local registry every time a new docker host is provisioned all the images need to be pulled from the remote registry, this might not be a huge issue, but depending on how many services you run it could take some time to re-download all the images. By having a local registry caching all the images it makes sure you can provision ready to use environments very quickly.

To run the registry there are a few steps

Create configuration file

version: 0.1  
log:  
  level: debug
  formatter: text
http:  
  secret: secret
  addr: :5000
storage:  
  cache:
    blobdescriptor: inmemory
  filesystem:
    rootdirectory: /var/lib/registry
proxy:  
  remoteurl: https://registry-1.docker.io

It is possible to override the settings of the config file via environment variables by using the SECTION_SECTION_... format, eg; STORAGE_CACHE_FILESYSTEM=/path
However, it is recommended to drive the configuration of the registry via a file instead of environment variables.
Settings worth mentioning:

  • storage_filesystem_rootdirectory - where to storage the image layers and repositories
  • proxy - enables a registry to be configured as a pull through cache

The official docs describe the configuration settings in more details.

Create compose file

version: '2'  
services:  
  registry:
    image: registry:2.4
    ports:
      - "5000:5000"
      - "5001:5001"
    volumes:
      - /data/registry:/var/lib/registry
    command:
      serve /var/lib/registry/config.yml
    networks:
      default:
        aliases:
          - registry.local

Bring the registry up

docker-compose up -d  

Verify the registry is online

curl -I localhost:5000  

List the repositories

curl localhost:5000/v2/_catalog  

It should come back as an empty array

{
    "repositories": []
}

Configure docker daemon to use the local registry

Where to change the configuration will depend on the distro you are using, but in any case, make sure the docker daemon is started with the following attributes:

Pull MySQL image

docker pull mysql:latest  

Verify the image has been cached

curl localhost:5000/v2/_catalog  

The MySQL repo should be present in the list

{
    "repositories": [
        "library/mysql",
    ]
}

List the image tags

curl localhost:5000/v2/library/mysql/tags/list  

Should list all the available tags for the image

{
    "name": "library/mysql",
    "tags": [
        "5.5.40",
        "5.5.41",
        "5.5.42",
        "5.5.43",
        "5.5.44",
        "5.5.45",
        "5.5.46",
        "5.5.47",
        "5.5.48",
        "5.5.49",
        "5.5.50",
        "5.5.51",
        "5.5.52",
        "5.5",
        "5.6.17",
        "5.6.20",
        "5.6.21",
        "5.6.22",
        "5.6.23",
        "5.6.24",
        "5.6.25",
        "5.6.26",
        "5.6.27",
        "5.6.28",
        "5.6.29",
        "5.6.30",
        "5.6.31",
        "5.6.32",
        "5.6.33",
        "5.6",
        "5.7.10",
        "5.7.11",
        "5.7.12",
        "5.7.13",
        "5.7.14",
        "5.7.15",
        "5.7.4-m14",
        "5.7.4",
        "5.7.5-m15",
        "5.7.5",
        "5.7.6-m16",
        "5.7.6",
        "5.7.7-rc",
        "5.7.7",
        "5.7.8-rc",
        "5.7.8",
        "5.7.9",
        "5.7",
        "5",
        "latest"
    ]
}