PhotoPrism Docker Compose: Gestiona tus Fotos con IA 2025

¿Buscas una alternativa privada y potente a Google Photos? PhotoPrism Docker Compose es la solución definitiva para gestionar tu biblioteca fotográfica con inteligencia artificial, reconocimiento facial y búsqueda avanzada, todo ejecutándose en tu propio servidor. Con más de 38.800 estrellas en GitHub, esta aplicación self-hosted se ha convertido en la opción preferida por miles de usuarios que valoran su privacidad y el control total sobre sus recuerdos.

En esta guía completa aprenderás a desplegar PhotoPrism utilizando Docker Compose, configurar todas las funcionalidades de IA, optimizar el rendimiento y comenzar a organizar miles de fotografías en minutos.

Qué es PhotoPrism Docker Compose y Por Qué Elegirlo

PhotoPrism es una aplicación de gestión fotográfica impulsada por inteligencia artificial que te permite organizar, buscar y compartir tus fotos de manera privada y segura. A diferencia de soluciones cloud como Google Photos o iCloud, esta aplicación se ejecuta completamente en tu infraestructura, garantizando privacidad absoluta.

Las características principales que hacen única a esta solución incluyen:

• Reconocimiento facial automático mediante TensorFlow que identifica personas en tus fotografías
• Etiquetado inteligente basado en contenido y ubicación geográfica
• Búsqueda avanzada por etiquetas, localización, resolución, color y calidad
• Soporte multi-formato incluyendo RAW, HEIC/HEIF, videos y panoramas
• Mapas interactivos con seis mapas mundiales de alta resolución
• Geocodificación inversa que convierte coordenadas GPS en nombres de lugares
• Progressive Web App que funciona en teléfonos, tablets y escritorios
• Sincronización WebDAV compatible con Windows Explorer, Apple Finder, iOS y Android

El proyecto es de código abierto bajo licencia AGPL 3.0, está programado principalmente en Go (80%), y cuenta con una comunidad activa de más de 185 contribuidores. La arquitectura basada en contenedores facilita enormemente el despliegue y mantenimiento.

Requisitos del Sistema para PhotoPrism Docker Compose

Antes de instalar este gestor fotográfico, es fundamental verificar que tu servidor cumple con los requisitos mínimos de hardware y software.

Requisitos de Hardware

• CPU: Mínimo 2 núcleos (4 núcleos recomendado para bibliotecas grandes)
• RAM: Mínimo 4 GB de memoria física con al menos 4 GB de swap configurado
• Almacenamiento: SSD altamente recomendado para base de datos y cachés (el rendimiento mejora significativamente)
• Espacio en disco: Depende del tamaño de tu biblioteca fotográfica más espacio adicional para thumbnails y cachés
• Arquitectura: Soporte para x86_64, ARM64 y Raspberry Pi

La documentación oficial enfatiza que nunca debes almacenar archivos de base de datos en dispositivos poco fiables como memorias USB o tarjetas SD, ya que esto puede corromper tus datos.

Requisitos de Software

• Docker Engine: Versión 20.10 o superior
• Docker Compose: Versión 2.0 o superior (nota: ya no es necesario especificar el campo version en archivos compose)
• Sistema Operativo: Linux (Ubuntu, Debian, CentOS), macOS, Windows con WSL2
• Podman Compose: Soportado como alternativa en distribuciones Red Hat

Importante: Los módulos de seguridad del kernel como AppArmor y SELinux pueden causar problemas. Si encuentras errores de permisos, considera ajustar las políticas de seguridad.

Instalación Paso a Paso de PhotoPrism Docker Compose

El proceso de instalación es directo y puede completarse en menos de 10 minutos siguiendo estos pasos detallados.

Paso 1: Crear Estructura de Directorios

Primero, crea los directorios necesarios para almacenar tus fotografías originales, configuración y base de datos:

mkdir -p ~/photoprism/{originals,storage,database}
cd ~/photoprism

Paso 2: Descargar Archivo Docker Compose

Descarga el archivo de configuración oficial para tu plataforma:

wget https://dl.photoprism.app/docker/compose.yaml

Para Raspberry Pi o arquitecturas ARM64, descarga la versión específica para ARM desde la documentación oficial.

Paso 3: Configurar Docker Compose YAML

Aquí está la configuración completa y optimizada que puedes usar directamente:

