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

The Problem

When your local computer can pull Docker Hub images but another device cannot, you can push the images you need to your own repository and pull them from the target device. This reduces repeated docker save, file transfers, and docker load operations.

This guide uses an Alibaba Cloud Container Registry (ACR) personal instance and node:lts-alpine3.21 to demonstrate the workflow from a local image to reuse on another device.

Pull, Push, and Reuse

1. Pull the required image on a device that can access Docker Hub.
2. Add a tag that includes your ACR repository address.
3. Log in to ACR and push the image.
4. Log in to the same registry on the target device and pull the image.

This workflow hosts an image you have already obtained in ACR. Subsequent pulls no longer depend on the original mirror service, but still depend on ACR and the connection between the target device and the registry. It does not automatically synchronize upstream updates or replace the initial source of the image.

Use Cases

• Reuse base images between a personal development machine and a test server.
• Provide an explicit registry address and image version for development and testing.
• Store images you have verified to reduce repeated downloads and manual file transfers.

This guide demonstrates a personal instance. Alibaba Cloud documentation states that personal instances are for development and testing only, have no SLA commitment, and should not serve production workloads. For production, evaluate an enterprise instance or another suitable registry service.

Prerequisites and Limitations

• Image source: At least one device must be able to obtain the required image. When using another source, verify its provenance and version.
• Account and repository: Prepare an Alibaba Cloud account eligible for a personal instance, complete personal real-name verification, and record the registry domain, namespace, repository name, and login credentials. Choose a region based on the target device location and observed connectivity.
• Version selection: The node:lts-alpine3.21 tag, image IDs, digests, and sizes below are examples, not a claim about the latest release. Tags can change; to pin an exact image, see Docker's pull-by-digest documentation.
• Device architecture: Check whether the target requires linux/amd64 or linux/arm64. For reuse across architectures, docker pull --platform=linux/amd64 node:lts-alpine3.21 explicitly selects the target platform. A normal single-platform pull, tag, and push workflow does not copy a complete multi-platform image. See Docker multi-platform documentation for relevant build methods.
• Personal-instance limits: Personal instances have usage quotas, shared bandwidth, and rate limits. Check the console and official limits for your registry domain, quotas, and currently available regions.

Content updated: October 4, 2026. The command outputs below retain the original examples; image IDs, digests, and console screens should be checked against your actual environment.

Step-by-Step Instructions

1. Alibaba Cloud Preparations

1. Register or log in to your Alibaba Cloud account, and complete personal verification.

2. 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.

3. In the "Instance List," click on "Personal Instance." In the pop-up prompt panel, click "Create Personal Instance."

4. Choose a region suitable for access from the target device. This example uses East China 1 (Hangzhou); available regions depend on the console. Read the service agreement and usage limits before creating the instance.

5. Set a registry login password under "Access Credentials," following the requirements shown in the console. Use this credential for subsequent docker login commands.

6. 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:

   Bash

   Copy

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

   For example:

   Bash

   Copy

   crpi-example.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/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.

   • The number of namespaces you can create depends on your current instance quota.

   • 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.

   • Repository count and storage capacity depend on your current instance quota.

7. 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.

   Bash

   Copy

   docker login --username=[aliyun-account-name] crpi-example.cn-hangzhou.personal.cr.aliyuncs.com

8. Create a namespace, such as my-team-one. If the name is unavailable, choose another as directed by the console.

9. Select "Image Repository," then "Create Image Repository." Select your namespace, enter node as the repository name, choose Private as the repository type, describe the image purpose, and click "Next."

10. In "Code Source," select "Local Repository," meaning we will use locally built images. Then click "Create Image Repository."

11. Read the login, push, and pull commands in the repository's "Basic Information" operation guide. Use the VPC address only when the target device has the appropriate VPC connectivity. The crpi-example domains below are placeholders; replace them with the actual domains shown in your console.

    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: crpi-example.cn-hangzhou.personal.cr.aliyuncs.com
      • VPC: crpi-example-vpc.cn-hangzhou.personal.cr.aliyuncs.com
    • Namespace: my-team-one;
    • Repository name: node;

2. Local Image Preparation

1. Find a device that can access Docker Hub, such as your personal computer, your overseas VPS, or a currently available image mirror.

2. Using the official Docker Hub node image, pull the required tag locally. For use across architectures, select the target platform as described above.

   Bash

   Copy

   docker pull node:lts-alpine3.21

3. 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.)

   Bash

   Copy

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

4. 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:

     Bash

     Copy

     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:

     Bash

     Copy

     [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 required image name. This example uses node, matching the repository you just created.

   • tag is the image tag, defaulting to latest. In Alibaba Cloud Container Registry, this is the version number you need to define.

   Final command to execute locally:

   Bash

   Copy

   # 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 crpi-example.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.

   Bash

   Copy

   REPOSITORY                                                                    TAG               IMAGE ID       CREATED         SIZE
   crpi-example.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

1. Log in to Alibaba Cloud Container Registry.

   Bash

   Copy

   # 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]

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

3. Upload the image to Alibaba Cloud.

   Bash

   Copy

   # 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:

   Bash

   Copy

   The push refers to repository [crpi-example.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

4. 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:

  Bash

  Copy

  docker login --username=[aliyun-account-name] crpi-example.cn-hangzhou.personal.cr.aliyuncs.com

  A Login Succeeded message indicates successful login.

• Pull the image:

  Bash

  Copy

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

  Bash

  Copy

  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 crpi-example.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node:lts-alpine3.21
  crpi-example.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node:lts-alpine3.21

• After a successful pull, verify the platform and runtime behavior on the target device before using it for development and testing.

Other Options

If your main requirement is to pull public images directly, you can also evaluate mirror services such as Xuanyuan Cloud. Check image coverage, pricing, traffic quotas, and availability separately; these services are not equivalent to hosting your own repository.

For image hosting, compare instance specifications, access controls, connectivity, and service commitments across these services:

• Alibaba Cloud Container Registry (ACR);
• Tencent Cloud Container Registry (TCR);
• Huawei Cloud Software Repository (SWR).

References

• Alibaba Cloud Container Registry - Personal Instance Documentation;
• Xuanyuan Cloud;