Jugando con Docker: iCloud Photo Library

¿Por qué necesitas esto?

Llevas años usando iCloud para almacenar tus fotos y vídeos. El problema es que Apple no ofrece una forma directa ni automatizada de descargar toda tu biblioteca a un servidor propio o NAS.

Puedes hacerlo manualmente desde iCloud.com (seleccionando 1.000 archivos cada vez) o tener un Mac con la biblioteca en local, pero si usas Linux, tienes un NAS o simplemente quieres una copia de seguridad automática, necesitas otra solución.

Ahí entra iCloud Photos Downloader (icloudpd), una herramienta open source que hace exactamente eso: descarga y sincroniza tus fotos y vídeos de iCloud al almacenamiento que tú elijas.

¿Qué es icloudpd hoy?

iCloud Photos Downloader es un proyecto open source con más de 11.600 estrellas en GitHub, licencia MIT y desarrollo activo (la versión actual es la v1.32.2). Está disponible como:

• Ejecutable directo para Windows, macOS y Linux
• Imagen Docker multi-arquitectura (AMD64, ARM64, ARM32v7)
• Paquete Python (pip), AUR (Arch Linux) y npm

Soporta tres modos de funcionamiento:

• Copy — descarga las fotos nuevas de iCloud (modo por defecto)
• Sync — descarga nuevas y elimina locales las que borraste en iCloud (–auto-delete)
• Move — descarga y borra las originales de iCloud (–keep-icloud-recent-days)

Además, maneja Live Photos (imagen + vídeo como archivos separados), RAW (incluyendo RAW+JPEG), deduplicación automática y metadatos EXIF.

Requisitos previos (importante)

Apple ha puesto más restricciones en los últimos años. Para que icloudpd funcione, tu cuenta de iCloud debe tener esta configuración:

1. Activar «Access iCloud Data on the Web»: En tu iPhone/iPad, ve a Ajustes > tu nombre > iCloud > Access iCloud Data on the Web y actívalo.
2. Desactivar «Advanced Data Protection»: En Ajustes > tu nombre > iCloud > Advanced Data Protection, asegúrate de que está desactivado.

Sin estos dos pasos, Apple devuelve un error ACCESS_DENIED y no podrás descargar nada.

Paso a paso con Docker

Vamos a montar un contenedor Docker con icloudpd que descargará toda tu biblioteca de fotos. A diferencia del artículo original, usaremos docker-compose para mantener la configuración ordenada y reutilizable.

1. Crear la estructura de directorios

mkdir -p /opt/icloudpd/data /opt/icloudpd/cookies
cd /opt/icloudpd

2. Crear el archivo docker-compose.yml

version: '3'
services:
  icloudpd:
    image: icloudpd/icloudpd:latest
    container_name: icloudpd
    restart: unless-stopped
    environment:
      - TZ=Europe/Madrid
    volumes:
      - ./data:/data
      - ./cookies:/cookies
    stdin_open: true
    tty: true

3. Arrancar el contenedor

docker-compose up -d

4. Entrar en el contenedor

docker exec -it icloudpd /bin/sh

5. Autenticarse en iCloud

Una vez dentro del contenedor, ejecuta:

icloud --username [email protected]

Te pedirá la contraseña. Si tienes activada la autenticación en dos pasos (recomendado), te pedirá un código que llegará a tus dispositivos Apple. Las cookies de sesión se almacenan en el directorio /cookies y duran aproximadamente dos meses.

6. Descargar las fotos

icloudpd --directory /data \
  --cookie-directory /cookies \
  --folder-structure {:%Y/%Y-%m-%d} \
  --username [email protected] \
  --password tucontraseña \
  --size original

Explicación de las opciones:

• --directory: dónde se guardarán las fotos
• --cookie-directory: donde se almacenan las cookies de sesión
• --folder-structure: estructura de carpetas (en este ejemplo: /Año/Año-mes-día)
• --size original: descarga los archivos en calidad original
• --auto-delete: (opcional) si borras una foto en iCloud, también se borra localmente

7. Sincronización automática

Para mantener la copia actualizada automáticamente, usa la opción –watch-with-interval. Esta opción hace que el contenedor se quede en segundo plano comprobando cada cierto tiempo si hay fotos nuevas:

icloudpd --directory /data \
  --cookie-directory /cookies \
  --folder-structure {:%Y/%Y-%m-%d} \
  --username [email protected] \
  --password tucontraseña \
  --size original \
  --watch-with-interval 3600

El valor 3600 son los segundos entre comprobaciones (1 hora). Puedes ajustarlo a tu gusto.

Alternativa: sincronización con docker-icloudpd

Existe una imagen alternativa muy popular: boredazfcuk/docker-icloudpd. Está basada en Alpine Linux e incluye funcionalidades extra como:

• Conversión HEIC a JPG
• Notificaciones por Telegram, Pushover, Discord, etc.
• Gestión automática del keyring del sistema

Es ideal si quieres una solución más «fire and forget».

Más opciones útiles

El comando icloudpd tiene muchas opciones. Estas son las más prácticas:

Opción	Qué hace
--auto-delete	Borra locales las fotos eliminadas en iCloud (modo sync)
--until-found 50	Para de buscar cuando encuentra 50 archivos seguidos ya descargados (acelera ejecuciones repetidas)
--recent 500	Descarga solo las últimas 500 fotos
--set-exif-datetime	Actualiza los metadatos EXIF con la fecha de la foto
--keep-icloud-recent-days 30	Mantiene en iCloud solo los últimos 30 días (modo move)
--watch-with-interval 3600	Monitoreo continuo, comprueba cada hora

Para ver todas las opciones: icloudpd --help

Más información

• Repositorio oficial en GitHub
• Documentación completa
• Imagen Docker oficial
• Imagen Docker alternativa (boredazfcuk)

¿Y ahora qué?

Este artículo forma parte de la serie «Jugando con Docker». Si te ha sido útil, te recomiendo el resto de artículos:

• Tecnología Docker para tu Empresa — Introducción a Docker
• Bitwarden con Vaultwarden 🔐
• Proxy inverso con Caddy 🌐
• Monitorización con Uptime Kuma 📊

¿Tienes un NAS y quieres automatizar las copias de iCloud? ¿Usas alguna otra herramienta? Cuéntalo en los comentarios.