Variáveis de Ambiente

cuidado

Para alterar as variáveis de ambiente, é necessário recriar os containers do Immich. Apenas reiniciar os containers não substituirá o ambiente dentro do container!

Para recriar o container usando o docker compose, execute docker compose up -d. Na maioria dos casos, o Docker reconhecerá que o arquivo .env foi alterado e recriará os containers afetados. Se isso não funcionar, tente executar docker compose up -d --force-recreate.

Docker Compose

Variável	Descrição	Padrão	Containers
IMMICH_VERSION	Tags da imagem	release	server, machine learning
UPLOAD_LOCATION	Caminho de host para uploads		server
DB_DATA_LOCATION	Caminho de host para o banco de dados Postgres		database

dica

Essas variáveis de ambiente são utilizadas pelo arquivo docker-compose.yml e NÃO afetam diretamente os containers.

Geral

Variável	Descrição	Padrão	Containers	Workers
TZ	Fuso horário	*1	server	microservices
IMMICH_ENV	Ambiente (produção, desenvolvimento)	production	server, machine learning	api, microservices
IMMICH_LOG_LEVEL	Nível de log (verbose, debug, log, warn, error)	log	server, machine learning	api, microservices
IMMICH_MEDIA_LOCATION	Local de mídia dentro do container ⚠️Provavelmente você não deve definir isso*2⚠️	/usr/src/app/upload	server	api, microservices
IMMICH_CONFIG_FILE	Caminho para o arquivo de configuração		server	api, microservices
NO_COLOR	Defina como true para desativar saída de log colorida	false	server, machine learning
CPU_CORES	Número de núcleos disponíveis para o servidor Immich	número de núcleos detectado	server
IMMICH_API_METRICS_PORT	Porta para as métricas OTEL	8081	server	api
IMMICH_MICROSERVICES_METRICS_PORT	Porta para as métricas OTEL	8082	server	microservices
IMMICH_PROCESS_INVALID_IMAGES	Quando true, gerar miniaturas para imagens inválidas		server	microservices
IMMICH_TRUSTED_PROXIES	Lista de IPs separados por vírgulas definidos como proxies confiáveis		server	api
IMMICH_IGNORE_MOUNT_CHECK_ERRORS	Veja Integridade do Sistema		server	api, microservices

*1: TZ deve ser configurado para um identificador TZ da lista. Por exemplo, TZ="Etc/UTC". TZ é usado pelo exiftool como um fallback caso o fuso horário não possa ser determinado a partir dos metadados da imagem. Também é usado para timestamps de arquivos de log e execução de tarefas cron.

*2: Este caminho é onde o código Immich busca os arquivos, que é interno ao container Docker. Configurá-lo para um caminho no host certamente irá causar problemas; você deve usar a variável UPLOAD_LOCATION em vez disso.

Workers

Variável	Descrição	Padrão	Containers
IMMICH_WORKERS_INCLUDE	Execute apenas esses workers.		server
IMMICH_WORKERS_EXCLUDE	Não execute esses workers. Corresponde aos workers padrão ou IMMICH_WORKERS_INCLUDE, se especificado.		server

informação

Informações sobre os workers atuais podem ser encontradas aqui.

Portas

Variável	Descrição	Padrão
IMMICH_HOST	Host de escuta	0.0.0.0
IMMICH_PORT	Porta de escuta	2283 (server), 3003 (machine learning)

Banco de Dados

Variável	Descrição	Padrão	Containers
DB_URL	URL do banco de dados		server
DB_HOSTNAME	Host do banco de dados	database	server
DB_PORT	Porta do banco de dados	5432	server
DB_USERNAME	Usuário do banco de dados	postgres	server, database*1
DB_PASSWORD	Senha do banco de dados	postgres	server, database*1
DB_DATABASE_NAME	Nome do banco de dados	immich	server, database*1
DB_SSL_MODE	Modo SSL do banco de dados		server
DB_VECTOR_EXTENSION*2	Extensão de vetor do banco de dados (uma entre [vectorchord, pgvector, pgvecto.rs])		server
DB_SKIP_MIGRATIONS	Ignorar a execução de migrações na inicialização (uma entre [true, false])	false	server
DB_STORAGE_TYPE	Otimize I/O concorrente em SSDs ou I/O sequencial em HDs ([SSD, HDD])*3	SSD	server

