Variables de Entorno

precaución

Para cambiar las variables de entorno, debes recrear los contenedores de Immich. ¡Solo reiniciar los contenedores no reemplaza el entorno dentro del contenedor!

Para recrear el contenedor usando docker compose, ejecuta docker compose up -d. En la mayoría de los casos, docker reconocerá que el archivo .env ha cambiado y recreará los contenedores afectados. Si esto no funciona, intenta ejecutar docker compose up -d --force-recreate.

Docker Compose

Variable	Descripción	Por Defecto	Contenedores
IMMICH_VERSION	Etiquetas de imagen	release	servidor, aprendizaje automático
UPLOAD_LOCATION	Ruta del host para subidas		servidor
DB_DATA_LOCATION	Ruta del host para la base de datos Postgres		base de datos

consejo

Estas variables de entorno son utilizadas por el archivo docker-compose.yml y NO afectan directamente a los contenedores.

General

Variable	Descripción	Por Defecto	Contenedores	Trabajadores
TZ	Zona horaria	*1	servidor	microservicios
IMMICH_ENV	Entorno (producción, desarrollo)	production	servidor, aprendizaje automático	api, microservicios
IMMICH_LOG_LEVEL	Nivel de registro (verbose, debug, log, warn, error)	log	servidor, aprendizaje automático	api, microservicios
IMMICH_MEDIA_LOCATION	Ubicación de medios dentro del contenedor ⚠️Probablemente no deberías configurar esto*2⚠️	/usr/src/app/upload	servidor	api, microservicios
IMMICH_CONFIG_FILE	Ruta al archivo de configuración		servidor	api, microservicios
NO_COLOR	Configurar en true para desactivar la salida de registros con códigos de color	false	servidor, aprendizaje automático
CPU_CORES	Número de núcleos disponibles para el servidor Immich	Número de núcleos de CPU detectado automáticamente	servidor
IMMICH_API_METRICS_PORT	Puerto para las métricas OTEL	8081	servidor	api
IMMICH_MICROSERVICES_METRICS_PORT	Puerto para las métricas OTEL	8082	servidor	microservicios
IMMICH_PROCESS_INVALID_IMAGES	Cuando está en true, genera miniaturas para imágenes no válidas		servidor	microservicios
IMMICH_TRUSTED_PROXIES	Lista de IPs separadas por comas configuradas como proxies confiables		servidor	api
IMMICH_IGNORE_MOUNT_CHECK_ERRORS	Ver Integridad del sistema		servidor	api, microservicios

*1: TZ debe configurarse con un identificador de zona horaria de esta lista. Por ejemplo, TZ="Etc/UTC". TZ es utilizado por exiftool como alternativa en caso de que no se pueda determinar la zona horaria a partir de los metadatos de la imagen. También se utiliza para marcas de tiempo en los archivos de registro y la ejecución de cron jobs.

*2: Esta ruta es donde el código de Immich busca los archivos, lo cual es interno para el contenedor docker. Configurarlo a una ruta en tu host ciertamente causará problemas, deberías usar la variable UPLOAD_LOCATION en su lugar.

Trabajadores

Variable	Descripción	Por Defecto	Contenedores
IMMICH_WORKERS_INCLUDE	Solo ejecuta estos trabajadores.		servidor
IMMICH_WORKERS_EXCLUDE	No ejecuta estos trabajadores. Coincide contra trabajadores predeterminados o IMMICH_WORKERS_INCLUDE si se especifica.		servidor

información

La información sobre los trabajadores actuales se puede encontrar aquí.

Puertos

Variable	Descripción	Por Defecto
IMMICH_HOST	Host autorizado	0.0.0.0
IMMICH_PORT	Puerto de escucha	2283 (servidor), 3003 (aprendizaje automático)

Base de Datos

Variable	Descripción	Por Defecto	Contenedores
DB_URL	URL de la base de datos		servidor
DB_HOSTNAME	Host de la base de datos	database	servidor
DB_PORT	Puerto de la base de datos	5432	servidor
DB_USERNAME	Usuario de la base de datos	postgres	servidor, base de datos*1
DB_PASSWORD	Contraseña de la base de datos	postgres	servidor, base de datos*1
DB_DATABASE_NAME	Nombre de la base de datos	immich	servidor, base de datos*1
DB_SSL_MODE	Modo SSL de la base de datos		servidor
DB_VECTOR_EXTENSION*2	Extensión vectorial de la base de datos (vectorchord, pgvector, pgvecto.rs)		servidor
DB_SKIP_MIGRATIONS	Ignorar la ejecución de migraciones en el inicio (true, false)	false	servidor
DB_STORAGE_TYPE	Optimización de IO concurrente en SSDs o IO secuencial en HDDs ([SSD, HDD])*3	SSD	servidor

