Can't Access Docker Hub? Build Your Private Image Repository with Alibaba Cloud ACR

Common Challenges

Executing docker pull to retrieve a base image, but it remains unresponsive for a long time, showing the error: `docker: Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout`, forcing you to abort with growing frustration...
A mirror registry that worked yesterday is suddenly unavailable today. You find yourself constantly searching online (often adding "latest working" keywords) for new, usable mirror addresses and configuring image accelerators, wasting a significant amount of time that shouldn't be necessary...
Your local machine, configured with a proxy, can pull images, but your cloud server is effectively "offline." Each time, you have to repeat the tedious process of docker save → scp → docker load between your local machine and the cloud, which is mentally and physically exhausting.
Your CI/CD pipeline gets stuck due to "image pull failures," delaying your deployment schedule. You're forced to manually skip tests, skip deployment, and proceed with a heart full of anxiety to fix it in production...

If you are experiencing or have been plagued by these issues, you are not alone.

Current State of Image Pulls

Since mid-May 2023, access to Docker Hub from mainland China has gradually deteriorated. A large number of R&D and operations personnel have had to configure domestic image accelerators to maintain their daily learning, development, and deployment workflows.

However, this relief was short-lived. By June 2024, a batch of public accelerator services, typified by the Shanghai Jiao Tong University Docker Hub mirror, successively announced the termination of their Docker Hub mirroring services. This change means that even the "lifeline" developers could barely rely on has also become unavailable.

Real-World Impact and Hidden Costs

Since then, many developers have entered a cycle of high-frequency operations with low returns:

Search for a new mirror site → Configure the new source address → Works for a few days → Access fails → Search again → Reconfigure again…

Every image pull failure disrupts the development rhythm; every re-search for an image source consumes energy and time; every failed configuration of a new source exacerbates anxiety and a sense of powerlessness.

This "seemingly solvable but actually unsustainable" approach has gradually become a persistent problem for Docker users in China.

Solution: Build Your Own Private Image Repository

To address issues such as difficulties in pulling images, frequent mirror site failures, and inconsistent images across different environments, you can build your own private image repository. This provides image services for individual developers, small teams, and systems that need to be deployed in the cloud but cannot use a proxy:

✅ Fulfill the need for commonly used base images during learning, development, and deployment.

✅ Configure once, and avoid frequent searching and switching of mirror sites for a long time.

✅ Achieve long-term, stable, and unified image sharing within the team and across personal multiple devices.

💡 Core Idea of the Solution

First, obtain the base images. Then, upload these base images, or new container images built to your specific needs, to an Alibaba Cloud Container Registry (ACR) private repository for use by devices that cannot access Docker Hub.

Specific Steps:

Obtain Base Images
- Use a device that can access Docker Hub (e.g., a personal computer with a proxy, an overseas VPS, etc.) to pull the required images.
- Alternatively, access currently available image mirror websites to pull the necessary base images locally.
Build new container images according to your needs.
Upload the built images to your private repository in Alibaba Cloud Container Registry (ACR).
Configure the Alibaba Cloud Container Registry (ACR) private repository address on any device and pull the corresponding images.

Why a Private Repository, Even if I Can Pull Images?

You might wonder: if I can already access Docker Hub, do I still need to set up a private image repository?

This is precisely one of the core problems this solution aims to address— we are not just focused on "can I pull images," but rather "how to manage images more efficiently, stably, and uniformly."

Building your own private image repository is suitable for the following typical scenarios:

How to reuse images across multiple devices (e.g., local development machine, cloud server, test environment) to avoid repeated save/load operations.
How to achieve a unified image source within a team, preventing version drift due to each member configuring their own image sources.
How to ensure the continuity of image pulls in CI/CD pipelines, preventing deployments from getting stuck at the pull stage.
How to maintain version control and architectural consistency for images, unaffected by fluctuations in external image sources.

Just as you can manually copy code but still choose to use Git, or manually deploy applications but choose CI/CD, a private image repository is a way to organize and enhance chaotic image usage practices.

This solution aims to provide a "reusable, promotable, and maintainable" practical approach, rather than a temporary, one-time fix.

Use Cases and Advantages

This solution is not only suitable for individual developers and DevOps engineers but also highly beneficial for small-scale teams looking to build stable development infrastructure in China's complex network environment (most large companies already have their own private image repositories).

