instalar immich con 6gb ram y actualizar

Qué vas a construir

Immich es un servicio de respaldo de fotos y videos para hosting propio; un reemplazo real para Google Photos. Incluye una aplicación móvil que sube el carrete de fotos en segundo plano, una línea de tiempo, álbumes, reconocimiento facial y búsqueda mediante machine learning que encuentra términos como "beach" o personas sin necesidad de usar etiquetas. Se ejecuta en un VPS propio, los archivos originales permanecen en tu disco y nadie los escanea para venderte productos.

La instalación consiste en cuatro contenedores mediante el archivo Docker Compose del proyecto. Ese proceso tarda diez minutos. El resto de esta guía aborda los problemas técnicos: el contenedor de machine-learning consume mucha memoria en máquinas pequeñas, los archivos originales ocupan espacio en disco rápidamente, la aplicación móvil requiere HTTPS y Immich lanza cambios que rompen la compatibilidad con frecuencia, lo que puede causar que un docker compose pull descuidado deje la base de datos sin capacidad de inicio. Si gestionas estos cuatro puntos correctamente, Immich será muy estable. Si los ignoras, perderás un fin de semana.

Requisitos previos y posibles inconvenientes

• RAM: la documentación oficial indica un mínimo de 6 GB y 8 GB recomendados; considere 4 GB más swap como el límite absoluto. Los contenedores immich-server y Postgres consumen poco. El contenedor immich-machine-learning es el que más recursos consume: carga los modelos CLIP y de reconocimiento facial en la RAM para crear los índices de búsqueda; en un equipo con 2 GB, el kernel detendrá el proceso. Añada swap aunque tenga 4 GB.
• Disco: elija un tamaño para toda su biblioteca y un margen adicional. Sus archivos originales se copian íntegramente, además de que Immich genera miniaturas e imágenes de vista previa (aproximadamente un 10–20% adicional). Una colección de fotos de 200 GB requiere un volumen de 300 GB. Postgres es pequeño en comparación.
• CPU: cualquier VPS con KVM moderno es adecuado, pero el ML en CPU es lento. La indexación de búsqueda inteligente de una importación grande puede tardar horas en segundo plano. Esto es normal; no requiere una GPU.
• Un nombre de dominio apuntando al VPS. La aplicación móvil requiere preferiblemente un endpoint HTTPS, y se recomienda usar un reverse proxy. Este es el mismo tipo de configuración que una instancia de Nextcloud self-hosted con Docker, TLS y backups — Immich es el equivalente para fotos de ese servidor de archivos.
• Docker y el plugin Compose instalados — Docker Engine más el plugin Compose v2 desde el repositorio apt oficial de Docker, tal como se explica en nuestra guía básica de Docker Compose.

Paso 1: Añadir swap antes que cualquier otra cosa

El fallo más común de Immich en un VPS pequeño es que el contenedor de ML recibe un OOM-kill. Proporcione espacio al kernel mediante swap primero.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

free -h ahora debería mostrar una línea de Swap: con 4.0Gi. Esto no acelerará el ML, pero evita que el contenedor se detenga durante el proceso de indexación en máquinas de 4 GB.

Paso 2: Obtener el compose y el env oficiales — use los originales, no una copia

Immich fija las versiones de sus servicios y, lo que es más importante, la imagen de su base de datos dentro de los archivos que distribuye. No use un archivo compose copiado de un blog (incluido este) como fuente de verdad. Descargue los assets de la release:

sudo mkdir -p /opt/immich && cd /opt/immich
sudo wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
sudo wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Estos provienen de la release etiquetada, por lo que las referencias de las imágenes coinciden. El archivo compose define cuatro servicios; es útil saber qué es cada uno antes de realizar cambios:

