Documentación

Esta documentación es para administradores que alojan Wanmory en un NAS, un servidor doméstico o un ordenador personal. Cubre la instalación, la configuración, el despliegue del servicio de IA, el uso diario, los ajustes del sistema y el mantenimiento. Para el diseño del sistema y los algoritmos, consulta Arquitectura.

Wanmory es una fototeca privada con IA, de código abierto y autoalojada. Se compone de cuatro contenedores: el backend en Go (server), el servicio de inferencia de IA en Python (ml), la base de datos PostgreSQL + pgvector (postgres) y mdns, que anuncia el dominio local. Todas las fotos, metadatos, vectores y la cola de tareas se guardan en local, sin depender de ningún servicio en la nube.

• Gestión de fotos: cronología agrupada por meses, álbumes y álbumes inteligentes, limpieza de ráfagas y fotos similares, mapa de viajes y presentaciones.
• Funciones de IA: detección y agrupación de caras, búsqueda en lenguaje natural (Chinese-CLIP), reconocimiento de texto (PP-OCR) y puntuación estética (selección IA).
• Varios miembros: cuentas individuales, permisos de borrado según quién subió cada foto e historial de accesos.

Opción 1: script de instalación (recomendado)

En un equipo de 64 bits con Docker instalado, ejecuta:

curl -fsSL https://wanmory.com/install.sh | bash

El script hace lo siguiente, por orden:

• Comprobación del entorno: arquitectura de CPU (amd64 / arm64) y espacio de usuario de 64 bits, disponibilidad de Docker y Docker Compose v2, memoria y espacio en disco libres.
• Configuración interactiva: carpeta de instalación (por defecto ~/wanmory), puerto de acceso (por defecto 8080, comprueba si está ocupado), dominio local (por defecto wanmory.local), contraseña de la base de datos (aleatoria por defecto) y ubicación de la base de datos (por defecto el volumen Docker pgdata, o una carpeta en un disco local), y zona horaria (escribe una ciudad o región para buscarla, como shanghai, tokyo o 北京, y elige un número si hay varias coincidencias).
• Ubicaciones de almacenamiento: carpeta de datos (miniaturas, vistas previas y fotos subidas, por defecto ./data) y carpeta de modelos de IA (por defecto ./models).
• Las preguntas y mensajes del script están en inglés para que se vean bien en cualquier terminal de NAS.
• Carpetas de fotos existentes: añade tantas como quieras, eligiendo para cada una montaje de solo lectura (recomendado) o de lectura y escritura.
• Crea .env (permisos 600); si se indican carpetas de fotos, crea también docker-compose.override.yml, que Docker Compose combina automáticamente.
• Descarga el docker-compose.yml oficial (desde Gitee si GitHub no responde), valida la configuración, descarga las imágenes, arranca los servicios y muestra la dirección cuando todo está listo.

# Ejemplo: instalación no interactiva en /opt/wanmory con el puerto 9000 y carpetas de fotos del NAS
curl -fsSL https://wanmory.com/install.sh | WANMORY_PORT=9000 WANMORY_PHOTOS=/volume1/photo,/volume2/family bash -s -- -y --dir /opt/wanmory

Opción 2: instalación manual

1. 1
   Crea una carpeta y descarga el archivo Compose

   Crea una carpeta para el archivo Compose, los datos y los modelos, y descarga el docker-compose.yml oficial:

   bashCopiar

   mkdir -p ~/wanmory && cd ~/wanmory
   curl -fsSLO https://raw.githubusercontent.com/i-dj/wanmory/main/docker/docker-compose.yml

2. 2
   (Opcional) Escribe un .env

   Crea un .env en la misma carpeta para cambiar los valores por defecto. En producción, cambia sí o sí la contraseña de la base de datos:

   .envCopiar

   WANMORY_DB_PASSWORD=cambia-esto-por-una-cadena-aleatoria
   WANMORY_PORT=8080
   WANMORY_TZ=Europe/Madrid
   WANMORY_VERSION=latest