*1: Los valores de DB_USERNAME, DB_PASSWORD y DB_DATABASE_NAME se pasan al contenedor de Postgres como las variables POSTGRES_USER, POSTGRES_PASSWORD y POSTGRES_DB en docker-compose.yml.

*2: Si no se proporciona, se detectará automáticamente cuál extensión usar durante el inicio introspectando la base de datos. Cuando se instalan múltiples extensiones, el orden de preferencia es VectorChord, pgvecto.rs, pgvector.

*3: Usa postgresql.ssd.conf o postgresql.hdd.conf, que principalmente controla la configuración effective_io_concurrency de Postgres para permitir IO concurrente en SSDs y IO secuencial en HDDs.

información

Todas las variables DB_ deben proporcionarse a todos los trabajadores de Immich, incluidos api y microservicios.

DB_URL debe tener el formato postgresql://usuario:contraseña@host:puerto/nombrebasededatos. Puedes requerir SSL agregando ?sslmode=require al final de la cadena de DB_URL, o requerir SSL y omitir la verificación del certificado agregando ?sslmode=require&sslmode=no-verify.

Cuando se define DB_URL, las variables de base de datos DB_HOSTNAME, DB_PORT, DB_USERNAME, DB_PASSWORD y DB_DATABASE_NAME son ignoradas.

Redis

Variable	Descripción	Por Defecto	Contenedores
REDIS_URL	URL de Redis		servidor
REDIS_SOCKET	Socket de Redis		servidor
REDIS_HOSTNAME	Host de Redis	redis	servidor
REDIS_PORT	Puerto de Redis	6379	servidor
REDIS_USERNAME	Usuario de Redis		servidor
REDIS_PASSWORD	Contraseña de Redis		servidor
REDIS_DBINDEX	Índice de BD de Redis	0	servidor

información

Todas las variables REDIS_ deben proporcionarse a todos los trabajadores de Immich, incluidos api y microservicios.

REDIS_URL debe comenzar con ioredis:// e incluir una cadena JSON codificada en base64 para la configuración. Puedes encontrar más información en la documentación de ioredis.

Cuando se definen REDIS_URL o REDIS_SOCKET, las variables REDIS_HOSTNAME, REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD y REDIS_DBINDEX son ignoradas.

Ejemplo de URL de Redis (Sentinel) en JSON antes de codificación:

JSON

{
  "sentinels": [
    {
      "host": "redis-sentinel-node-0",
      "port": 26379
    },
    {
      "host": "redis-sentinel-node-1",
      "port": 26379
    },
    {
      "host": "redis-sentinel-node-2",
      "port": 26379
    }
  ],
  "name": "redis-sentinel"
}

Machine Learning