It focuses on solving the following typical problem scenarios:

CI/CD build tasks on cloud servers (like Alibaba Cloud ECS) frequently fail due to the inability to pull base images.
When switching between multiple machines (e.g., home laptop, company computer, test server), images are inconsistent, leading to frequent environment discrepancies.
Every time a new project is started or a service is deployed, you need to manually docker pull. If a mirror site is down, you have to find another solution.
Team members configure different image accelerator sources, making it difficult to maintain uniformity and long-term availability.
During tight deadlines, spending a lot of time searching for images and configuring environments severely impacts efficiency and mood.
Using docker image save to export images and docker image load to import them requires manual operations and manual copying to other devices, which is cumbersome.

By building your own private image repository, you can effectively circumvent the above problems, bringing the following advantages:

✅ One-time Acquisition, Long-term Reuse Commonly used images only need to be pulled once. After uploading to your private repository, they can be used across multiple devices for a long time, no longer limited by external network conditions. Especially in cloud environments (e.g., deployment scripts, CI/CD), "predictability" is far more important than "temporary availability."
✅ Unified Sharing Across Multiple Devices Local development, cloud deployment, and test verification all use the same image source. No longer do you need to package on your laptop and then upload to the cloud server every time, saving a lot of repetitive work.
✅ Controllable Image Versions, More Stable Builds Once an image is confirmed to be usable, a fixed version can be uploaded, avoiding compatibility issues caused by unintentional changes in official images (e.g., base dependency upgrades, configuration changes). This fundamentally eliminates build risks like "worked fine yesterday, broken today."
✅ Supports Multi-Architecture Images Different versions of images can be built and uploaded based on device architecture, such as amd64 (mainstream servers) and arm64 (e.g., Apple M series chips), ensuring consistency between local testing and online deployment.
✅ Improved CI/CD Stability No longer relying on external accelerators or mirror sites, the entire build process becomes more controllable, continuous, and stable. Especially in critical scenarios (e.g., urgent fixes, scheduled deployments), stable image pulling is the bottom line for ensuring delivery.

In summary, this is a low-cost, highly controllable "image isolation + image pool" solution suitable for long-term use within the Chinese network environment. It doesn't rely on third-party services, doesn't worry about accelerators failing, and doesn't require save/load every time, truly achieving one-time configuration for long-term benefits.

Prerequisites and Limitations

Before adopting this solution, confirm the following prerequisites:

At least one device capable of accessing Docker Hub To obtain original official images, you need at least one device that can normally access Docker Hub (e.g., a local development machine configured with a proxy, an overseas VPS, etc.) for the initial pull of required base images.
- If your personal computer already has a proxy, you can pull locally and export via docker save.
- If someone in your team has this capability, images can also be uniformly exported and then uploaded for sharing.
Or, other available image pulling channels
- If Docker Hub is inaccessible, you can also consider using existing image distribution platforms (e.g., Xuanyuan Cloud) to obtain base images, then push them to your private repository via docker tag and docker push.
Possess an Alibaba Cloud account with completed personal verification
- This solution relies on Alibaba Cloud Container Registry (ACR), so the following preparations are required in advance:
  - Have an Alibaba Cloud account.
  - Have completed personal real-name verification (Container Registry service can be used for free).
  - It is recommended to enable an ACR instance in East China 1 (Hangzhou) or your local region for optimal bandwidth and access latency.
Familiarity with basic Docker operations Having read this far, we believe you already have some understanding of basic Docker operations. If not, you can refer to the official Docker documentation.

Step-by-Step Workflow and Best Practices

📌 Next, we will explain in detail how to use Alibaba Cloud ACR to create instances, upload images, and reuse them on other devices. Before proceeding, it is recommended to have:

A machine with internet access to pull images

An Alibaba Cloud account and real-name verification

Basic Docker CLI usage capability

1. Alibaba Cloud Preparations

Register or log in to your Alibaba Cloud account, and complete personal verification.
Go to "Console" in the top right corner. Move your mouse to the top left corner to slide out "Products and Services," enter "Container Registry," and click on "Container Registry (ACR)" to enter the ACR console.
In the "Instance List," click on "Personal Instance." In the pop-up prompt panel, click "Create Personal Instance."
For "Region" selection, considering that Alibaba Cloud is located in Hangzhou and its network should be the most stable there, choose China -> East China 1 (Hangzhou). Check the service agreement and usage restrictions, then click "Create Immediately."
After creation, you will be prompted to set a Registry login password (8-32 characters, must include at least two of letters, symbols, or numbers). Remember this password as it will be needed for subsequent access.