• immich-server (ghcr.io/immich-app/immich-server, contenedor immich_server) — la API y la interfaz web, que escucha en el puerto 2283. Monta sus archivos subidos en /data.
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, contenedor immich_machine_learning) — búsqueda CLIP y reconocimiento facial. Almacena modelos descargados en un volumen model-cache. Este servicio consume mucha memoria.
• database (contenedor immich_postgres) — Postgres con la extensión vectorial VectorChord, que permite la búsqueda por similitud. La etiqueta de la imagen está fijada por digest en el archivo compose, por ejemplo ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Configuraciones antiguas usaban pgvecto.rs; el soporte se eliminó en Immich v3.0, por lo que cualquier instalación actual usa VectorChord. Nunca edite esta etiqueta manualmente.
• redis (contenedor immich_redis) — una instancia de Valkey/Redis para colas de trabajo.

Paso 3: Configurar .env — donde se almacenan sus fotos y la base de datos

Abra .env y configure cuatro parámetros. Todo lo que esté debajo de la línea marcada debe permanecer sin cambios.

# Where original uploads are stored on the host
UPLOAD_LOCATION=/opt/immich/library

# Where the Postgres data lives. NEVER put this on an NFS/network share.
DB_DATA_LOCATION=/opt/immich/postgres

# "v3" is a floating tag that tracks the latest v3.x. Pin a full tag like
# v3.0.2 instead — then you upgrade on purpose, not by surprise.
IMMICH_VERSION=v3.0.2

# Change this to a long random string. Letters and digits only.
DB_PASSWORD=REPLACE_WITH_A_LONG_RANDOM_STRING

# Set your timezone so timestamps and "on this day" line up
TZ=Europe/London

###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Dos reglas para evitar problemas. UPLOAD_LOCATION debe apuntar a su disco de gran capacidad; si planea añadir un volumen de datos más adelante, configure esto con su ruta de montaje desde el inicio, ya que cambiarlo después implica mover las miniaturas y actualizar las rutas de los archivos. Además, DB_DATA_LOCATION debe estar en un disco local: Postgres se corrompe en recursos compartidos NFS o SMB, según indica la documentación. Si utiliza únicamente letras y dígitos en DB_PASSWORD, evitará errores de escape en las cadenas de conexión.

Paso 4: Primera ejecución y creación del usuario administrador

cd /opt/immich
sudo docker compose up -d
sudo docker compose ps

Un resultado correcto muestra cuatro contenedores, todos running y finalmente healthy:

NAME                      STATUS
immich_machine_learning   Up (healthy)
immich_postgres           Up (healthy)
immich_redis              Up (healthy)
immich_server             Up (healthy)

El primer up descarga varios gigabytes de imágenes; espere a que termine. Puede monitorear el progreso con sudo docker compose logs -f immich-server; el servidor registrará que está escuchando en el puerto 2283 cuando esté listo. Ahora abra http://YOUR_SERVER_IP:2283 en un navegador. La primera visita mostrará un asistente de Getting Started; la primera cuenta que cree será la cuenta de administrador. Use una contraseña segura; esta cuenta gestiona la configuración del servidor, la administración de usuarios y la configuración de ML necesaria para más adelante.

Paso 5: La aplicación móvil y el respaldo en segundo plano

Instale "Immich" desde la App Store o Play Store. En la pantalla de inicio de sesión se solicita un Server Endpoint URL. Ingrese la URL completa incluyendo el esquema, por ejemplo https://photos.example.com (la aplicación añade /api automáticamente). Inicie sesión con la cuenta que acaba de crear, luego abra la pantalla de Backup de la aplicación, seleccione los álbumes para proteger (normalmente Camera y Screenshots) y active Background backup. El respaldo en segundo plano en iOS está limitado por el sistema operativo: las cargas en primer plano siempre se ejecutan, mientras que las de segundo plano ocurren cuando el sistema lo permite.

Este es el punto donde suelen surgir problemas, así que lea el Paso 6 antes de intentar configurar la aplicación.

Paso 6: HTTPS mediante un proxy inverso — y la regla de la URL completa

