How to Build a High-Performance Private Docker Registry Using Azure Storage

Using Docker commonly involves docker run or docker pull, but pulling images from Docker Hub in China can be slow; this guide shows how to create a high‑speed private Docker Registry backed by Azure Storage.

First, create a Docker‑machine host in Azure Hong Kong (or Beijing/Shanghai for China‑region accounts) using the Azure driver:

docker-machine create --driver azure --azure-subscription-id {sub-id} --azure-open-port 80 {machine-name}

Next, set up an Azure Storage account and obtain its access key. The same storage account can be used from both the Azure‑hosted machine and a local Docker‑machine.

Then launch the registry container on both the Azure host and the local host, configuring the Azure storage driver with the account name, key, container, and realm. Example commands for macOS/Linux:

docker run -d -p 5000:5000 \
 -e REGISTRY_STORAGE=azure \
 -e REGISTRY_STORAGE_AZURE_ACCOUNTNAME="{Account Name}" \
 -e REGISTRY_STORAGE_AZURE_ACCOUNTKEY="{access key}" \
 -e REGISTRY_STORAGE_AZURE_CONTAINER="{storage container name}" \
 -e REGISTRY_STORAGE_AZURE_REALM="core.chinacloudapi.cn" \
 --name=registry \
 --restart=always \
 registry:2

And for Windows:

docker run -d -p 5000:5000 ^
 -e REGISTRY_STORAGE=azure ^
 -e REGISTRY_STORAGE_AZURE_ACCOUNTNAME="{Account Name}" ^
 -e REGISTRY_STORAGE_AZURE_ACCOUNTKEY="{access key}" ^
 -e REGISTRY_STORAGE_AZURE_CONTAINER="{storage container name}" ^
 -e REGISTRY_STORAGE_AZURE_REALM="core.chinacloudapi.cn" ^
 --name=registry ^
 --restart=always ^
 registry:2

After the registry is running, use the provided scripts to pull an image from Docker Hub via the Azure‑backed registry, push it to the local registry, and then pull it locally, achieving fast and stable transfers.

macOS/Linux script ( pull-image.sh) example:

echo There are $# arguments to $0: $*
 echo Pulling image $3 from docker hub via azure storage
 echo Usage
 echo "-------------------------------------------"
 echo "$1 is the offshore docker-machine name"
 echo "$2 is the local docker-machine name"
 echo "$3 is the image name"
 echo "-------------------------------------------"
 
 echo "-> Swithc to $1"
 eval $(docker-machine env $1)
 echo "-> pulling image $3"
 docker pull $3
 echo "-> tag image $3 and push to local registry"
 docker tag $3 localhost:5000/$3
 docker push localhost:5000/$3
 echo "-> Pull from registry in localhost into $2"
 eval $(docker-machine env $2)
 docker pull localhost:5000/$3
 docker tag localhost:5000/$3 $3
 docker rmi localhost:5000/$3
 echo "-> Done!"

Windows script ( pull-image.cmd) example:

echo off
 echo There are $# arguments to $0: $*
 echo Pulling image $3 from docker hub via azure storage
 echo Usage
 echo "-------------------------------------------"
 echo "%1 is the offshore docker-machine name"
 echo "%2 is the local docker-machine name"
 echo "%3 is the image name"
 echo "-------------------------------------------"
 
 echo "-> Swithc to %1"
 @FOR /f "tokens=*" %i IN ('docker-machine env %1') DO @%i
 echo "-> pulling image %3"
 docker pull $3
 echo "-> tag image %3 and push to local registry"
 docker tag %3 localhost:5000/%3
 docker push localhost:5000/%3
 echo "-> Pull from registry in localhost into %2"
 @FOR /f "tokens=*" %i IN ('docker-machine env %2') DO @%i
 docker pull localhost:5000/%3
 docker tag localhost:5000/%3 %3
 docker rmi localhost:5000/%3
 echo "-> Done!"

The same approach can be applied to other cloud providers such as AWS or Alibaba Cloud using the appropriate Docker Registry storage drivers.