After setting the password, you will enter the image repository page. Before creating a repository, let's clarify some concepts and best practices:

🧱 Namespace and Repository Structure Explanation

In Alibaba Cloud ACR, image addresses follow the standard Docker image naming structure:

[registry-domain]/[namespace]/[repository]:[tag]

For example: registry.cn-hangzhou.aliyuncs.com/my-team/node:lts-alpine3.21

Field	Description
`registry`	Image repository address (Alibaba Cloud assigned domain)
`namespace`	Namespace, equivalent to "organization name" or "owner"
`repository`	Image repository name, recommended for storing multiple versions of one application
`tag`	Image tag, representing the specific version number, e.g., `latest` or `v1.0`

🗂 About Namespaces

Namespaces are logical groupings for repositories and can be used to isolate different projects or teams.
Under the same Alibaba Cloud account, a personal ACR instance can create a maximum of 3 namespaces.
It is recommended to name namespaces according to practical scenarios, for example:
- Company level: yourcorp
- Team level: frontend-team
- Project level: ai-service
- Personal level: personal-name

📦 About Image Repositories

A repository is used to store multiple versions of a certain type of image (e.g., the same application, component, or service).
Naming conventions can be:
- Software name: nginx, redis, mysql
- Business component name: user-service, admin-panel, event-bot
It is recommended to maintain a reasonable repository granularity: one repository manages multiple versions of only one type of image, which helps with permission management and clear versioning.
The repository limit is 300.

Before creating a repository, first set the access credentials. Click the "Access Credentials" menu. The password you just set for the Registry is the fixed password. You can see the specific setup command in "Login Instance," where --username is your username, i.e., your Alibaba Cloud account name.
```
docker login --username=[aliyun-account-name] ***.cn-hangzhou.personal.cr.aliyuncs.com
```
Create a namespace. Since multiple people share the same Registry address, namespaces might be taken. Try to enter a name related to your personal use. Click "OK," and keep other options as default.
Select "Image Repository," then click "Create Image Repository." Taking node as an example, select the namespace you just created, enter node for the repository name, keep others as default, enter "Official base image node" for the summary, and click "Next."
In "Code Source," select "Local Repository," meaning we will use locally built images. Then click "Create Image Repository."
At this point, the basic Alibaba Cloud configuration is complete. In the repository's "Basic Information," there are detailed operation guides, including how to log in, pull images, push images. Image addresses are divided into public network addresses and VPC addresses. If your device is within the Alibaba Cloud VPN network, you can choose to use the VPC address.

During the Alibaba Cloud configuration phase, you should record the following information:
- Alibaba Cloud account name;
- Registry login password;
- Public and VPC image addresses (may vary, refer to the page display):
  - Public network: ***.cn-hangzhou.personal.cr.aliyuncs.com
  - VPC: ***.-vpc.cn-hangzhou.personal.cr.aliyuncs.com
- Namespace: my-team-one;
- Repository name: node;

2. Local Image Preparation

Find a device that can access Docker Hub, such as your personal computer, your overseas VPS, or a currently available image mirror.
Taking the official Docker Hub node image as an example, use docker pull to pull the latest image locally.
```
docker pull node:lts-alpine3.21
```

Verify local images to ensure successful pull. The current tag is lts-alpine3.21, and the Image ID is a937d3ed32b0. (These values may differ on your local machine.)

docker images
REPOSITORY                                               TAG               IMAGE ID       CREATED         SIZE
node                                                     lts-alpine3.21    a937d3ed32b0   2 days ago      159MB

Once the image is local, you need to tag (rename) the existing image for uploading to the Alibaba Cloud Registry.