*1: Os valores de DB_USERNAME, DB_PASSWORD e DB_DATABASE_NAME são passados ao container Postgres como variáveis POSTGRES_USER, POSTGRES_PASSWORD e POSTGRES_DB em docker-compose.yml.

*2: Se não fornecido, a extensão apropriada será detectada automaticamente na inicialização por introspecção do banco de dados. Quando várias extensões estão instaladas, a ordem de preferência é VectorChord, pgvecto.rs, pgvector.

*3: Utiliza postgresql.ssd.conf ou postgresql.hdd.conf, que controla principalmente a configuração effective_io_concurrency do Postgres para permitir I/O concorrente em SSDs e I/O sequencial em HDs.

informação

Todas as variáveis DB_ precisam ser fornecidas para todos os workers do Immich, incluindo api e microservices.

DB_URL deve estar no formato postgresql://usuariodb:senhadb@hostdobanco:portadobanco/nomedobanco. Você pode exigir SSL adicionando ?sslmode=require ao final da string DB_URL, ou exigir SSL e ignorar a verificação de certificado adicionando ?sslmode=require&sslmode=no-verify.

Quando DB_URL está definido, as variáveis DB_HOSTNAME, DB_PORT, DB_USERNAME, DB_PASSWORD e DB_DATABASE_NAME são ignoradas.

Redis

Variável	Descrição	Padrão	Containers
REDIS_URL	URL do Redis		server
REDIS_SOCKET	Socket do Redis		server
REDIS_HOSTNAME	Host do Redis	redis	server
REDIS_PORT	Porta do Redis	6379	server
REDIS_USERNAME	Usuário do Redis		server
REDIS_PASSWORD	Senha do Redis		server
REDIS_DBINDEX	Índice do DB Redis	0	server

informação

Todas as variáveis REDIS_ devem ser fornecidas para todos os workers do Immich, incluindo api e microservices.

REDIS_URL deve começar com ioredis:// e depois incluir uma string JSON codificada em base64 para a configuração. Mais informações podem ser encontradas na documentação ioredis upstream.

Quando REDIS_URL ou REDIS_SOCKET são definidos, as variáveis REDIS_HOSTNAME, REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD e REDIS_DBINDEX são ignoradas.

Exemplo de JSON de URL do Redis (Sentinel) antes da codificação:

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"
}

Aprendizado de Máquina

