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

> Configure iCloud China icloud.com.cn for Chinese users with docker-icloudpd. Set environment variables ICLOUD_CHINA and AUTH_CHINA to route photos and authentication correctly.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) and [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh), the logic checks this flag before constructing API endpoints:

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) persists across restarts. The container writes default values (including `icloud_china=false`) on first start via [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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

```yaml
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:

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

```

### Manual Configuration File

Edit [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) directly:

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

```

After editing, restart the container to apply changes:

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) (lines 92-94) and processed by [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) and [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh)
- The container automatically adjusts domain validation logic when China mode is enabled, preventing false network errors
- Persist configuration in [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) contacts the correct authentication endpoint, while `ICLOUD_CHINA` handles the subsequent photo downloads in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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.