Explanation:
- This operation does not copy image data; it merely creates a new reference for it.
- It uses the following command:
```
docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
```
Where:
- SOURCE_IMAGE[:TAG] can be your local Image ID.
- TARGET_IMAGE[:TAG] is an address composed of multiple components describing the image's storage location and identity, in the format:
```
[registry/][namespace/]name[:tag]
```
- registry is the image repository address, defaulting to docker.io (i.e., Docker Hub).
- namespace is the namespace, defaulting to library, and corresponds to the namespace you just created in Alibaba Cloud Container Registry.
- name is the image name, defaulting to node, and corresponds to the repository name you just created in Alibaba Cloud Container Registry.
- tag is the image tag, defaulting to latest. In Alibaba Cloud Container Service, this is the version number you need to define.
Final command to execute locally:
```
# Note: Do not include [], they only indicate content to be replaced
# [local-image-id] Replace with your local image's Image ID
# [aliyun-registry-url] Replace with your Alibaba Cloud image repository address
# [your-namespace] Replace with the namespace you just created
# [node] Replace with the repository name you just created
# [lts-alpine3.21] Replace with the tag you want to define
docker tag [local-image-id] [aliyun-registry-url]/[your-namespace]/[node]:[lts-alpine3.21]
```
After executing this command, run docker images. You will see two images with the same Image ID but different REPOSITORY entries: one is node, and the other is ***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node. The former is the local image, and the latter is the Alibaba Cloud image repository address.
```
REPOSITORY                                                                    TAG               IMAGE ID       CREATED         SIZE
***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node                     lts-alpine3.21    a937d3ed32b0   4 days ago      159MB
node                                                                          lts-alpine3.21    a937d3ed32b0   4 days ago      159MB
```
At this point, your local image files are ready. Next, you need to upload them to the Alibaba Cloud Registry.

3. Upload Image to Alibaba Cloud

Log in to Alibaba Cloud Container Registry.

# Note: Do not include [], they only indicate content to be replaced
# [aliyun-account-name] Replace with your Alibaba Cloud account name
# [aliyun-registry-url] Replace with your Alibaba Cloud image repository address
# Specific details can be found in the repository's Basic Information - Operation Guide
docker login --username=[aliyun-account-name] [aliyun-registry-url]

Enter the Registry login password you just set. Upon successful login, you will see a Login Succeeded message.

Upload the image to Alibaba Cloud.

# Note: Do not include [], they only indicate content to be replaced
# [aliyun-registry-url] Replace with your Alibaba Cloud image repository address
# [your-namespace] Replace with the namespace you just created
# [node] Replace with the repository name you just created
# [lts-alpine3.21] Replace with the tag you want to define
docker push [aliyun-registry-url]/[your-namespace]/[node]:[lts-alpine3.21]

Upon successful execution, you will see information similar to the following:

The push refers to repository [***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node]
bc25a8c84974: Pushed
625f0765efa8: Pushed
b3c942954ba7: Pushed
08000c18d16d: Pushed
lts-alpine3.21: digest: sha256:cb4769335a5b3b23636053dcb5e2ad7c22de01ade9e772a40d5e77b72d659367 size: 1158

Check your Alibaba Cloud image repository. Under "Image Repository" --> "Image Versions," you can see the information for the image you just uploaded.

4. Usage on Other Devices

On a device that cannot access Docker Hub, first log in to Alibaba Cloud Container Registry:
```
docker login --username=[aliyun-account-name] ***.cn-hangzhou.personal.cr.aliyuncs.com
```
A Login Succeeded message indicates successful login.

Pull the image:

docker pull ***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node:lts-alpine3.21

lts-alpine3.21: Pulling from my-team-one/node
f18232174bc9: Pull complete
5056ee185863: Pull complete
974362762896: Pull complete
18d8590713a4: Pull complete
Digest: sha256:cb4769335a5b3b23636053dcb5e2ad7c22de01ade9e772a40d5e77b72d659367
Status: Downloaded newer image for ***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node:lts-alpine3.21
***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node:lts-alpine3.21

After a successful pull, you can happily use the image!

Alternative Solutions

✴️ Other Solutions

Alternatively, you can use professional Docker image acceleration platforms, such as Xuanyuan Cloud. However, these professional image acceleration platforms require payment for traffic, with an entry-level package costing 5 RMB for 50GB of traffic. If you can meet your needs at a lower cost, save time, and improve efficiency, you might consider using them.

Currently, cloud service providers like Alibaba Cloud, Tencent Cloud, and Huawei Cloud all offer their own image repository services and image accelerators. However, the official image artifacts provided are limited, mostly based on cloud vendor systems like Alibaba Cloud Linux, offering fewer choices for individual developers.

Alibaba Cloud's Container Registry (ACR);
Tencent Cloud's Container Registry (TCR);
Huawei Cloud's Software Repository (SWR);