Variável	Descrição	Padrão	Contêineres
MACHINE_LEARNING_MODEL_TTL	Tempo de inatividade (s) antes de um modelo ser descarregado (desabilitado se <= 0)	300	aprendizado de máquina
MACHINE_LEARNING_MODEL_TTL_POLL_S	Intervalo (s) entre verificações para o TTL do modelo (desabilitado se <= 0)	10	aprendizado de máquina
MACHINE_LEARNING_CACHE_FOLDER	Diretório onde os modelos são baixados	/cache	aprendizado de máquina
MACHINE_LEARNING_REQUEST_THREADS*1	Contagem de threads do pool de threads de requisição (desabilitado se <= 0)	número de núcleos da CPU	aprendizado de máquina
MACHINE_LEARNING_MODEL_INTER_OP_THREADS	Número de operações paralelas do modelo	1	aprendizado de máquina
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS	Número de threads para cada operação do modelo	2	aprendizado de máquina
MACHINE_LEARNING_WORKERS*2	Número de processos de trabalhadores a serem criados	1	aprendizado de máquina
MACHINE_LEARNING_HTTP_KEEPALIVE_TIMEOUT_S*3	Tempo de Keep-alive HTTP em segundos	2	aprendizado de máquina
MACHINE_LEARNING_WORKER_TIMEOUT	Tempo máximo (s) de falta de resposta antes de um trabalhador ser encerrado	120 (300 se usando OpenVINO)	aprendizado de máquina
MACHINE_LEARNING_PRELOAD__CLIP__TEXTUAL	Lista separada por vírgula de modelo(s) CLIP (textual) a serem pré-carregados e armazenados		aprendizado de máquina
MACHINE_LEARNING_PRELOAD__CLIP__VISUAL	Lista separada por vírgula de modelo(s) CLIP (visual) a serem pré-carregados e armazenados		aprendizado de máquina
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__RECOGNITION	Lista separada por vírgula de modelo(s) de reconhecimento facial (reconhecimento) pré-carregados e armazenados		aprendizado de máquina
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__DETECTION	Lista separada por vírgula de modelo(s) de reconhecimento facial (detecção) pré-carregados e armazenados		aprendizado de máquina
MACHINE_LEARNING_ANN	Ativa aceleração de hardware ARM-NN se suportado	True	aprendizado de máquina
MACHINE_LEARNING_ANN_FP16_TURBO	Executa operações em precisão FP16: aumenta velocidade, reduz precisão (aplica apenas ao ARM-NN)	False	aprendizado de máquina
MACHINE_LEARNING_ANN_TUNING_LEVEL	Nível de ajuste de GPU do ARM-NN (1: rápido, 2: normal, 3: exaustivo)	2	aprendizado de máquina
MACHINE_LEARNING_DEVICE_IDS*4	IDs dos dispositivos para usar em ambientes com múltiplos GPUs	0	aprendizado de máquina
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION	Define o número máximo de faces que serão processadas de uma vez pelo modelo de reconhecimento facial	Nenhum (1 se usando OpenVINO)	aprendizado de máquina
MACHINE_LEARNING_PING_TIMEOUT	Tempo de espera (ms) para uma resposta PING ao verificar se um servidor ML está disponível	2000	servidor
MACHINE_LEARNING_AVAILABILITY_BACKOFF_TIME	Tempo para ignorar servidores ML que estão offline antes de tentar novamente	30000	servidor
MACHINE_LEARNING_RKNN	Ativa aceleração de hardware RKNN se suportado	True	aprendizado de máquina
MACHINE_LEARNING_RKNN_THREADS	Quantidade de threads de runtime RKNN que devem ser criadas durante inferência.	1	aprendizado de máquina

*1: É recomendado começar com este parâmetro ao alterar os níveis de concorrência do serviço de aprendizado de máquina e depois ajustar os outros.

*2: Como cada processo duplica modelos na memória, alterar isso não é recomendado, a menos que você tenha memória abundante disponível.

*3: Para cenários como HPA no K8S. https://github.com/immich-app/immich/discussions/12064

*4: Usar múltiplos GPUs requer que MACHINE_LEARNING_WORKERS seja definido como maior que 1. Um único dispositivo é atribuído a cada trabalhador com prioridade em round-robin.

informação

Embora o modelo textual seja o único necessário para busca inteligente, alguns usuários podem experimentar lentidão nas primeiras buscas devido a backups que acionam o carregamento dos outros modelos na memória, bloqueando outras requisições até que sejam concluídas. Para evitar isso, você pode pré-carregar os outros modelos (visual, recognition e detection) se tiver RAM suficiente para fazê-lo.

Parâmetros adicionais de aprendizado de máquina podem ser ajustados a partir da interface administrativa.

Prometheus

Variável	Descrição	Padrão	Contêineres	Trabalhadores
IMMICH_TELEMETRY_INCLUDE	Coletar estas telemetrias. Lista de host, api, io, repo, job. Nota: Você também pode especificar all para habilitar todas		servidor	api, microsserviços
IMMICH_TELEMETRY_EXCLUDE	Não coletar estas telemetrias. Lista de host, api, io, repo, job		servidor	api, microsserviços

Segredos do Docker

As seguintes variáveis suportam o uso de Segredos do Docker para segurança adicional.

Para usar qualquer uma dessas, substitua a variável de ambiente regular pela variável de ambiente equivalente _FILE. O valor da variável _FILE deve ser definido como o caminho de um arquivo contendo o valor da variável.

Variável Regular	Variável Equivalente Segredos do Docker '_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: Veja a documentação oficial para detalhes sobre como usar Segredos do Docker na imagem do Postgres.

*2: Veja este comentário para um exemplo de como usar um segredo do Docker para a senha no contêiner Redis.