3. 3
   Arranca los servicios

   El primer arranque descarga las imágenes y ejecuta automáticamente las migraciones de la base de datos:

   bashCopiar

   docker compose up -d
   docker compose ps        # comprueba que los cuatro servicios estén running / healthy

4. 4
   Abre y configura

   Abre http://wanmory.local:8080 (o http://<IP del equipo>:8080) en el navegador, crea la cuenta de administrador según las indicaciones y descarga los modelos en «Ajustes del sistema → IA». Cuando terminen de descargarse, las fotos existentes entran solas en la cola de IA.

El archivo Compose oficial define cuatro servicios: la base de datos postgres, el backend server, el anunciador del dominio local mdns y el servicio de IA integrado ml. Para qué sirve cada ajuste está anotado en el propio archivo:

# Archivo Compose oficial de Wanmory: ejecuta docker compose up -d en la carpeta de este archivo
# Las variables con forma ${VAR:-defecto} se leen del .env de la misma carpeta; si no existen, se usa el valor por defecto
services:
  # ── Base de datos: PostgreSQL 17 + pgvector ──────────────────────
  # Guarda metadatos de fotos, personas, álbumes, ajustes, la cola de tareas y los vectores (índice HNSW)
  # No publica puertos; solo accesible en la red interna de Compose
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: wanmory
      POSTGRES_PASSWORD: ${WANMORY_DB_PASSWORD:-wanmory}   # cámbiala en .env sí o sí en producción
      POSTGRES_DB: wanmory
    volumes:
      - ${WANMORY_DB_DIR:-pgdata}:/var/lib/postgresql/data  # volumen con nombre pgdata por defecto; con WANMORY_DB_DIR, esa carpeta. Inclúyela en las copias de seguridad
    healthcheck:                             # server espera a esta comprobación y arranca cuando la base de datos está lista
      test: ["CMD", "pg_isready", "-U", "wanmory", "-d", "wanmory"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped
  # ── Backend: binario Go con la app web incrustada ────────────────
  # Se encarga de la API, subidas (tus), planificación de tareas, miniaturas y permisos; migra la base de datos al arrancar
  server:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    environment:
      DATABASE_URL: postgres://wanmory:${WANMORY_DB_PASSWORD:-wanmory}@postgres:5432/wanmory
      WANMORY_ML_URL: http://ml:3003         # dirección del servicio de IA integrado; uno remoto se configura en «Ajustes de IA»
      TZ: ${WANMORY_TZ:-Asia/Shanghai}       # zona horaria si el EXIF no la indica
      WANMORY_MDNS: "off"                    # este contenedor no recibe multidifusión en la red bridge; el servicio mdns de abajo anuncia el dominio
      WANMORY_HTTP_PUBLIC_PORT: ${WANMORY_PORT:-8080}   # puerto que muestra la app web; debe coincidir con el mapeo de puertos
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # dominio local inicial; si se cambia en los ajustes web, manda el ajuste
    ports:
      - "${WANMORY_PORT:-8080}:8080"         # puerto del equipo:puerto del contenedor
    volumes:
      - ${WANMORY_DATA_DIR:-./data}:/data    # upload/ guarda los originales subidos, thumbs/ las miniaturas y vistas de 1440 px
      # Monta las carpetas de fotos existentes como subcarpetas de /photos, tantas como quieras; :ro = solo lectura; se escanean cada 15 minutos
      # - /mnt/nas/photos:/photos/nas:ro
      # - /media/usb/camara:/photos/usb:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
  # ── Anuncio del dominio local (mDNS) ─────────────────────────────
  # Misma imagen que server, solo ejecuta el subcomando mdns; anuncia wanmory.local (se puede cambiar en la app web)
  mdns:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    command: ["mdns"]
    network_mode: host                       # hace falta la red del equipo para enviar y recibir multidifusión local
    environment:
      WANMORY_URL: http://127.0.0.1:${WANMORY_PORT:-8080}   # pregunta periódicamente a server el dominio actual
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # se anuncia mientras server no responda
    depends_on:
      - server
    restart: unless-stopped
  # ── Servicio de IA integrado: FastAPI + ONNX Runtime, solo CPU ───
  # Sin estado; recibe las vistas previas de server y devuelve caras, vectores y texto; no publica puertos
  ml:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-ml:${WANMORY_VERSION:-latest}
    volumes:
      - ${WANMORY_MODELS_DIR:-./models}:/models  # conserva los modelos: recrear el contenedor no los vuelve a descargar
    environment:
      WANMORY_MODEL_DIR: /models
      WANMORY_AUTO_DOWNLOAD: "0"             # sin descarga automática; un administrador confirma licencias y espacio en la app web
    restart: unless-stopped
volumes:
  pgdata:

.env (variables de Compose)

Estas variables se usan en docker-compose.yml; ponlas en el .env de la misma carpeta para aplicarlas:

Contenedor server (opcional)

DATABASE_URL, WANMORY_ML_URL, WANMORY_MDNS y WANMORY_HTTP_PUBLIC_PORT ya están en el archivo Compose con su finalidad anotada. Las siguientes variables no están en el archivo por defecto; añádelas al environment de server si las necesitas:

Las fotos que ya están en un NAS o un disco externo no hace falta subirlas. Monta la carpeta como subcarpeta de /photos dentro del contenedor: se escanea cada 15 minutos y los archivos nuevos se importan en su sitio (sin copiarlos ni moverlos); después pasan por la lectura de metadatos, las miniaturas y la IA igual que las fotos subidas.

  server:
    volumes:
      - ./data:/data
      - /mnt/nas/photos:/photos/nas:ro       # :ro monta en solo lectura
      - /media/usb/camara:/photos/usb:ro
      - /home/yo/Imagenes:/photos/pictures    # montaje de lectura y escritura

Tras el cambio, ejecuta docker compose up -d. El primer escaneo empieza unos 20 segundos después de reiniciarse el contenedor.

• Se recomienda montar en solo lectura (:ro): el sistema no escribe nada en esas carpetas. Borrar una foto en la app solo la mueve a «Eliminadas recientemente», el borrado definitivo nunca elimina el archivo original y los escaneos posteriores no lo vuelven a importar. En carpetas de lectura y escritura, el borrado definitivo también elimina el archivo original.
• Los archivos con contenido idéntico solo se importan una vez (se comparan por suma SHA-1), incluidos los ya subidos y los duplicados entre carpetas.
• Las carpetas ocultas y las de sistema del NAS (.xxx, @eaDir, #recycle, etc.) se omiten automáticamente.
• Las fotos importadas desde carpetas no pertenecen a ningún miembro; solo los administradores pueden borrarlas.

El servicio mdns funciona en modo de red del equipo y anuncia el dominio de acceso en tu red local (por defecto wanmory.local). macOS, iOS, iPadOS y Windows 10 o posterior acceden en http://wanmory.local:8080 sin configurar el router. El dominio se cambia en «Ajustes del sistema → Dominio de acceso» y debe terminar en .local.

Las subidas web usan el protocolo reanudable tus (/api/uploads/) con fragmentos de 16 MB. Detrás de un proxy inverso, quita el límite de tamaño de las peticiones y desactiva el búfer de peticiones. Ejemplo con Nginx:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/uploads/ {
    proxy_pass http://127.0.0.1:8080;
    client_max_body_size 0;          # sin límite de tamaño (como mínimo 20m)
    proxy_request_buffering off;     # transmitir en flujo sin guardar en el disco del proxy
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

El servicio de IA es un servicio HTTP sin estado: recibe vistas previas de 1440 píxeles del backend y devuelve caras, vectores y texto reconocido. Nunca accede a la base de datos ni guarda archivos. El backend admite dos modos, que se cambian en «Ajustes del sistema → IA → Modo de ejecución de IA»:

Si el servicio de IA no está disponible, las tareas de IA se quedan en la cola y dejan de tomarse, sin gastar reintentos; el procesamiento sigue solo cuando el servicio vuelve. Explorar, subir y lo demás no se ve afectado.

Opción 1: directamente en un Mac o equipo con GPU (recomendado)

Ejecutarlo directamente permite la aceleración por hardware: en Apple Silicon, los modelos de caras usan CoreML y Chinese-CLIP usa MPS; en GPU NVIDIA, Chinese-CLIP usa CUDA en media precisión (unos 1,9 GB de VRAM / memoria). Instala primero uv.

git clone https://github.com/i-dj/wanmory.git
cd wanmory/ml
uv sync --extra torch                 # instalar las dependencias de PyTorch (búsqueda semántica acelerada por GPU)
# Genera un token de acceso; el backend y el servicio de IA usan el mismo valor
export WANMORY_ML_TOKEN=$(openssl rand -hex 24)
echo $WANMORY_ML_TOKEN
WANMORY_FACE_MODEL_PRELOAD=1 uv run --extra torch python -m wanmory_ml
# Escucha en 0.0.0.0:3003 por defecto; se cambia con WANMORY_ML_HOST / WANMORY_ML_PORT

Opción 2: la imagen Docker en otro equipo

Para un equipo x86 más potente sin GPU utilizable; la imagen usa solo la CPU:

docker run -d --name wanmory-ml --restart unless-stopped \
  -p 3003:3003 \
  -e WANMORY_ML_TOKEN=<token-de-acceso> \
  -v $PWD/models:/models \
  ghcr.io/i-dj/wanmory-ml:latest

Activar el servicio remoto en el backend

1. 1
   Abre los ajustes de IA

   Como administrador, ve a «Ajustes del sistema → IA → Modo de ejecución de IA» y elige «Servicio remoto».

2. 2
   Introduce la dirección y el token

   La dirección tiene la forma http://192.168.1.20:3003; introduce el token generado en el paso anterior. Antes de guardar se prueba la conexión y se muestran la latencia y la versión del servicio.

3. 3
   Confirma el nivel y los modelos

   Una vez conectado, un nivel «Automático» se vuelve a calcular según el hardware del equipo remoto; descarga los modelos necesarios en «Nivel de modelos».

El nivel decide qué modelos se usan para las caras y la búsqueda semántica. Con «Automático», el sistema recomienda un nivel según el hardware del equipo donde está el servicio de IA: «Alta precisión» si hay una GPU utilizable; solo con CPU, «Ligero» por debajo de 6 GB de memoria y «Equilibrado» en otro caso.

• El reconocimiento de texto usa PP-OCRv6 (RapidOCR); sus modelos se instalan con las dependencias y no hay que descargarlos aparte.
• Tras cambiar de nivel, se vuelven a detectar las caras y a calcular los vectores semánticos de todas las fotos con los nuevos modelos; mientras tanto, la búsqueda sigue usando los vectores antiguos y las personas con nombre se conservan.
• Los modelos se descargan en la carpeta montada ./models, y puedes borrar los que ya no uses para liberar espacio (el que está en uso no se puede borrar).
• Los modelos faciales de InsightFace son solo para uso no comercial; sustitúyelos u obtén una licencia antes de cualquier uso comercial.

1. 1
   Crea el administrador

   En la primera visita, el sistema ve que no hay ninguna cuenta y te guía para crear un administrador. Los administradores pueden añadir miembros y cambiar los ajustes del sistema.

2. 2
   Descarga los modelos

   Ve a «Ajustes del sistema → IA», confirma el nivel de modelos y descárgalos. Las tareas de IA esperan en la cola hasta que estén listos.

3. 3
   Importa fotos

   Súbelas desde la app web o conecta las fotos de tu NAS como se explica en Montar carpetas de fotos existentes.

4. 4
   Añade miembros

   En «Ajustes del sistema → Miembros», crea cuentas para otras personas y elige el rol «Miembro» o «Administrador».

• La subida web admite fotos, vídeos, HEIC, RAW (como DNG) y más, con selección múltiple; se sube por fragmentos con el protocolo tus y se reanuda tras un corte de red o al recargar la página.
• Los archivos subidos se guardan por año y mes en la carpeta de subidas (por defecto data/upload). La carpeta se cambia en «Ajustes del sistema → Carpeta de subidas» y solo afecta a las nuevas subidas.
• Tras importar, se ejecutan por orden: lectura de metadatos (ExifTool) → miniaturas y vista previa de 1440 píxeles (libvips / FFmpeg) → vectores semánticos, caras y texto (servicio de IA) → geocodificación inversa.
• El indicador de tareas en la parte superior de la barra lateral muestra, en número de fotos, el progreso y el tiempo restante estimado de «Importar fotos» y «Reconocimiento con IA».

La información de las personas (nombres, fusiones) es común a todos los miembros; el número de fotos, las portadas y las páginas de personas se calculan con las fotos que cada miembro puede ver, y las fotos ocultas solo las ve su dueño.

• Miembros: al añadir uno, define nombre, contraseña inicial (mínimo 4 caracteres) y rol; puedes restablecer la contraseña de un miembro o quitarlo.
• Historial de accesos: registra la hora, el dispositivo y la IP de cada inicio de sesión, con la ubicación estimada sin conexión a partir de la IP (ip2region), y conserva los últimos seis meses. Solo lo ven los administradores.
• En «Mi cuenta», cada miembro puede cambiar su contraseña y su avatar y ver los dispositivos en los que tiene la sesión abierta.

La parte superior de la tarjeta muestra en vivo el estado de la IA (en marcha o motivo de la pausa). Los cambios se aplican al instante, sin reiniciar.

«Ajustes del sistema → Actualización del sistema» muestra las versiones actuales del backend y del servicio de IA y avisa de las nuevas. Para actualizar, ejecuta en la carpeta donde está docker-compose.yml:

docker compose pull && docker compose up -d

Las migraciones de la base de datos se ejecutan solas al arrancar server. Si fijaste una versión con WANMORY_VERSION, cambia antes la etiqueta en .env.

Hay tres tipos de datos que copiar:

# Exportar la base de datos
docker compose exec -T postgres pg_dump -U wanmory -Fc wanmory > wanmory-$(date +%F).dump
# Restaurar en una instalación nueva (ejecuta antes docker compose up -d postgres)
docker compose exec -T postgres pg_restore -U wanmory -d wanmory --clean < wanmory-2026-11-10.dump

Si un miembro olvida su contraseña, un administrador la restablece en «Ajustes del sistema → Miembros». Si el administrador olvida la suya, ejecuta esto en el equipo donde funciona la app, en la carpeta donde está docker-compose.yml:

docker compose exec server wanmory reset-password            # listar las cuentas y elegir una
docker compose exec server wanmory reset-password <nombre>    # indicar la cuenta directamente

• El comando lista todas las cuentas (nombre, rol, fecha de creación, último acceso); elige una por su número y escribe dos veces la nueva contraseña.
• Tras restablecerla, esa cuenta se cierra en todos los dispositivos; las fotos y los álbumes no cambian.
• Solo se puede hacer en el equipo; la app web no tiene opción para ello. Sin Docker, ejecuta wanmory reset-password con las mismas variables de entorno que el servidor, como DATABASE_URL.

Consulta los registros de cada servicio con docker compose logs -f server y docker compose logs -f ml. Si el problema sigue, cuéntanoslo en la página Informar de un problema con tu número de versión y los registros relevantes.

Ejecuta el script de desinstalación en el equipo donde funciona Wanmory:

curl -fsSL https://wanmory.com/uninstall.sh | bash

El script lee primero el .env de la carpeta de instalación y lista los contenedores, la base de datos, la carpeta de datos y los modelos de IA con el espacio que ocupan, además de las carpetas de fotos montadas. Después detiene y elimina los contenedores y la red, y pregunta uno a uno si quieres borrar cada elemento (por defecto se conserva todo):

• Las carpetas de fotos montadas (NAS, discos externos) nunca se borran.
• Para borrar la base de datos o la carpeta de datos hay que escribir DELETE como confirmación.
• Si solo eliminas los contenedores y conservas los datos, volver a ejecutar install.sh en la misma carpeta lo recupera todo; si borras .env pero conservas la base de datos, apunta antes el WANMORY_DB_PASSWORD que contiene.