La aplicación móvil requiere HTTPS. Coloque un proxy inverso delante del puerto 2283 para finalizar la conexión TLS allí. Si ya ejecuta varios contenedores, Traefik con TLS automático para múltiples apps de Docker es la opción más organizada: un bloque de etiquetas (labels) redirige photos.example.com al contenedor immich-server y gestiona el certificado automáticamente. Si prefiere nginx, la guía Let's Encrypt con Certbot y nginx le proporciona un certificado y un bloque proxy_pass http://127.0.0.1:2283;. Una configuración del proxy es crítica para Immich: aumente el límite de tamaño de subida, ya que los vídeos de los teléfonos son grandes. En nginx, esto es client_max_body_size 50000M; dentro del bloque server; el valor predeterminado de 1 MB rechaza las subidas de vídeo con 413 Request Entity Too Large.

La regla que aplica la aplicación: el endpoint debe ser alcanzable y, en la práctica, debe ser HTTPS. Los endpoints con http://, o una IP directa sin el puerto, causan el error "la aplicación no puede alcanzar el servidor", detallado como un fallo específico más abajo.

Paso 7: Librerías externas vs. subidas — importar un árbol de fotos existente

Existen dos formas de añadir fotos a Immich, y no son lo mismo.

• Uploads (Subidas) son archivos que pertenecen a Immich. La aplicación o el cargador web copia el archivo en UPLOAD_LOCATION. Immich puede renombrarlos, moverlos y eliminarlos.
• External libraries (Librerías externas) son importaciones de solo lectura de archivos que ya residen en una carpeta de su servidor — un árbol Pictures antiguo o una exportación de un NAS. Immich los indexa en su ubicación original y los muestra en la línea de tiempo, pero nunca modifica ni elimina los originales.

Para importar un árbol existente, móntelo como solo lectura en el contenedor del servidor. Edite docker-compose.yml bajo immich-server: y añada un volumen:

  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
      - /srv/photos:/mnt/media/photos:ro

El flag :ro garantiza que Immich nunca pueda tocar los originales. Recree el contenedor con sudo docker compose up -d y, en la interfaz web, vaya a su avatar → Administration → External Libraries → Create Library, seleccione el usuario propietario, haga clic en Add bajo Folders e introduzca la ruta del contenedor — /mnt/media/photos, no la ruta del host /srv/photos. Haga clic en Scan. Usar la ruta del host en lugar de la ruta del contenedor es el error principal con las librerías externas; el escaneo no encuentra nada y reporta cero archivos.

Paso 8: La disciplina de actualización que requiere Immich

Esta parte diferencia una instalación funcional de una rota. Immich lanza actualizaciones rápidamente y no aplica parches retroactivos ni soporta degradaciones de versión (downgrades). Seguir ciegamente la etiqueta flotante v3 acabará corrompiendo la base de datos. La disciplina es:

1. Fijar una versión. Mantenga IMMICH_VERSION configurado con una etiqueta concreta como v3.0.2, no con la etiqueta flotante v3 que siempre descarga la última v3.x.
2. Leer las notas de la versión siempre antes de actualizar. Las modificaciones que rompen la compatibilidad —especialmente cambios en la base de datos o en la extensión vectorial— se detallan allí. El lanzamiento de la v3.0 es el ejemplo claro: eliminó pgvecto.rs por completo, por lo que cualquier usuario con la extensión antigua debía completar la migración a VectorChord (introducida en la v1.133) antes de actualizar.
3. Realizar una copia de seguridad de la base de datos primero (Paso 9). Siempre, y con mayor rigor si las notas mencionan la base de datos.
4. Descargar también el nuevo archivo compose. IMMICH_VERSION solo fija las imágenes del servidor y de ML. La imagen de Postgres está fijada por digest dentro de docker-compose.yml, por lo que una versión que requiera una extensión de base de datos más reciente incluirá un nuevo archivo compose. Descargue ambos archivos de la versión, reaplique sus valores de .env y luego actualice.
5. Actualizar los clientes móviles en el mismo periodo. El servidor solo es compatible con su propia versión principal, y la aplicación soporta la versión principal actual y la anterior. Un servidor con una versión superior a la de la aplicación mostrará Your app major version is not compatible with the server! en el teléfono hasta que se actualice la app; por seguridad, es mejor actualizar primero la aplicación.

