¶ 
What is Immich?
Easily back up, organize, and manage your photos on your own server. Immich helps you browse, search and organize your photos and videos with ease, without sacrificing your privacy.
¶ 1 · Deploy Immich
TrueNAS
Docker Compose - CPU Docker Compose - Nvidia GPU Docker Compose - AMD GPU Docker Compose - Intel GPU/iGPU Docker Compose - VAAPI (Intel/AMD/Nvidia)
- Set a database and redis password
- If you have an nVidia GPU, select the Cuda Machine Learning Image for the Machine Learning Image Type
- Set Host Path Storage for Data and Postgres Storage options
Since Immich runs as
rootGeneric permissions are fine for all of these datasets
The Postgres Data Storage needs the ☑ Automatic Permissions checkbox checked!
- If you can, increase limits on the Resources Configuration
Check out the new docs from TrueNAS
services:
immich-server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
volumes:
- ${UPLOAD_LOCATION}:/data
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
ports:
- '2283:2283'
depends_on:
- redis
- database
restart: unless-stopped
healthcheck:
disable: false
immich-machine-learning:
container_name: immich_machine_learning
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
volumes:
- model-cache:/cache
env_file:
- .env
restart: unless-stopped
healthcheck:
disable: false
redis:
container_name: immich_redis
image: docker.io/valkey/valkey:8-bookworm@sha256:fea8b3e67b15729d4bb70589eb03367bab9ad1ee89c876f54327fc7c6e618571
healthcheck:
test: redis-cli ping || exit 1
restart: unless-stopped
database:
container_name: immich_postgres
image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
POSTGRES_INITDB_ARGS: '--data-checksums'
# Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
# DB_STORAGE_TYPE: 'HDD'
volumes:
- ${DB_DATA_LOCATION}:/var/lib/postgresql/data
shm_size: 128mb
restart: unless-stopped
volumes:
model-cache:
¶ env Variables
UPLOAD_LOCATION=/mnt/tank/configs/immich/uploads
IMMICH_VERSION=release
DB_DATA_LOCATION=/mnt/tank/configs/immich/db
DB_PASSWORD=postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
Make sure to change the
DB_PASSWORDto something random!
Set the IMMICH_VERSION based on the releases here.
¶ Folder Structure
tank
└── configs
└── immich
├── uploads
└── db
- The
uploadsdirectory will be where all photos are stored in individual folders per user
Since Immich runs as
rootGeneric permissions are fine for all of these datasets
services:
immich-server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu
- compute
- video
volumes:
- ${UPLOAD_LOCATION}:/data
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
ports:
- '2283:2283'
depends_on:
- redis
- database
restart: unless-stopped
healthcheck:
disable: false
immich-machine-learning:
container_name: immich_machine_learning
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cuda
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu
volumes:
- model-cache:/cache
env_file:
- .env
restart: unless-stopped
healthcheck:
disable: false
redis:
container_name: immich_redis
image: docker.io/valkey/valkey:8-bookworm@sha256:fea8b3e67b15729d4bb70589eb03367bab9ad1ee89c876f54327fc7c6e618571
healthcheck:
test: redis-cli ping || exit 1
restart: unless-stopped
database:
container_name: immich_postgres
image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
POSTGRES_INITDB_ARGS: '--data-checksums'
# Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
# DB_STORAGE_TYPE: 'HDD'
volumes:
- ${DB_DATA_LOCATION}:/var/lib/postgresql/data
shm_size: 128mb
restart: unless-stopped
volumes:
model-cache:
¶ env Variables
UPLOAD_LOCATION=/mnt/tank/configs/immich/uploads
IMMICH_VERSION=release
DB_DATA_LOCATION=/mnt/tank/configs/immich/db
DB_PASSWORD=postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
MACHINE_LEARNING_MODEL_TTL=0
MACHINE_LEARNING_MODEL_TTL_POLL_S=0
Make sure to change the
DB_PASSWORDto something random!
Set the IMMICH_VERSION based on the releases here.
In case you want to use multiple gpus see: https://docs.immich.app/features/ml-hardware-acceleration#multi-gpu
The GPU must have compute capability 5.2 or greater.
The server must have the official NVIDIA driver installed.
The installed driver must be >= 545 (it must support CUDA 12.3).
¶ Folder Structure
tank
└── configs
└── immich
├── uploads
└── db
- The
uploadsdirectory will be where all photos are stored in individual folders per user
Since Immich runs as
rootGeneric permissions are fine for all of these datasets
¶ Confirming GPU Utilization
To confirm you are actually using your GPU, you should do the following:
- On TrueNAS go to System > Shell
- Run
watch -d -n 1 nvidia-smiinside the terminal - You should be able to see a python process running if there is a job running for Smart Search, Facial Detection or Facial Recognition
This is under assumption that you have some content in your library.
services:
immich-server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
devices:
- /dev/dri:/dev/dri
volumes:
- ${UPLOAD_LOCATION}:/data
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
ports:
- '2283:2283'
depends_on:
- redis
- database
restart: unless-stopped
healthcheck:
disable: false
immich-machine-learning:
container_name: immich_machine_learning
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-rocm
group_add:
- video
devices:
- /dev/dri:/dev/dri
- /dev/kfd:/dev/kfd
volumes:
- model-cache:/cache
env_file:
- .env
restart: unless-stopped
healthcheck:
disable: false
redis:
container_name: immich_redis
image: docker.io/valkey/valkey:8-bookworm@sha256:fea8b3e67b15729d4bb70589eb03367bab9ad1ee89c876f54327fc7c6e618571
healthcheck:
test: redis-cli ping || exit 1
restart: unless-stopped
database:
container_name: immich_postgres
image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
POSTGRES_INITDB_ARGS: '--data-checksums'
# Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
# DB_STORAGE_TYPE: 'HDD'
volumes:
- ${DB_DATA_LOCATION}:/var/lib/postgresql/data
shm_size: 128mb
restart: unless-stopped
volumes:
model-cache:
The GPU must be supported by ROCm. If it isn't officially supported, you can attempt to use the
HSA_OVERRIDE_GFX_VERSIONenvironmental variable:HSA_OVERRIDE_GFX_VERSION=<a supported version, e.g. 10.3.0>. If this doesn't work, you might need to also setHSA_USE_SVM=0.
The ROCm image is quite large and requires at least 35GiB of free disk space. However, pulling later updates to the service through Docker will generally only amount to a few hundred megabytes as the rest will be cached.
This backend is new and may experience some issues. For example, GPU power consumption can be higher than usual after running inference, even if the machine learning service is idle. In this case, it will only go back to normal after being idle for 5 minutes (configurable with the MACHINE_LEARNING_MODEL_TTL setting).
¶ env Variables
UPLOAD_LOCATION=/mnt/tank/configs/immich/uploads
IMMICH_VERSION=release
DB_DATA_LOCATION=/mnt/tank/configs/immich/db
DB_PASSWORD=postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
MACHINE_LEARNING_MODEL_TTL=0
MACHINE_LEARNING_MODEL_TTL_POLL_S=0
Make sure to change the
DB_PASSWORDto something random!
Set the IMMICH_VERSION based on the releases here.
¶ Folder Structure
tank
└── configs
└── immich
├── uploads
└── db
- The
uploadsdirectory will be where all photos are stored in individual folders per user
Since Immich runs as
rootGeneric permissions are fine for all of these datasets
¶ Confirming GPU Utilization
To confirm you are actually using your GPU, you should do the following:
- On TrueNAS go to System > Shell
- Run
docker exec -it immich_machine_learning bashto enter the container - First you will have to update the repositories and install radeontop package by running
apt update && apt install radeontop
- Run
radeontopinside the terminal - You should be able to see usage increasing if there is a job running for Smart Search, Facial Detection or Facial Recognition
This is under assumption that you have some content in your library.
services:
immich-server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
devices:
- /dev/dri:/dev/dri
volumes:
- ${UPLOAD_LOCATION}:/data
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
ports:
- '2283:2283'
depends_on:
- redis
- database
restart: unless-stopped
healthcheck:
disable: false
immich-machine-learning:
container_name: immich_machine_learning
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-openvino
group_add:
- video
device_cgroup_rules:
- 'c 189:* rmw'
devices:
- /dev/dri:/dev/dri
volumes:
- model-cache:/cache
- /dev/bus/usb:/dev/bus/usb
env_file:
- .env
restart: unless-stopped
healthcheck:
disable: false
redis:
container_name: immich_redis
image: docker.io/valkey/valkey:8-bookworm@sha256:fea8b3e67b15729d4bb70589eb03367bab9ad1ee89c876f54327fc7c6e618571
healthcheck:
test: redis-cli ping || exit 1
restart: unless-stopped
database:
container_name: immich_postgres
image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
POSTGRES_INITDB_ARGS: '--data-checksums'
# Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
# DB_STORAGE_TYPE: 'HDD'
volumes:
- ${DB_DATA_LOCATION}:/var/lib/postgresql/data
shm_size: 128mb
restart: unless-stopped
volumes:
model-cache:
Integrated GPUs are more likely to experience issues than discrete GPUs, especially for older processors or servers with low RAM.
Ensure the server's kernel version is new enough to use the device for hardware accceleration.
Expect higher RAM usage when using OpenVINO compared to CPU processing.
¶ env Variables
UPLOAD_LOCATION=/mnt/tank/configs/immich/uploads
IMMICH_VERSION=release
DB_DATA_LOCATION=/mnt/tank/configs/immich/db
DB_PASSWORD=postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
MACHINE_LEARNING_MODEL_TTL=0
MACHINE_LEARNING_MODEL_TTL_POLL_S=0
Make sure to change the
DB_PASSWORDto something random!
Set the IMMICH_VERSION based on the releases here.
¶ Folder Structure
tank
└── configs
└── immich
├── uploads
└── db
- The
uploadsdirectory will be where all photos are stored in individual folders per user
Since Immich runs as
rootGeneric permissions are fine for all of these datasets
¶ Confirming GPU Utilization
To confirm you are actually using your GPU, you should do the following:
- On TrueNAS go to System > Shell
- Run
intel_gpu_topinside the terminal - You should be able to see a python process running if there is a job running for Smart Search, Facial Detection or Facial Recognition
This is under assumption that you have some content in your library.
services:
immich-server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
devices:
- /dev/dri:/dev/dri
volumes:
- ${UPLOAD_LOCATION}:/data
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
ports:
- '2283:2283'
depends_on:
- redis
- database
restart: unless-stopped
healthcheck:
disable: false
immich-machine-learning:
container_name: immich_machine_learning
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
volumes:
- model-cache:/cache
env_file:
- .env
restart: unless-stopped
healthcheck:
disable: false
redis:
container_name: immich_redis
image: docker.io/valkey/valkey:8-bookworm@sha256:fea8b3e67b15729d4bb70589eb03367bab9ad1ee89c876f54327fc7c6e618571
healthcheck:
test: redis-cli ping || exit 1
restart: unless-stopped
database:
container_name: immich_postgres
image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
POSTGRES_INITDB_ARGS: '--data-checksums'
# Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
# DB_STORAGE_TYPE: 'HDD'
volumes:
- ${DB_DATA_LOCATION}:/var/lib/postgresql/data
shm_size: 128mb
restart: unless-stopped
volumes:
model-cache:
In case your graphics card, dedicated or integrated, doesn't support machine learning, you can still accelerate transcoding!
You may want to choose a slower preset than for software transcoding to maintain quality and efficiency
While you can use VAAPI with NVIDIA and Intel devices, prefer the more specific APIs since they're more optimized for their respective devices
¶ env Variables
UPLOAD_LOCATION=/mnt/tank/configs/immich/uploads
IMMICH_VERSION=release
DB_DATA_LOCATION=/mnt/tank/configs/immich/db
DB_PASSWORD=postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
Make sure to change the
DB_PASSWORDto something random!
Set the IMMICH_VERSION based on the releases here.
¶ Folder Structure
tank
└── configs
└── immich
├── uploads
└── db
- The
uploadsdirectory will be where all photos are stored in individual folders per user
Since Immich runs as
rootGeneric permissions are fine for all of these datasets
¶ 2 · Adding External Libraries
- If installing from the TrueNAS apps catalog, under Storage Configuration → Additional Storage, add a host path pointed to where your photos are stored
- If installing via docker compose, add an additional line in the
immich_serversection pointed to where your photos are stored - Click the circle with the letter in the top right and select Administration
- Select External Libraries in the left panel
- Select an external library owner
- Click the 3 dots at the end of the row which was just created
- Select Edit Import Paths
- Select Add Path
- Add the path you mounted earlier and click Add
- Click Save
¶ 3 · Migrating to New Dataset Structure
Assuming you have the following legacy datasets:
tank
└── configs
└── immich
├── backups [dataset]
├── library [dataset]
├── profile [dataset]
├── thumbs [dataset]
├── video [dataset]
├── uploads [dataset]
└── db [dataset]
You need to migrate to the new datasets, where data has the sub-directories {backups, library, profile, thumbs, encoded_video, upload}. Sub-directory naming is important, and will break the app if not done correctly. I am calling the new parent dataset immich1 for clarity.
tank
└── configs
└── immich1
├── data [dataset]
├── backups [directory]
├── library [directory]
├── profile [directory]
├── thumbs [directory]
├── encoded_video [directory]
└── upload [directory]
└── db [dataset]
- Create new parent dataset (I am calling this
immich1for simplicity & clarity) with apps permission preset - Create two sub-datasets:
dataanddbwith apps permission preset - Use
rsyncto copy data from the old datasets to the new ones (assuming this is how your old dataset structure is named).rsyncwill create the new sub-directories when it completes the sync task. Run the following command in the TrueNAS shell asroot:rsync -avhz --progress /mnt/tank/configs/immich/backups/ /mnt/tank/configs/immich1/data/backups/ && \ rsync -avhz --progress /mnt/tank/configs/immich/library/ /mnt/tank/configs/immich1/data/library/ && \ rsync -avhz --progress /mnt/tank/configs/immich/profile/ /mnt/tank/configs/immich1/data/profile/ && \ rsync -avhz --progress /mnt/tank/configs/immich/thumbs/ /mnt/tank/configs/immich1/data/thumbs/ && \ rsync -avhz --progress /mnt/tank/configs/immich/video/ /mnt/tank/configs/immich1/data/encoded-video/ && \ rsync -avhz --progress /mnt/tank/configs/immich/uploads/ /mnt/tank/configs/immich1/data/upload/ && \ rsync -avhz --progress /mnt/tank/configs/immich/db/ /mnt/tank/configs/immich1/db/ - Edit Immich app
a. Scroll down to Storage Configuration and uncheck the box Use Old Storage Configuration (Deprecated)
b. Set the Data Storage to the new dataset/mnt/tank/immich1/data
c. Set the Postgres Data Storage to the new dataset/mnt/tank/immich1/dband be sure to check the Automatic Permissions checkbox
d. Click the blue Update button - Once all running, you can remove the old dataset
immich
¶ 4 · Picking the right CLIP model
Immich's documentation is very thorough regarding this so you should just read from there.
Many users don't even know that they can change the model and that it will impact their users significantly, especially if they are not English speakers.
Main things you want to pay attention to is if you need Multilingual model and model size so you are sure it will fit inside your GPU.
Immich team also provided a list of languages that are supported by the Multilingual models and how well they perform.
nllbmodels expect the search query to be in the language specified in the user settingsxlmandsiglip2models understand search text regardless of the current language setting
4 · Video