iCloud-docker
🤟 Please star this repository if you end up using this project. If it has improved your life in any way, consider donating to my mission using 'Sponsor' or 'Buy Me a Coffee' button. It will help me to continue supporting this product. :pray:
iCloud-docker (previously known as iCloud-drive-docker) is a simple iCloud client in Docker environment. It uses iCloudPy python library to interact with iCloud server.
For developers and AI agents: This project uses OpenCode with AGENTS.md for agent instructions. See docs/index.md for architecture documentation and AGENTS.md for build/test commands.
Primary use case of iCloud-docker is to periodically sync wanted or all of your iCloud drive, photos using your iCloud username and password.
Please note that this application only downloads the files from server. It does not upload the local files to the server (yet).
Installation
Installation using Docker Hub
docker run --name icloud \
-v ${PWD}/icloud:/icloud \
-v ${PWD}/config:/config \
-e ENV_CONFIG_FILE_PATH=/config/config.yaml \
-p 8080:8080 \
mandarons/icloud-drive
The -p 8080:8080 flag exposes the optional web UI. Remove it if you
are not enabling app.web_ui.enabled in config.yaml.
Installation using docker-compose
services:
icloud:
image: mandarons/icloud-drive
environment:
- PUID=<insert the output of `id -u $user`>
- PGID=<insert the output of `id -g $user`>
env_file:
- .env.icloud # Must contain ENV_CONFIG_FILE_PATH=/config/config.yaml and optionally, ENV_ICLOUD_PASSWORD=<password>
container_name: icloud
restart: unless-stopped
ports:
- "8080:8080" # Web UI — remove if not using app.web_ui.enabled
volumes:
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
- ${PWD}/icloud:/icloud
- ${PWD}/config:/config # Must contain config.yaml
Authentication (required after container creation or authentication expiration)
# Login manually if ENV_ICLOUD_PASSWORD is not specified and/or 2FA is required
docker exec -it icloud /bin/sh -c "su-exec abc icloud --username=<icloud-username> --session-directory=/config/session_data"
For China server users, please add --region=china as follows:
# Login manually if ENV_ICLOUD_PASSWORD is not specified and/or 2FA is required
docker exec -it icloud /bin/sh -c "su-exec abc icloud --username=<icloud-username> --region=china --session-directory=/config/session_data"
Follow the steps to authenticate.
Two ways to run unattended
The container can keep syncing with or without an Apple ID password on disk. Both run unattended; they differ in what happens months later.
Password stored (ENV_ICLOUD_PASSWORD, or answering yes to icloud's "Save password in keyring?" prompt) — indefinite unattended operation. When Apple's trusted session lapses the container signs in again by itself and only needs a human for the second factor. The cost is the credential at rest: on a headless host Python's keyring resolves to keyrings.alt.file.PlaintextKeyring, so the password sits in cleartext in /config/python_keyring/keyring_pass.cfg. That is an Apple ID password, which also reaches Find My, iCloud backups, purchases and account recovery.
No password — unattended until Apple's trust window closes, then a human signs in once. With no password configured the container resumes the saved session in /config/session_data and never attempts a credential sign-in. Nothing derived from your password is written to disk. When the session stops being accepted, sync stops with No Apple ID password is stored and the saved session is no longer valid …, sends the usual 2FA notification and waits retry_login_interval between attempts; set app.trust_expiry_warn_days so the warning arrives before that, not after. How often that happens is Apple's call, not a documented interval — app.trust_refresh_days rolls the window forward while the session is healthy, which should make it rare, though that refresh has not been verified against Apple over a full trust lifetime in this mode.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
