How to Configure iCloud China (icloud.com.cn) in docker-icloudpd for Mainland China Users

Set the environment variables ICLOUD_CHINA=true and AUTH_CHINA=true in your docker-icloudpd container to route all photo downloads and authentication through the Chinese iCloud endpoint at icloud.com.cn instead of the global icloud.com service.

The boredazfcuk/docker-icloudpd container provides native support for users with Apple IDs registered in mainland China, allowing seamless photo downloads from the isolated Chinese iCloud infrastructure. By toggling two specific boolean flags defined in CONFIGURATION.md, you instruct the underlying iCloud Photo Downloader to communicate exclusively with icloud.com.cn endpoints while maintaining full compatibility with the container's automated sync features.

Understanding the China-Specific Configuration Variables

According to the source code documentation in CONFIGURATION.md (lines 92 and 94), docker-icloudpd exposes two distinct environment variables that control China-region behavior. These are processed by the core shell scripts sync-icloud.sh and launcher.sh on every container start.

ICLOUD_CHINA (Photo Downloads)

When set to true, this variable forces the downloader to contact icloud.com.cn for all photo-list and download requests instead of the default icloud.com. In sync-icloud.sh, the logic checks this flag before constructing API endpoints:

if [ "${icloud_china}" = true ]; then
    # use icloud.com.cn for API calls

fi

If the flag is false (the default set by init_config.sh), the container uses the global iCloud service.

AUTH_CHINA (Authentication)

When set to true, the initial cookie-generation step also uses icloud.com.cn. This is mandatory if your Apple ID was created on the Chinese iCloud service, as global authentication servers will reject credentials registered in the China region. The launcher.sh wrapper checks this variable when constructing the initial authentication flow.

Step-by-Step Configuration Guide

1. Set the environment variables

   Add ICLOUD_CHINA=true to your container environment. If your Apple ID was created in China, also add AUTH_CHINA=true.

2. Map the correct timezone

   Use TZ=Asia/Shanghai to ensure timestamps align with the Chinese service.

3. Persist the configuration

   Mount a volume to /config so that /config/icloudpd.conf persists across restarts. The container writes default values (including icloud_china=false) on first start via init_config.sh.

4. Verify network connectivity

   Ensure your Docker host can resolve and reach icloud.com.cn. As noted in change.log (line 879), the maintainers amended domain and route checks to be compatible with the icloud_china variable, preventing false "network-unavailable" warnings when the container contacts Chinese servers.

Configuration Examples

Docker Compose

services:
  icloudpd:
    image: boredazfcuk/icloudpd:latest
    environment:
      - TZ=Asia/Shanghai
      - ICLOUD_CHINA=true
      - AUTH_CHINA=true
      - APPLE_ID=you@example.cn
    volumes:
      - ./photos:/home/user/iCloud
      - ./config:/config
    restart: unless-stopped

Environment File

Create a .env file in your project directory:

TZ=Asia/Shanghai
ICLOUD_CHINA=true
AUTH_CHINA=true
APPLE_ID=you@example.cn

Manual Configuration File

Edit /config/icloudpd.conf directly:

apple_id=you@example.cn
icloud_china=true
auth_china=true

After editing, restart the container to apply changes:

docker compose up -d --force-recreate icloudpd

Technical Implementation Details

The endpoint switching logic is implemented across two core shell scripts. In sync-icloud.sh, the application evaluates the icloud_china variable to determine whether to query icloud.com.cn for photo metadata and download URLs. The launcher.sh wrapper performs similar conditional checks when constructing the launch command and validating that the route to the Chinese endpoint is reachable.

When icloud_china=true, the scripts adjust domain validation logic to avoid false positives. The changelog entry at line 879 of change.log documents this refinement: "Amended domain and route checks to be compatible with icloud_china variable."

Summary

• Set ICLOUD_CHINA=true to route photo downloads through icloud.com.cn instead of icloud.com
• Set AUTH_CHINA=true if your Apple ID requires Chinese authentication endpoints for initial login
• Both variables are documented in CONFIGURATION.md (lines 92-94) and processed by sync-icloud.sh and launcher.sh
• The container automatically adjusts domain validation logic when China mode is enabled, preventing false network errors
• Persist configuration in /config/icloudpd.conf via volume mounts to maintain settings across container restarts

Frequently Asked Questions

Do I need to set both ICLOUD_CHINA and AUTH_CHINA?

If your Apple ID was created in mainland China, yes. Set both environment variables to true. The AUTH_CHINA flag ensures the cookie generation step in launcher.sh contacts the correct authentication endpoint, while ICLOUD_CHINA handles the subsequent photo downloads in sync-icloud.sh.

What happens if I only set ICLOUD_CHINA but not AUTH_CHINA?

The photo downloader will attempt to reach icloud.com.cn for downloads, but the initial cookie generation might fail if it tries to authenticate against icloud.com. This results in authentication errors during the sync startup phase, as the global servers reject credentials belonging to the Chinese partition.

How can I verify the container is using the Chinese endpoint?

Check the container logs for connection attempts to https://www.icloud.com.cn. The sync-icloud.sh script constructs URLs based on the icloud_china variable, and successful connections will show this domain in debug output rather than icloud.com. Additionally, the domain check validation will specifically test connectivity to icloud.com.cn when the flag is enabled.

Will enabling China mode affect download performance?

The container adjusts route checks specifically for icloud.com.cn as documented in change.log, but actual download speed depends on your ISP's peering with Chinese CDNs. The configuration ensures proper routing without triggering the false "network-unavailable" errors that would occur if the container tried to validate Chinese routes against global DNS expectations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}