docker-icloudpd: Alpine Linux Container for Automated iCloud Photos Backup

What docker-icloudpd Does and Who Uses It

docker-icloudpd wraps the iCloud Photos Downloader command-line utility in an Alpine Linux Docker container and adds a set of features designed for long-running, unattended home server deployments. The README describes the author's specific use case: syncing the photo streams of all the iDevices in a household back to a server, which is described as the only way to back up multiple devices to a single location.

The target user is a home server operator, typically running Synology NAS, Unraid, or a Portainer-managed Docker environment, who wants iCloud photos available locally without manually exporting from an iPhone. The project addresses a specific friction point: iCloud does not expose a native server-side sync API, so the only automated download path is through the iCloud Photos Downloader utility, which this container packages and extends.

The README is explicit that this project is a container wrapper, not a replacement for iCloud Photos Downloader itself. The download logic comes from that upstream tool; docker-icloudpd adds the surrounding infrastructure for persistent authentication, notifications, and supplementary features like HEIC conversion and Nextcloud upload.

HEIC-to-JPG Conversion and Nextcloud Integration

One of the most cited reasons for using this container over the bare iCloud Photos Downloader utility is the automatic HEIC-to-JPG conversion. iPhones record photos in HEIC format by default, which has broad support on Apple devices but inconsistent support in other photo management tools and media servers. The container converts downloaded HEIC files to JPG without manual intervention.

The README states that the Nextcloud integration uploads every downloaded file to a configured Nextcloud server. It also uploads the JPG files created from HEIC conversions. Delete synchronisation is also supported: when a photo is removed from iCloud, the corresponding file on Nextcloud is removed. This makes the Nextcloud instance a real-time mirror of the iCloud library rather than a one-way import.

The HEIC conversion and Nextcloud upload are configured through environment variables documented in CONFIGURATION.md. The README does not list those variable names; it directs all configuration questions to the CONFIGURATION.md file at the GitHub repository root.

Authentication: MFA, Telegram Bot, and reauth.sh

iCloud authentication uses Apple's multi-factor authentication flow, which generates time-limited session cookies. When a cookie expires, the container must re-authenticate, which historically required interactive access to the container's command line. docker-icloudpd offers two approaches to make re-authentication less disruptive.

The first approach is reauth.sh, a script available from the Docker command line. Running it prompts for the MFA code without requiring a full container reinitialisation. The README describes this as easier local re-authentication compared to the original process.

The second approach uses the Telegram integration for fully remote re-authentication. Because the container already maintains a two-way Telegram connection for notifications, it can receive re-authentication requests through that channel. The caregiver sends a message to the Telegram bot saying they want to re-authenticate. The container responds when it is ready, asking for the MFA code. Sending that code through Telegram completes the login. The README describes this as eliminating the need to ever access the container command line for routine re-authentication.

The system keyring stores credentials securely within the container rather than in plaintext environment variables.

Notification Services and Two-Way Telegram Communication

docker-icloudpd supports eleven notification services: Telegram, Prowl, Pushover, WebHook, DingTalk, Discord, openhab, IYUU, WeCom, msmtp, and Signal. Notifications report sync status, authentication events, and errors.

The Telegram integration is the most capable of these because it supports two-way communication. Beyond receiving notifications, the caregiver can send a message to the Telegram chat to trigger an immediate sync rather than waiting for the next scheduled check. The README describes this as "2-way comms via Telegram" and lists it as a distinct feature.

The breadth of notification options reflects the variety of home server setups among the project's users: some prefer Discord for their home server community, others use Home Assistant webhooks (via the generic WebHook option), and users in China commonly use DingTalk, WeCom, or IYUU. All of these are configured through environment variables in CONFIGURATION.md.

The ADP Limitation and What It Means

The README states clearly and prominently: Apple's Advanced Data Protection (ADP) is not supported. ADP must be disabled for this container to work.

Advanced Data Protection is an opt-in iCloud feature that extends end-to-end encryption to most iCloud data categories, including photos, Notes, and iCloud Drive. When ADP is enabled, Apple's servers cannot access the encrypted data, which also prevents third-party tools like iCloud Photos Downloader from authenticating and downloading files through the standard API.

Disabling ADP restores the default iCloud encryption model, where Apple holds the keys and can assist with account recovery. This is a deliberate security tradeoff: the automated backup capability comes at the cost of the additional encryption layer that ADP provides. Users who enabled ADP specifically to protect their photo library from server-side access should weigh this tradeoff carefully before deploying this container.

This limitation is inherent to the upstream iCloud Photos Downloader utility, not to this container. No workaround exists as of the last documented state of the project.

Repository Layout and Configuration Reference

The repository contains the container definition and supporting scripts. The icloudpd.dockerfile is the primary Dockerfile. icloudpd.dockerfile-sourcebuild is an alternative that builds iCloud Photos Downloader from source rather than using a packaged version. The launcher.sh script is the container entrypoint that reads configuration and starts the sync process. The sync-icloud.sh script contains the main download logic. The healthcheck.sh script provides the Docker health check. The reauth.sh script handles cookie renewal. The authenticate.exp is an Expect script that handles the interactive MFA flow. A docker-compose/ directory contains example Docker Compose configurations for common deployments.

The CONFIGURATION.md file, linked directly in the README, contains the full list of environment variables, their accepted values, and examples for different deployment scenarios. The README describes this as approximately 37,000 characters of documentation, exceeding the DockerHub README limit, which is why the README itself is a placeholder.

The change.log at the repository root documents the history of changes. The build_version.txt file records the current container version.

The licence is not identified in the repository metadata; the README does not state a licence. Users should check the repository directly for any LICENCE or LICENSE file before redistribution.

Comparable Alternatives and When to Use Them

The upstream iCloud Photos Downloader (icloudpd) runs without Docker as a Python command-line tool. It covers the core download functionality without the Telegram re-authentication, HEIC conversion, Nextcloud sync, or multi-notification features that this container adds. Choosing the bare utility makes sense for users who want minimal dependencies and are comfortable writing their own shell scripts around it.

For users on Synology NAS, DSM's built-in Cloud Sync application can sync iCloud Drive (documents, not photos) directly through the Synology interface without Docker. It does not handle the full iCloud photo library and also does not support ADP. The distinction matters: this container targets the iCloud photo library specifically, not just iCloud Drive.

Deploying docker-icloudpd on an Unraid, Portainer, or Synology Container Manager installation follows the Docker Compose examples in the docker-compose/ directory. Those examples are referenced in the README as the intended starting point for self-hosted deployments.

Editorial conclusion

docker-icloudpd is a practical solution for households with multiple Apple devices that need a centralised, automated photo backup to a local server. It is the only documented approach for syncing multiple iCloud accounts to a single location using a container. The Telegram bot integration makes re-authentication manageable without SSH access, which matters for long-running home server deployments. The hard requirement to disable Apple's Advanced Data Protection before the container can authenticate is a significant security tradeoff that every user must evaluate before deployment. Full configuration is in CONFIGURATION.md, not the README. The last push was on 2026-09-06.

Frequently asked questions

Official sources

1. boredazfcuk/docker-icloudpd on GitHub
2. Issues
3. README