Variable	Descripción	Predeterminado	Contenedores
MACHINE_LEARNING_MODEL_TTL	Tiempo de inactividad (s) antes de que un modelo sea descargado (deshabilitado si <= 0)	300	machine learning
MACHINE_LEARNING_MODEL_TTL_POLL_S	Intervalo (s) entre verificaciones del TTL del modelo (deshabilitado si <= 0)	10	machine learning
MACHINE_LEARNING_CACHE_FOLDER	Directorio donde se descargan los modelos	/cache	machine learning
MACHINE_LEARNING_REQUEST_THREADS*1	Cantidad de hilos del grupo de hilos de solicitud (deshabilitado si <= 0)	número de núcleos de CPU	machine learning
MACHINE_LEARNING_MODEL_INTER_OP_THREADS	Número de operaciones paralelas del modelo	1	machine learning
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS	Número de hilos por operación del modelo	2	machine learning
MACHINE_LEARNING_WORKERS*2	Número de procesos de trabajo a crear	1	machine learning
MACHINE_LEARNING_HTTP_KEEPALIVE_TIMEOUT_S*3	Tiempo de permanencia (keep-alive) en segundos para HTTP	2	machine learning
MACHINE_LEARNING_WORKER_TIMEOUT	Tiempo máximo (s) de falta de respuesta antes de que se elimine un trabajador	120 (300 si se utiliza OpenVINO)	machine learning
MACHINE_LEARNING_PRELOAD__CLIP__TEXTUAL	Lista separada por comas de modelos CLIP (textuales) a precargar y almacenar en caché		machine learning
MACHINE_LEARNING_PRELOAD__CLIP__VISUAL	Lista separada por comas de modelos CLIP (visuales) a precargar y almacenar en caché		machine learning
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__RECOGNITION	Lista separada por comas de modelos de reconocimiento facial (reconocimiento) a precargar		machine learning
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__DETECTION	Lista separada por comas de modelos de reconocimiento facial (detección) a precargar		machine learning
MACHINE_LEARNING_ANN	Habilitar aceleración de hardware ARM-NN si es compatible	True	machine learning
MACHINE_LEARNING_ANN_FP16_TURBO	Ejecutar operaciones en precisión FP16: incrementando la velocidad, reduciendo la precisión (solo para ARM-NN)	False	machine learning
MACHINE_LEARNING_ANN_TUNING_LEVEL	Nivel de ajuste de GPU ARM-NN (1: rápido, 2: normal, 3: exhaustivo)	2	machine learning
MACHINE_LEARNING_DEVICE_IDS*4	IDs de dispositivos a usar en entornos con múltiples GPUs	0	machine learning
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION	Establecer el número máximo de rostros que serán procesados al mismo tiempo por el modelo de reconocimiento facial	None (1 si se utiliza OpenVINO)	machine learning
MACHINE_LEARNING_PING_TIMEOUT	Tiempo de espera (ms) para una respuesta PING al verificar si un servidor de ML está disponible	2000	server
MACHINE_LEARNING_AVAILABILITY_BACKOFF_TIME	Tiempo para ignorar servidores de ML desconectados antes de intentarlo nuevamente	30000	server
MACHINE_LEARNING_RKNN	Habilitar aceleración de hardware RKNN si es compatible	True	machine learning
MACHINE_LEARNING_RKNN_THREADS	Cantidad de hilos de tiempo de ejecución de RKNN a iniciar durante la inferencia.	1	machine learning

*1: Se recomienda comenzar con este parámetro al cambiar los niveles de concurrencia del servicio de aprendizaje automático y luego ajustar los demás.

*2: Dado que cada proceso duplica los modelos en memoria, cambiar esto no se recomienda a menos que disponga de suficiente memoria.

*3: Para escenarios como HPA en K8S. https://github.com/immich-app/immich/discussions/12064

*4: El uso de múltiples GPUs requiere que MACHINE_LEARNING_WORKERS se configure a un valor mayor que 1. Un solo dispositivo se asigna a cada trabajador en una prioridad de tipo round-robin.

información

Aunque el modelo textual es el único requerido para la búsqueda inteligente, algunos usuarios pueden experimentar ralentizaciones en las primeras búsquedas debido a que las copias de seguridad activan la carga de los otros modelos en memoria, lo que bloquea otras solicitudes hasta completarse. Para evitar esto, puede precargar los otros modelos (visual, reconocimiento y detección) si tiene suficiente RAM para hacerlo.

Se pueden ajustar parámetros adicionales de aprendizaje automático desde la interfaz de usuario del administrador.

Prometheus

Variable	Descripción	Predeterminado	Contenedores	Workers
IMMICH_TELEMETRY_INCLUDE	Recopilar estas telemetrías. Lista de host, api, io, repo, job. Nota: También puede especificar all para habilitarlas todas		server	api, microservices
IMMICH_TELEMETRY_EXCLUDE	No recopilar estas telemetrías. Lista de host, api, io, repo, job		server	api, microservices

Docker Secrets

Las siguientes variables admiten el uso de Docker secrets para mayor seguridad.

Para usar cualquiera de estas, reemplace la variable de entorno regular por la variable de entorno equivalente _FILE. El valor de la variable _FILE debe ser la ruta de un archivo que contenga el valor de la variable.

Variable Regular	Variable Equivalente Docker Secrets '_FILE'
DB_HOSTNAME	DB_HOSTNAME_FILE*1
DB_DATABASE_NAME	DB_DATABASE_NAME_FILE*1
DB_USERNAME	DB_USERNAME_FILE*1
DB_PASSWORD	DB_PASSWORD_FILE*1
DB_URL	DB_URL_FILE*1
REDIS_PASSWORD	REDIS_PASSWORD_FILE*2

*1: Consulte la documentación oficial para detalles sobre cómo usar Docker Secrets en la imagen de Postgres.

*2: Consulte este comentario para un ejemplo de cómo usar un Docker secret para la contraseña en el contenedor de Redis.