services:
  photoprism:
    image: photoprism/photoprism:latest
    container_name: photoprism
    restart: unless-stopped
    stop_grace_period: 10s
    depends_on:
      - mariadb
    security_opt:
      - seccomp:unconfined
      - apparmor:unconfined
    ports:
      - "2342:2342"
    environment:
      PHOTOPRISM_ADMIN_USER: "admin"
      PHOTOPRISM_ADMIN_PASSWORD: "TuContraseñaSegura123"  # CAMBIAR OBLIGATORIO
      PHOTOPRISM_AUTH_MODE: "password"
      PHOTOPRISM_SITE_URL: "http://localhost:2342/"
      PHOTOPRISM_DISABLE_TLS: "false"
      PHOTOPRISM_DEFAULT_TLS: "true"
      PHOTOPRISM_ORIGINALS_LIMIT: 5000
      PHOTOPRISM_HTTP_COMPRESSION: "gzip"
      PHOTOPRISM_LOG_LEVEL: "info"
      PHOTOPRISM_READONLY: "false"
      PHOTOPRISM_EXPERIMENTAL: "false"
      PHOTOPRISM_DISABLE_CHOWN: "false"
      PHOTOPRISM_DISABLE_WEBDAV: "false"
      PHOTOPRISM_DISABLE_SETTINGS: "false"
      PHOTOPRISM_DISABLE_TENSORFLOW: "false"
      PHOTOPRISM_DISABLE_FACES: "false"
      PHOTOPRISM_DISABLE_CLASSIFICATION: "false"
      PHOTOPRISM_DISABLE_VECTORS: "false"
      PHOTOPRISM_DISABLE_RAW: "false"
      PHOTOPRISM_RAW_PRESETS: "false"
      PHOTOPRISM_JPEG_QUALITY: 85
      PHOTOPRISM_DETECT_NSFW: "false"
      PHOTOPRISM_UPLOAD_NSFW: "true"
      PHOTOPRISM_DATABASE_DRIVER: "mysql"
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"
      PHOTOPRISM_DATABASE_NAME: "photoprism"
      PHOTOPRISM_DATABASE_USER: "photoprism"
      PHOTOPRISM_DATABASE_PASSWORD: "contraseña_db_segura"  # CAMBIAR OBLIGATORIO
      PHOTOPRISM_SITE_CAPTION: "AI-Powered Photos App"
      PHOTOPRISM_SITE_DESCRIPTION: ""
      PHOTOPRISM_SITE_AUTHOR: ""
    working_dir: "/photoprism"
    volumes:
      - "./originals:/photoprism/originals"
      - "./storage:/photoprism/storage"

  mariadb:
    image: mariadb:11
    container_name: photoprism_mariadb
    restart: unless-stopped
    stop_grace_period: 5s
    security_opt:
      - seccomp:unconfined
      - apparmor:unconfined
    command: >
      --innodb-buffer-pool-size=512M
      --transaction-isolation=READ-COMMITTED
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci
      --max-connections=512
      --innodb-rollback-on-timeout=OFF
      --innodb-lock-wait-timeout=120
    volumes:
      - "./database:/var/lib/mysql"
    environment:
      MARIADB_AUTO_UPGRADE: "1"
      MARIADB_INITDB_SKIP_TZINFO: "1"
      MARIADB_DATABASE: "photoprism"
      MARIADB_USER: "photoprism"
      MARIADB_PASSWORD: "contraseña_db_segura"  # MISMO QUE ARRIBA
      MARIADB_ROOT_PASSWORD: "root_password_segura"  # CAMBIAR OBLIGATORIO

Importante: Siempre debes cambiar PHOTOPRISM_ADMIN_PASSWORD antes del primer inicio. Esta contraseña debe tener mínimo 8 caracteres y no puede cambiarse posteriormente mediante variable de entorno (solo vía comando CLI).

Paso 4: Iniciar los Servicios

Ejecuta el siguiente comando para iniciar la aplicación en segundo plano:

docker compose up -d

Este comando descargará las imágenes necesarias (aproximadamente 1-2 GB), creará los contenedores y los iniciará automáticamente. El primer inicio puede tardar algunos minutos mientras se inicializa la base de datos MariaDB.

Paso 5: Verificar los Logs

Verifica que todo esté funcionando correctamente con:

docker compose logs -f --tail=100