Los comandos reales, una vez que tenga los archivos nuevos listos:

cd /opt/immich
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune

Paso 9: Backups — un volcado de la base de datos MÁS los originales, y realizar una prueba

Un backup de Immich consta de dos elementos; uno sin el otro es inútil. La database contiene la estructura de los álbumes, los rostros, los índices de búsqueda y el mapa que vincula el asset con el archivo. El originals directory contiene las fotos reales. Si restauras uno sin el otro, obtendrás fotos sin organización o una estructura vacía que apunta a archivos inexistentes.

Realiza un dump de la database con pg_dump desde el interior del contenedor Postgres —específicamente la database immich, no todo el cluster—:

sudo docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > /opt/immich/immich-db-$(date +%F).sql.gz

Luego, realiza el backup de UPLOAD_LOCATION —todo el árbol /opt/immich/library, y en particular sus subcarpetas library/, upload/ y profile/— usando restic, rsync o borg hacia otra máquina o almacenamiento de objetos. Ejecuta primero el dump de la database y después el de los archivos para evitar que el dump referencie una foto que el backup de archivos aún no ha copiado. Las external libraries se respaldan por separado en su origen real; Immich no es el propietario de estas.

Ahora la parte que todos omiten: probar la restauración. Una restauración debe ejecutarse contra un stack nuevo cuyo servidor nunca se haya iniciado, en una imagen de Postgres cuya extensión vector sea compatible con el dump; esta es la razón por la cual nunca se debe improvisar el tag de la imagen de la DB. En un equipo de prueba con el mismo compose y .env, elimina cualquier estado previo, levanta únicamente la database y carga el dump:

cd /opt/immich
sudo docker compose down -v
sudo docker compose pull
sudo docker compose create
sudo docker start immich_postgres
sleep 10
gunzip --stdout immich-db-2026-07-15.sql.gz |
  sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" |
  sudo docker exec -i immich_postgres psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on
sudo docker compose up -d

La reescritura sed de search_path es obligatoria en una database VectorChord; si se omite, la restauración fallará a mitad del proceso. Cuando el stack se reinicie con los originals en su lugar, abre la web UI: si tus fotos y álbumes aparecen, el backup funciona. Si nunca has realizado esta prueba, no tienes un backup, solo tienes una esperanza.

Modos de fallo y los strings que verá

El contenedor de ML recibe un OOM-kill. sudo docker compose logs immich-machine-learning termina abruptamente, docker compose ps muestra que Restarting, y el código de salida es 137. sudo dmesg | grep -i oom lo confirma: Out of memory: Killed process ... (python3). Los trabajos de búsqueda y reconocimiento facial se detienen. La causa es falta de RAM para los modelos. Soluciones, en orden: añadir swap (Paso 1); asignar más RAM al VPS; o, si no es posible, desactivar ML en Administration → Settings → Machine Learning Settings desactivando Smart Search y Facial Recognition — conservará los backups y álbumes, pero perderá la búsqueda por contenido. Eliminar el servicio immich-machine-learning del archivo compose tiene el mismo efecto.

Postgres no inicia tras una actualización. El log del servidor muestra un bucle con una línea como The database currently has VectorChord 0.5.3 activated, but the Postgres instance only has 0.4.2 available. This most likely means the extension was downgraded. — o, en stacks antiguos, The pgvecto.rs extension is not available in this Postgres instance.. La causa es una imagen de base de datos con una versión de extensión anterior a la versión de sus datos actualizados; esto ocurre casi siempre por editar la etiqueta de la imagen manualmente o por restaurar un dump reciente en una imagen antigua. La solución es usar la imagen de Postgres que coincida — utilice el archivo compose de la versión que corresponda a su base de datos, no haga downgrade, y restaure únicamente en una imagen compatible.

