How to Safely Configure Auto-Delete and keep_icloud_recent Features in docker-icloudpd

Enable auto_delete and keep_icloud_recent_only by setting them to true in your .env file, define keep_icloud_recent_days as an integer, and acknowledge the safety warnings by setting warnings_acknowledged=true to proceed past the mandatory two-minute pause.

The docker-icloudpd container wraps the iCloud Photo Downloader (icloudpd) binary in a controlled environment where destructive operations require explicit configuration. Understanding how environment variables translate into command-line flags is essential before enabling features that permanently delete photos from your iCloud account.

Understanding the Configuration Pipeline

docker-icloudpd orchestrates synchronization through three shell scripts that read your environment variables, enforce safety checks, and construct the final icloudpd command. The pipeline flows from .env file definitions through validation to command execution.

Variable Definitions in init_config.sh

The file init_config.sh declares all user-configurable variables at container startup. According to the source code, lines 13-15 define the parameters controlling deletion behavior:

• auto_delete – Boolean flag that defaults to false. When enabled, the container removes photos from iCloud that are no longer present in your local download directory.
• keep_icloud_recent_only – Boolean flag that enables retention mode, keeping only a specified number of recent days in iCloud.
• keep_icloud_recent_days – Integer value representing the number of days to retain. This parameter is only evaluated when keep_icloud_recent_only is set to true.

These variables are sourced from /config/.env or passed directly through Docker environment parameters.

Command-Line Construction in sync-icloud.sh

The sync-icloud.sh script translates your environment variables into icloudpd binary flags during the synchronization phase. At lines 2199-2202, the script checks the auto_delete variable:

# When auto_delete is not false, append the flag

if [ "${auto_delete}" != false ]; then
   command_line+=" --auto-delete"
fi

For the recent-only retention policy, lines 2206-2209 implement the logic:

# If keep_icloud_recent_only is true and days are specified

if [ "${keep_icloud_recent_only}" = true ] && [ -n "${keep_icloud_recent_days}" ]; then
   command_line+=" --keep-icloud-recent-days ${keep_icloud_recent_days}"
fi

Safety Mechanisms and Mandatory Warnings

Before executing any destructive operation, launcher.sh implements a critical safety checkpoint. Lines 30-35 of this file contain warning text explaining that the "Keep iCloud recent" feature deletes all files older than the specified day count from iCloud entirely.

By default, the container enforces a two-minute pause upon startup when dangerous options are detected. This delay provides a window to abort the container (Ctrl-C) if configuration errors are discovered. To proceed past this pause, you must explicitly set warnings_acknowledged=true in your environment file.

Configuration Examples

The following snippets demonstrate practical implementations. Always start with warnings_acknowledged=false during initial testing to verify your configuration.

Enable Auto-Delete Only

This configuration removes photos from iCloud after confirming they exist locally:

# .env configuration

auto_delete=true
warnings_acknowledged=false

Result: sync-icloud.sh appends --auto-delete to the icloudpd command, but no retention date filtering occurs.

Retain Only Recent Photos

To keep only the last 30 days of photos in iCloud while removing older content:

# .env configuration

keep_icloud_recent_only=true
keep_icloud_recent_days=30
warnings_acknowledged=false

Result: The script adds --keep-icloud-recent-days 30 to the command line after displaying the mandatory warning in launcher.sh.

Combined Configuration (High Risk)

Warning: This example demonstrates both features active simultaneously. Testing in a non-production environment is mandatory.

# .env configuration - USE WITH EXTREME CAUTION

auto_delete=true
keep_icloud_recent_only=true
keep_icloud_recent_days=0
warnings_acknowledged=true

Result: This deletes all photos not present locally via --auto-delete, then removes everything older than 0 days via --keep-icloud_recent_days, effectively wiping the entire iCloud photo library.

Docker Compose Implementation

Mount your configuration file and pass variables through the environment section:

# docker-compose.yml

services:
  icloudpd:
    image: ghcr.io/boredazfcuk/docker-icloudpd:latest
    container_name: icloudpd
    restart: unless-stopped
    environment:
      - AUTO_DELETE=true
      - KEEP_ICLOUD_RECENT_ONLY=true
      - KEEP_ICLOUD_RECENT_DAYS=7
      - WARNINGS_ACKNOWLEDGED=true
    volumes:
      - ./config:/config
      - ./photos:/photos

The environment keys map directly to the variables processed by init_config.sh.

Critical Safety Considerations

Both --auto-delete and --keep-icloud-recent-days perform irreversible deletions from your iCloud account. Unlike local file operations, these changes sync immediately across all Apple devices linked to the account.

Setting keep_icloud_recent_days=0 triggers immediate deletion of your entire iCloud photo library, as zero days satisfies the "older than" condition for all existing photos. Always verify your download integrity and backup strategy before enabling warnings_acknowledged=true.

Summary

• Configuration File: init_config.sh (lines 13-15) defines auto_delete, keep_icloud_recent_only, and keep_icloud_recent_days variables.
• Command Building: sync-icloud.sh translates these into --auto-delete (lines 2199-2202) and --keep-icloud-recent-days (lines 2206-2209) flags.
• Safety Pause: launcher.sh (lines 30-35) enforces a two-minute warning period unless warnings_acknowledged=true is set.
• Data Risk: Both features permanently remove photos from iCloud; keep_icloud_recent_days=0 deletes the entire library.

Frequently Asked Questions

What happens if I set keep_icloud_recent_days to 0?

Setting this value to 0 configures icloudpd to delete all photos older than 0 days, which encompasses your entire iCloud photo library. According to the implementation in sync-icloud.sh, this value passes directly to the --keep-icloud-recent-days flag without minimum threshold validation, resulting in complete data loss if keep_icloud_recent_only is enabled.

Why does the container pause for two minutes on startup?

The pause occurs in launcher.sh when dangerous deletion features are detected and warnings_acknowledged is not set to true. This two-minute window allows you to interrupt the container with Ctrl-C if you discover a configuration error that would cause unintended photo deletion. The warning text explicitly states that the "Keep iCloud recent" feature deletes files permanently from iCloud.

Can I use auto-delete without keep_icloud_recent_only?

Yes. These features operate independently. Setting auto_delete=true without keep_icloud_recent_only results in only the --auto-delete flag being appended to the command line (as implemented at lines 2199-2202 of sync-icloud.sh). This removes photos from iCloud only after they have been successfully downloaded and are present in your local directory, without applying any date-based retention logic.

Where do I place the .env file in a Docker Compose setup?

The container expects environment variables at /config/.env inside the filesystem. In your docker-compose.yml, mount a host directory containing the .env file to /config, or define the variables directly in the environment: section. The init_config.sh script reads this location during container initialization to populate the runtime configuration.

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