Busca mensajes que confirmen que el servidor web está escuchando en el puerto 2342 y que la conexión con MariaDB se estableció correctamente.

Paso 6: Acceder a la Interfaz Web

Abre tu navegador y accede a http://localhost:2342 (o la IP de tu servidor). Inicia sesión con:

• Usuario: admin
• Contraseña: La que configuraste en PHOTOPRISM_ADMIN_PASSWORD

Configuración de Volúmenes PhotoPrism Docker Compose

La correcta configuración de volúmenes es crítica para evitar pérdida de datos y optimizar el rendimiento.

Volumen Originals (Fotografías Originales)

El directorio /photoprism/originals almacena tus fotos y videos originales. Puedes:

• Montar múltiples subdirectorios desde diferentes ubicaciones
• Activar modo solo lectura con PHOTOPRISM_READONLY: "true" para evitar modificaciones accidentales
• Usar rutas absolutas (nunca relativas) para evitar problemas de montaje

Ejemplo con múltiples directorios:

volumes:
  - "/mnt/nas/photos:/photoprism/originals/nas"
  - "/home/user/Pictures:/photoprism/originals/local"
  - "./storage:/photoprism/storage"

Volumen Storage (Configuración y Cachés)

El directorio /photoprism/storage es esencial y debe especificarse siempre. Contiene:

• Archivos de configuración de la aplicación
• Thumbnails generados automáticamente
• Cachés de procesamiento
• Metadatos indexados

Advertencia: La documentación oficial especifica que este volumen «debe especificarse siempre para no perder estos archivos tras un reinicio o actualización». Nunca anides este directorio dentro de originals.

Volumen Import (Opcional)

El directorio /photoprism/import es opcional pero recomendado para:

• Organizar automáticamente nuevas fotos por año/mes
• Prevenir archivos duplicados
• Facilitar importaciones masivas

Tampoco debe estar dentro del directorio originals.

Optimización de Rendimiento PhotoPrism Docker Compose

Para sistemas con recursos limitados o bibliotecas fotográficas enormes, estas optimizaciones marcan una diferencia significativa.

Ajustar Workers y Procesamiento

Reduce el número de workers si tienes poca RAM:

PHOTOPRISM_WORKERS: "2"  # Ajusta al número de núcleos CPU disponibles

Deshabilitar Funciones IA Selectivamente

Si el procesamiento con TensorFlow consume demasiados recursos:

PHOTOPRISM_DISABLE_TENSORFLOW: "true"    # Deshabilita clasificación IA
PHOTOPRISM_DISABLE_FACES: "true"         # Deshabilita reconocimiento facial
PHOTOPRISM_DISABLE_CLASSIFICATION: "true" # Deshabilita etiquetado automático

Nota: Deshabilitar estas funciones reduce significativamente la funcionalidad principal de la aplicación.

Optimizar MariaDB

Ajusta el buffer pool de MariaDB según tu RAM disponible:

command: >
  --innodb-buffer-pool-size=1G  # Aumenta si tienes >8GB RAM
  --transaction-isolation=READ-COMMITTED
  --character-set-server=utf8mb4

Para sistemas con 16GB+ de RAM, puedes aumentar a 2G o más para acelerar consultas complejas.

Evitar Límites de Memoria Duros

La documentación advierte contra establecer límites duros de memoria que puedan causar reinicios inesperados durante la indexación de bibliotecas grandes. Es mejor permitir que el sistema operativo gestione la memoria mediante swap.

Comandos Útiles para Gestionar PhotoPrism Docker Compose

Estos comandos CLI te ayudarán en el día a día:

Indexar y Actualizar Biblioteca

# Indexar nuevas fotos y limpiar entradas antiguas
docker compose exec photoprism photoprism index --cleanup

# Forzar re-indexación completa
docker compose exec photoprism photoprism index -f

Cambiar Contraseña de Admin

docker compose exec photoprism photoprism passwd admin

Backup de Base de Datos

docker compose exec photoprism photoprism backup -i -f

Reset Completo de Base de Datos

docker compose exec photoprism photoprism reset --yes

Advertencia: Este comando elimina toda la información indexada. Úsalo solo si necesitas empezar desde cero.

Ver Logs en Tiempo Real

docker compose logs -f --tail=100

Actualizar a Última Versión

docker compose pull
docker compose up -d

Funcionalidades Avanzadas de PhotoPrism

