How the docker-icloudpd Health Check Detects Cookie Expiration and Download Failures

The docker-icloudpd health check evaluates exit code files, error logs, and authentication cookie expiration dates in /healthcheck.sh to determine container health status.

The boredazfcuk/docker-icloudpd container automates iCloud photo downloads, but automated sync requires reliable failure detection. The health check mechanism monitors both operational failures (download errors) and authentication state (cookie validity) to enable Docker's auto-heal capabilities or orchestrator restarts when intervention is required.

How the Health Check Script Works

The health monitoring logic resides entirely in /healthcheck.sh. This script performs a sequential validation of three independent failure modes: sync process exit codes, error file presence, and authentication cookie status. If any check fails, the script exits with a non-zero status, signaling Docker to mark the container as unhealthy.

Detecting Download and Sync Failures

The health check identifies download and verification failures by monitoring files written by the main sync script (sync-icloud.sh).

Exit Code Monitoring

The script checks for exit code files in /tmp/icloudpd/ to determine if the last download or check operation succeeded:

if [ -f "/tmp/icloudpd/icloudpd_download_exit_code" ]; then
    download_exit_code="$(cat /tmp/icloudpd/icloudpd_download_exit_code)"
    if [ "${download_exit_code:=0}" -ne 0 ]; then
        echo "File download error: ${download_exit_code}"
        exit "${download_exit_code}"
    fi
fi

A similar block checks icloudpd_check_exit_code for verification failures. When these files contain non-zero values, the health check propagates that exit code to Docker.

Error File Detection

Even when exit codes are zero, the health check scans for error report files:

if [ -f "/tmp/icloudpd/icloudpd_download_error" ]; then
    if [ -s "/tmp/icloudpd/icloudpd_download_error" ]; then
        echo "Errors reported during download"
        exit 1
    fi
fi

Non-empty error files in /tmp/icloudpd/icloudpd_download_error or /tmp/icloudpd/icloudpd_check_error trigger an immediate unhealthy status.

Validating Authentication Cookie Expiration

The health check prevents silent authentication failures by parsing the Apple ID cookie file to verify it exists and has not expired.

Cookie Existence Checks

The script first verifies the cookie file exists at /config/${cookie} (where ${cookie} is derived from the sanitized Apple ID). If missing, it exits with:

Error: Cookie does not exist...

Parsing Expiration Dates for MFA and Web Auth

For MFA authentication (authentication_type=MFA), the script extracts the X-APPLE-DS-WEB-SESSION-TOKEN cookie and parses its expires attribute:

mfa_expire_date="$(grep "X-APPLE-DS-WEB-SESSION-TOKEN" "/config/${cookie}" \
                  | sed -e 's#.*expires="\(.*\)Z"; HttpOnly.*#\1#')"
mfa_expire_seconds="$(date -d "${mfa_expire_date}" '+%s')"
days_remaining=$(( (mfa_expire_seconds - $(date '+%s')) / 86400 ))

For Web authentication (authentication_type=Web), it performs the same logic on X_APPLE_WEB_KB.

The script compares days_remaining against notification_days (default 7):

• If days remaining ≤ 0: Prints "Error: ... cookie has expired" and exits 1
• If days remaining ≤ notification_days: Prints warning about impending expiration
• Otherwise: Reports healthy status with days remaining

Configuring the Health Check in Docker

To utilize the health check in your deployment, ensure your Docker Compose or run command references the script:

services:
  icloudpd:
    image: ghcr.io/boredazfcuk/docker-icloudpd:latest
    healthcheck:
      test: [ "CMD", "/healthcheck.sh" ]
      interval: 5m
      timeout: 10s
      retries: 3
    volumes:
      - ./config:/config
      - ./tmp:/tmp/icloudpd

You can manually verify health status by executing:

docker exec -it <container_name> /healthcheck.sh

Summary

• The docker-icloudpd health check runs /healthcheck.sh to monitor container viability through three distinct validation layers.
• Download failures are detected by reading exit code files (/tmp/icloudpd/icloudpd_download_exit_code) and error report files in the same directory.
• Cookie expiration is determined by parsing the expires attribute from X-APPLE-DS-WEB-SESSION-TOKEN (MFA) or X_APPLE_WEB_KB (Web) cookies and calculating days remaining against the notification_days threshold.
• When any check fails, the script exits non-zero, causing Docker to mark the container unhealthy and trigger restart policies or alerts.

Frequently Asked Questions

How often does the docker-icloudpd health check run?

By default, the health check interval depends on your Docker configuration. The example configuration uses a 5-minute interval with 3 retries, meaning Docker runs /healthcheck.sh every 5 minutes and allows up to 3 failures before marking the container unhealthy. You can adjust the interval, timeout, and retries values in your Docker Compose healthcheck definition to match your monitoring requirements.

What happens when the iCloud cookie expires?

When the health check detects that the cookie has expired (days remaining ≤ 0), it prints an error message such as "Error: Multi-factor authentication cookie has expired" and exits with status code 1. This causes Docker to mark the container as unhealthy. If you have configured an auto-heal container or restart policy, Docker will attempt to restart the container, but the download will not resume until you manually re-authenticate to generate a fresh cookie file in /config/.

Can the health check detect partial download failures?

Yes, the health check can detect partial failures through the error file mechanism. Even if the download process exits with code 0, if sync-icloud.sh writes any content to /tmp/icloudpd/icloudpd_download_error, the health check will detect the non-empty file and exit with status 1, marking the container unhealthy. This ensures that logging errors or partial sync issues trigger alerts even when the process technically completes.

Where are the health check files located inside the container?

The health check script itself resides at /healthcheck.sh in the container root. The state files it monitors are located in /tmp/icloudpd/ (exit codes and error files), while the authentication cookie is stored in /config/ with a filename derived from your sanitized Apple ID. When mapping volumes, ensure you persist both /config for the cookie and /tmp/icloudpd if you need to inspect exit codes or error logs from the host system.

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