How to Use Single Pass Mode with Cron for Scheduled Synchronization in docker-icloudpd

Enable single_pass=true in /config/icloudpd.conf, set the Docker restart policy to no, and invoke the container via host cron to run one synchronization cycle and exit.

The boredazfcuk/docker-icloudpd container runs continuously by default, polling for new iCloud photos at configured intervals. By activating single pass mode with cron for scheduled synchronization, you transform the container into an ephemeral task that performs one sync and terminates, allowing precise control over execution timing via the host's cron daemon.

Understanding Single Pass Mode in docker-icloudpd

In standard operation, the container daemonizes indefinitely, sleeping between downloads according to the download_interval setting. Single pass mode disables this persistence, making the container suitable for external schedulers.

Core Implementation in sync-icloud.sh

According to the source code in sync-icloud.sh (lines 100-108), the script evaluates the single_pass configuration variable during initialization. When set to true, the script assigns skip_check=true, which bypasses the periodic download-check loop and allows the process to terminate after completing the initial synchronization cycle.

Configuring Single Pass Mode

Setting up single pass mode requires two distinct configuration changes: one internal to the container's configuration and one in the container runtime parameters.

Step 1 – Enable single_pass in icloudpd.conf

Set the single_pass variable to true in your /config/icloudpd.conf file. When this flag is active, the download_interval setting becomes irrelevant because the container exits immediately after the first sync completes.

# /config/icloudpd.conf

single_pass=true          # Exit after one synchronisation

download_interval=60      # Ignored when single_pass is enabled

apple_id=user@example.com

Step 2 – Set Docker Restart Policy to "no"

As documented in CONFIGURATION.md (lines 106-107), you must override the default restart behavior. The docker-compose/docker-compose.example.yml (lines 30-31) specifies restart: always by default, which must be changed to "no" for single pass usage. Without this change, Docker immediately restarts the container upon exit, potentially flooding Apple's authentication servers with requests.

# docker-compose.yml

services:
  icloudpd:
    image: boredazfcuk/icloudpd
    restart: "no"                     # Required for single-pass mode

    environment:
      - TZ=Europe/London
    volumes:
      - icloudpd_config:/config
      - ./photos:/home/user/iCloud/

Scheduling with Cron

With the container configured to exit after a single run, use the host system's cron daemon to trigger synchronizations at specific times.

Docker Run Method

Use docker run --rm in your crontab to create an ephemeral container that is automatically removed after exit. Explicitly include --restart=no to ensure Docker does not respawn the container.

30 2 * * *  /usr/bin/docker run --rm \
    --name icloudpd_sync \
    --restart=no \
    -v icloudpd_config:/config \
    -v /srv/photos/iCloud:/home/user/iCloud \
    -e TZ=Europe/London \
    boredazfcuk/icloudpd

Docker Compose Alternative

If you manage the container with Docker Compose, use the run subcommand with the --rm flag. This executes a one-off container that inherits the restart: "no" setting from your compose file.

0 */6 * * *  cd /opt/icloudpd && \
    /usr/bin/docker compose run --rm --no-deps icloudpd

The --no-deps flag ensures only the icloudpd service runs without spawning dependent containers, while --rm cleans up the container after the single synchronization completes.

Summary

• Set single_pass=true in /config/icloudpd.conf to disable the continuous execution loop in sync-icloud.sh
• Configure Docker with restart: "no" to prevent automatic container respawning after single-pass exit
• Use host cron with docker run --rm or docker compose run --rm to schedule ephemeral synchronization jobs
• This architecture prevents resource waste and avoids excessive authentication requests to Apple's servers

Frequently Asked Questions

What happens if I don't set the Docker restart policy to "no"?

If the restart policy remains set to always or unless-stopped, Docker immediately restarts the container when single pass mode exits. This creates a rapid restart loop that continuously authenticates with Apple's servers, potentially triggering rate limits or account restrictions as noted in the project documentation.

Does single_pass mode ignore the download_interval setting?

Yes. When single_pass=true is configured, the download_interval variable is ignored because sync-icloud.sh sets skip_check=true and exits after the first synchronization cycle rather than entering the sleep loop defined for continuous operation.

Can I use single pass mode with Kubernetes CronJobs?

Yes. Single pass mode is ideal for Kubernetes CronJobs. Configure your Job template with restartPolicy: Never (equivalent to Docker's no) and mount a configuration file with single_pass=true. The container runs once per scheduled Job execution and exits cleanly without lingering pods.

Where does the container check the single_pass configuration?

The container reads the single_pass variable from /config/icloudpd.conf during the initialization phase. This value is processed in sync-icloud.sh between lines 100-108, where it determines whether to set the skip_check internal flag that controls the main execution loop's persistence.

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