Más allá de la instalación básica, esta plataforma ofrece capacidades profesionales que rivalizan con soluciones comerciales.

Reconocimiento Facial con TensorFlow

La aplicación utiliza TensorFlow para identificar automáticamente rostros en tus fotos. Puedes asignar nombres a las personas detectadas y posteriormente buscar todas las fotos que contienen a alguien específico. El motor de IA mejora con el tiempo a medida que procesa más imágenes.

Mapas Interactivos y Geocodificación

Con seis mapas mundiales de alta resolución integrados, puedes visualizar dónde fueron tomadas tus fotografías. La geocodificación inversa convierte automáticamente las coordenadas GPS de tus fotos en nombres de lugares legibles como «París, Francia» o «Parque Nacional Yosemite».

A diferencia de otros servicios, PhotoPrism cubre completamente estos servicios de mapas sin depender de APIs externas con limitaciones de uso.

Búsqueda Avanzada Multi-Criterio

El motor de búsqueda soporta filtros combinados por:

• Etiquetas automáticas («playa», «montaña», «perro», etc.)
• Ubicación geográfica (ciudad, país, coordenadas)
• Resolución y calidad de imagen
• Color dominante
• Fecha y hora de captura
• Cámara y configuración EXIF
• Personas identificadas

Puedes combinar múltiples filtros para búsquedas extremadamente específicas como «fotos de María en la playa durante verano 2024».

Soporte RAW Profesional

Fotógrafos profesionales apreciarán el soporte completo para formatos RAW de todas las marcas principales (Canon CR2/CR3, Nikon NEF, Sony ARW, etc.). El servicio genera automáticamente previsualizaciones de alta calidad sin modificar los archivos originales.

Sincronización Multi-Dispositivo

El servidor WebDAV integrado permite sincronizar automáticamente fotos desde:

• iOS (mediante apps compatibles con WebDAV)
• Android (con aplicaciones de backup WebDAV)
• Windows Explorer (conexión directa WebDAV)
• Apple Finder (montaje de volumen de red)

Esto significa que puedes configurar backup automático desde tu smartphone exactamente como lo harías con Google Photos, pero manteniendo control total.

Solución de Problemas Comunes

Errores de Permisos

Si encuentras errores de permisos al acceder a directorios:

sudo chown -R 1000:1000 ~/photoprism/{originals,storage,database}

O ajusta PHOTOPRISM_DISABLE_CHOWN: "true" si gestionas permisos manualmente.

Contenedor No Inicia

Verifica que MariaDB esté completamente iniciada antes de que el servicio principal arranque. Aumenta el stop_grace_period si los contenedores se detienen abruptamente.

Indexación Lenta

Si la indexación de miles de fotos es extremadamente lenta:

• Verifica que usas SSD para storage y database
• Aumenta RAM disponible y workers
• Considera deshabilitar temporalmente clasificación IA para acelerar indexación inicial
• Revisa que no hay límites de memoria Docker causando throttling

Problemas con AppArmor/SELinux

Como menciona la documentación, estos módulos de seguridad pueden causar problemas. Si enfrentas errores inexplicables, prueba deshabilitarlos temporalmente o ajusta las políticas para permitir acceso a Docker.

Comparativa: PhotoPrism vs Alternativas

Para ayudarte a decidir si esta solución es adecuada para ti, aquí hay una comparación con otras opciones populares.

PhotoPrism vs Immich

Immich es otra excelente alternativa self-hosted a Google Photos. Mientras Immich se enfoca en simplicidad y experiencia móvil nativa, esta opción destaca por:

• Capacidades IA más maduras y precisas
• Mejor soporte para formatos RAW profesionales
• Mapas integrados sin dependencias externas
• Comunidad más establecida (38.8k vs 20k estrellas GitHub)

Immich gana en facilidad de uso inicial y apps móviles nativas.

PhotoPrism vs Nextcloud Photos

Nextcloud Photos es parte del ecosistema Nextcloud Docker Compose. La diferencia principal:

• Nextcloud es una suite completa (archivos, calendario, contactos)
• PhotoPrism es especializado exclusivamente en gestión fotográfica
• Reconocimiento facial y IA mucho más avanzados en PhotoPrism
• Nextcloud consume más recursos por ser multi-propósito

Si solo necesitas gestión de fotos, esta aplicación es superior. Si quieres una solución todo-en-uno, considera Nextcloud.

PhotoPrism vs Google Photos