La app móvil no conecta con el servidor. La pantalla de login muestra un error de conexión / Server is not reachable tras introducir la URL. Tres causas: escribió http:// cuando el proxy solo sirve https://; se conectó directamente al backend sin especificar el puerto, intentando usar example.com (puerto 443) en lugar de example.com:2283; o el reverse proxy no está reenviando /api. Solucione esto introduciendo la URL completa de https://photos.example.com y confirme que carga primero en el navegador de un teléfono. Si el navegador funciona pero la app no, el proxy está eliminando la ruta o el certificado es autofirmado — la app rechaza certificados no confiables.

Falta de espacio en disco durante la importación. Las subidas fallan, las miniaturas aparecen en blanco y los logs muestran ENOSPC: no space left on device o, desde Postgres, could not extend file ... No space left on device. df -h muestra el volumen UPLOAD_LOCATION al 100%. Por esto debe dimensionar el disco antes de importar una librería grande. Para recuperar, adjunte un volumen más grande, detenga el stack, mueva UPLOAD_LOCATION a este nuevo volumen, actualice .env y reinicie — o expanda el disco existente si su proveedor lo permite. Postgres puede bloquearse si el disco se llena, así que libere espacio y reinicie el contenedor de la base de datos antes de asumir que hay corrupción.

FAQ

¿Cuánta RAM y disco necesita Immich?

Los requisitos oficiales de Immich son un mínimo de 6 GB de RAM y 8 GB recomendados. El límite práctico para una biblioteca pequeña es de 4 GB con swap; configure swap siempre, ya que el contenedor de machine-learning genera picos de consumo. Para el disco, reserve el tamaño total de su biblioteca más un 10–20% adicional para miniaturas y previsualizaciones en almacenamiento local. Nunca coloque el directorio de datos de Postgres en una unidad de red. Si aún decide qué otros servicios ejecutar, la guía de qué alojar por cuenta propia en 2026 compara el consumo de Immich con otros servicios.

¿Puedo ejecutar Immich sin una GPU?

Sí. El contenedor de machine-learning funciona correctamente en CPU. Una GPU solo acelera la indexación de smart-search y, con la variante de imagen adecuada, la transcodificación de video. Usando CPU, la indexación inicial de una biblioteca grande puede tardar horas en segundo plano, pero no bloquea las copias de seguridad ni la navegación. Si su equipo es insuficiente para ML, puede desactivar Smart Search y Facial Recognition en la configuración de administración y mantener el resto de las funciones.

¿Cómo actualizo Immich de forma segura?

Fije IMMICH_VERSION a una etiqueta concreta como v3.0.2, lea las notas de la versión antes de cada actualización y realice primero una copia de seguridad de la base de datos. Debido a que la imagen de Postgres está fijada dentro de docker-compose.yml en lugar de por IMMICH_VERSION, descargue de nuevo tanto el archivo compose como example.env de la versión de destino y vuelva a aplicar sus valores, luego ejecute docker compose pull && docker compose up -d. Nunca deje la versión sin fijar; Immich incluye cambios que rompen la compatibilidad y no admite degradaciones de versión (downgrades).

¿Qué debo respaldar exactamente?

Dos elementos juntos: un pg_dump de la base de datos immich y el directorio completo de originales UPLOAD_LOCATION. La base de datos contiene los álbumes, las caras y el mapeo de archivos; el directorio contiene las fotos reales. Una restauración requiere ambos elementos más una imagen de base de datos con una extensión vectorial compatible. Realice primero el volcado de la base de datos y después la copia de archivos. Pruebe la restauración en un equipo de prueba al menos una vez; una copia de seguridad no probada no es una copia de seguridad.

¿Cómo importo mi carpeta de fotos existente?

Monte la carpeta en modo solo lectura dentro del contenedor immich-server como un volumen adicional (por ejemplo - /srv/photos:/mnt/media/photos:ro), recree el contenedor y luego, en Administration → External Libraries, cree una biblioteca y añada la ruta del contenedor /mnt/media/photos. Immich indexa los archivos en su ubicación original y nunca los modifica ni elimina. El error más común es introducir la ruta del host en lugar de la ruta del contenedor, lo que provoca que el escaneo no encuentre nada.