Deploying a Private Docker Registry on Azure China with azure-docker-registry-template

The article introduces Docker Registry concepts, distinguishing public registries like Docker Hub from private, enterprise‑grade registries, and explains why a simple docker run command is insufficient for a production‑ready service.

It then presents the azure-docker-registry-template , an open‑source ARM template from Microsoft China Cloud Computing Center that automates the deployment of a full‑featured Docker Registry on Azure, creating a cluster of VMs, an Azure storage account for blob storage, and a load balancer, with built‑in TLS support.

The project consists of several key files:

azuredeploy-template.json : the ARM deployment template.

azuredeploy.parameters.json : parameters such as adminUsername , adminPassword , dnsNameforLBIP , numberOfInstances , vmSize , and sshRSAPublicKey .

cloud-config-template.yml : cloud‑init script for VM provisioning.

deploy-docker-registry.sh : wrapper shell script that injects user parameters into the ARM template and triggers the deployment.

The cloud-config-template.yml file writes two TLS certificate files to the VM:

- path: "/etc/docker-registry/certs/server.crt"
  permissions: "0644"
  encoding: "base64"
  owner: "root"
  content: |
    {{{serverCertificate}}}

- path: "/etc/docker-registry/certs/server.key"
  permissions: "0644"
  encoding: "base64"
  owner: "root"
  content: |
    {{{serverKey}}}

These certificates are later referenced by the Docker Registry service.

The Docker Compose manifest that starts the registry uses Azure Blob storage as the backend:

- path: "/etc/docker-registry/manifests/docker-compose.yml"
  permissions: "0644"
  owner: "root"
  content: |
    registry:
      container_name: myregistry
      restart: always
      image: registry
      ports:
        - 5000:5000
      environment:
        REGISTRY_HTTP_TLS_CERTIFICATE: /certs/server.crt
        REGISTRY_HTTP_TLS_KEY: /certs/server.key
        REGISTRY_STORAGE: azure
        REGISTRY_STORAGE_AZURE_ACCOUNTNAME: "<<
>>"
        REGISTRY_STORAGE_AZURE_ACCOUNTKEY: "<<
>>"
        REGISTRY_STORAGE_AZURE_CONTAINER: "<<
>>"
        REGISTRY_STORAGE_AZURE_REALM: "core.chinacloudapi.cn"
      volumes:
        - /etc/docker-registry/certs:/certs

A systemd unit ensures the registry starts automatically and restarts on failure:

- path: "/etc/systemd/system/docker-registry.service"
  permissions: "0644"
  owner: "root"
  content: |
    [Unit]
    Description=Docker registry
    Requires=docker.service
    After=docker.service

    [Service]
    Restart=always
    TimeoutStartSec=0
    RestartSec=5s
    ExecStartPre=/usr/bin/docker pull mirror.azure.cn:5000/library/registry
    ExecStartPre=/usr/bin/docker-compose -f /etc/docker-registry/manifests/docker-compose.yml up -d
    ExecStart=/bin/echo "started."

    [Install]
    WantedBy=multi-user.target

The create-blob.sh script (omitted for brevity) creates the Azure Blob container that stores all images after the VM is provisioned.

An initialization snippet installs Docker Engine and Docker Compose on the VMs:

runcmd:
  - echo "deb https://mirror.azure.cn/docker-engine/apt/repo/ ubuntu-xenial main" | sudo tee /etc/apt/sources.list.d/docker.list
  - apt-get update
  - apt-get install -y docker-engine
  - apt-get install -y docker-compose

To secure the registry, a self‑signed certificate is generated with OpenSSL:

openssl req -newkey rsa:4096 -nodes \
    -sha256 -keyout /certs/server.key \
    -x509 -days 365 -out /certs/server.crt

The Common Name must match the fully qualified domain name derived from the dnsNameforLBIP parameter and the chosen Azure region (e.g., myhub.chinanorth.cloudapp.chinacloudapi.cn ).

After importing the certificate into the OS trust store (Keychain on macOS or the Windows certificate manager) and restarting the Docker daemon, the deployment is triggered with:

./deploy-docker-registry.sh \
    -n "
" \
    -l "
"

The script provisions the resources in a few minutes; the number of VM instances can be scaled by adjusting the numberOfInstances parameter.

Once deployed, images can be pushed and pulled using commands such as:

docker pull/push xxx.chinanorth.cloudapp.chinacloudapi.cn:5000/xxx

This provides a fully functional, TLS‑secured private Docker Registry hosted in Azure China.