• Privacidad: PhotoPrism gana absolutamente (todo en tu servidor)
• Costo: Google Photos cobra por almacenamiento ilimitado; PhotoPrism solo requiere tu hardware
• Funcionalidades IA: Google tiene ventaja en precisión de reconocimiento
• Facilidad: Google Photos es más simple de usar
• Control: PhotoPrism te da control total sobre tus datos

Casos de Uso Reales de PhotoPrism

Esta plataforma brilla en estos escenarios:

• Fotógrafos profesionales: Gestionar bibliotecas de 50,000+ fotos RAW con metadatos completos
• Familias preocupadas por privacidad: Compartir álbumes familiares sin depender de big tech
• Archivos históricos: Digitalizar y organizar colecciones de fotografías antiguas con geolocalización
• Organizaciones: Gestionar archivos fotográficos corporativos con control de acceso
• Entusiastas self-hosted: Complementar tu stack de servicios auto-hospedados

Preguntas Frecuentes sobre PhotoPrism Docker Compose

¿PhotoPrism es completamente gratuito?

Sí, el software es 100% gratuito y de código abierto bajo licencia AGPL 3.0. Existe una membresía PhotoPrism® Plus opcional que desbloquea mapas interactivos adicionales y soporte premium, pero todas las funcionalidades básicas son gratuitas permanentemente.

¿Puedo instalar PhotoPrism en Raspberry Pi?

Sí, existe soporte oficial para arquitecturas ARM64 incluyendo Raspberry Pi 4 y 5. Necesitarás al menos 4GB de RAM y se recomienda usar SSD externo en lugar de tarjeta SD para la base de datos. Descarga el archivo compose específico para ARM desde la documentación oficial.

¿Cuánto espacio en disco necesito?

Depende del tamaño de tu biblioteca fotográfica. Como referencia, para 10,000 fotos necesitarás aproximadamente: espacio para originales (ejemplo: 50GB para JPEGs, 200GB+ para RAWs) más 10-15% adicional para thumbnails, cachés y base de datos. Una biblioteca de 50,000 fotos puede requerir fácilmente 500GB-1TB total.

¿Puedo migrar desde Google Photos a PhotoPrism?

Sí, el proceso es directo: descarga tu archivo Google Takeout con todas tus fotos, extrae el ZIP, y copia las carpetas al directorio originals. Luego ejecuta el comando de indexación. El sistema procesará automáticamente los metadatos EXIF y organizará tu biblioteca. Ten en cuenta que álbumes de Google Photos no se migran automáticamente y deberás recrearlos manualmente.

¿Cómo aseguro mis fotos con backups?

Implementa una estrategia 3-2-1: mantén 3 copias en 2 medios diferentes con 1 copia off-site. Realiza backups del directorio originals (tus fotos originales) y database (MariaDB). Puedes usar rsync, Restic, Borg o herramientas similares para automatizar backups incrementales a almacenamiento externo o cloud.

El directorio storage puede regenerarse mediante re-indexación, así que es menos crítico para backups (aunque recomendado para evitar re-procesamiento).

Conclusión

Implementar PhotoPrism Docker Compose te proporciona una solución profesional de gestión fotográfica que rivaliza con servicios comerciales, pero manteniendo control absoluto sobre tus datos personales. Con más de 38.800 estrellas en GitHub y una comunidad activa de 185+ contribuidores, esta plataforma representa la opción más madura para quienes buscan privacidad sin sacrificar funcionalidades avanzadas.

Las capacidades de inteligencia artificial para reconocimiento facial, etiquetado automático y búsqueda avanzada transforman miles de fotografías desorganizadas en una biblioteca perfectamente catalogada y fácilmente navegable. Ya sea que gestiones una colección personal de vacaciones familiares o un archivo profesional de 50,000+ imágenes RAW, el sistema escala eficientemente adaptándose a tus necesidades.

El proceso de instalación, aunque requiere configuración inicial cuidadosa, puede completarse en menos de 10 minutos siguiendo esta guía. Los beneficios a largo plazo de privacidad, control total y cero costos recurrentes de almacenamiento hacen que la inversión de tiempo inicial valga absolutamente la pena.

Si te ha resultado útil este tutorial, explora más artículos sobre self-hosting en nuestra categoría Docker Compose, donde encontrarás guías completas para desplegar servicios como Nextcloud, Vaultwarden y Jellyfin.