TrueNAS SCALE [Community]
This is a community contribution and not officially supported by the Immich team, but included here for convenience.
Community support can be found in the dedicated channel on the Discord Server.
Please report app issues to the corresponding Github Repository.
Immich can easily be installed on TrueNAS SCALE via the Community train application. Consider reviewing the TrueNAS Apps tutorial if you have not previously configured applications on your system.
TrueNAS SCALE makes installing and updating Immich easy, but you must use the Immich web portal and mobile app to configure accounts and access libraries.
First Steps
The Immich app in TrueNAS SCALE installs, completes the initial configuration, then starts the Immich web portal. When updates become available, SCALE alerts and provides easy updates.
Before installing the Immich app in SCALE, review the Environment Variables documentation to see if you want to configure any during installation. You may also configure environment variables at any time after deploying the application.
Setting up Storage Datasets
Before beginning app installation, create the datasets to use in the Storage Configuration section during installation.
Immich requires seven datasets: library, upload, thumbs, profile, video, backups, and pgData.
You can organize these as one parent with seven child datasets, for example /mnt/tank/immich/library, /mnt/tank/immich/upload, and so on.
The pgData dataset must be owned by the user netdata (UID 999) for postgres to start. The other datasets must be owned by the user root (UID 0) or a group that includes the user root (UID 0) for immich to have the necessary permissions.
If the library dataset uses ACL it must have ACL mode set to Passthrough if you plan on using a storage template and the dataset is configured for network sharing (its ACL type is set to SMB/NFSv4). When the template is applied and files need to be moved from upload to library, immich performs chmod internally and needs to be allowed to execute the command. More info.
Installing the Immich Application
To install the Immich application, go to Apps, click Discover Apps, either begin typing Immich into the search field or scroll down to locate the Immich application widget.
Click on the widget to open the Immich application details screen.
Click Install to open the Immich application configuration screen.
Application configuration settings are presented in several sections, each explained below. To find specific fields click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.
Application Name and Version
Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.
Accept the default version number in Version. When a new version becomes available, the application has an update badge. The Installed Applications screen shows the option to update applications.
Immich Configuration
Accept the default value in Timezone or change to match your local timezone.
Timezone is only used by the Immich exiftool microservice if it cannot be determined from the image metadata.
Untick Enable Machine Learning if you will not use face recognition, image search, and smart duplicate detection.
Accept the default option or select the Machine Learning Image Type for your hardware based on the Hardware-Accelerated Machine Learning Supported Backends.
Immich's default is postgres but you should consider setting the Database Password to a custom value using only the characters A-Za-z0-9.
The Redis Password should be set to a custom value using only the characters A-Za-z0-9.
Accept the Log Level default of Log.
Leave Hugging Face Endpoint blank. (This is for downloading ML models from a different source.)
Leave Additional Environment Variables blank or see Environment Variables to set before installing.
Network Configuration
Accept the default port 30041 in WebUI Port or enter a custom port number.
Only numbers within the range 9000-65535 may be used on SCALE versions below TrueNAS Scale 24.10 Electric Eel.
Regardless of version, to avoid port conflicts, don't use ports on this list.
Storage Configuration
Immich requires seven storage datasets.
The default setting for datasets is ixVolume (dataset created automatically by the system) but this results in your data being harder to access manually and can result in data loss if you delete the immich app. (Not recommended)
For each Storage option select Host Path (Path that already exists on the system) and then select the matching dataset created before installing the app: Immich Library Storage: library, Immich Uploads Storage: upload, Immich Thumbs Storage: thumbs, Immich Profile Storage: profile, Immich Video Storage: video, Immich Backups Storage: backups, Postgres Data Storage: pgData.
The image above has example values.
Additional Storage (External Libraries)
You may configure External Libraries by mounting them using Additional Storage. The Mount Path is the loaction you will need to copy and paste into the External Library settings within Immich. The Host Path is the location on the TrueNAS SCALE server where your external library is located.
Resources Configuration
Accept the default CPU limit of 2 threads or specify the number of threads (CPUs with Multi-/Hyper-threading have 2 threads per core).
Accept the default Memory limit of 4096 MB or specify the number of MB of RAM. If you're using Machine Learning you should probably set this above 8000 MB.
Before TrueNAS SCALE version 24.10 Electric Eel:
The CPU value was specified in a different format with a default of 4000m which is 4 threads.
The Memory value was specified in a different format with a default of 8Gi which is 8 GiB of RAM. The value was specified in bytes or a number with a measurement suffix. Examples: 129M, 123Mi, 1000000000
Enable GPU Configuration options if you have a GPU that you will use for Hardware Transcoding and/or Hardware-Accelerated Machine Learning. More info: GPU Passtrough Docs for TrueNAS Apps
Install
Finally, click Install. The system opens the Installed Applications screen with the Immich app in the Deploying state. When the installation completes it changes to Running.
Click Web Portal on the Application Info widget to open the Immich web interface to set up your account and begin uploading photos.
For more information on how to use the application once installed, please refer to the Post Install guide.
Edit App Settings
- Go to the Installed Applications screen and select Immich from the list of installed applications.
- Click Edit on the Application Info widget to open the Edit Immich screen.
- Change any settings you would like to change.
- The settings on the edit screen are the same as on the install screen.
- Click Update at the very bottom of the page to save changes.
- TrueNAS automatically updates, recreates, and redeploys the Immich container with the updated settings.
Environment Variables
You can set Environment Variables by clicking Add on the Additional Environment Variables option and filling in the Name and Value.
Some Environment Variables are not available for the TrueNAS SCALE app. This is mainly because they can be configured through GUI options in the Edit Immich screen.
Some examples are: IMMICH_VERSION, UPLOAD_LOCATION, DB_DATA_LOCATION, TZ, IMMICH_LOG_LEVEL, DB_PASSWORD, REDIS_PASSWORD.
Updating the App
When updates become available, SCALE alerts and provides easy updates. To update the app to the latest version:
- Go to the Installed Applications screen and select Immich from the list of installed applications.
- Click Update on the Application Info widget from the Installed Applications screen.
- This opens an update window with some options
- You may select an Image update too.
- You may view the Changelog.
- Click Upgrade to begin the process and open a counter dialog that shows the upgrade progress.
- When complete, the update badge and buttons disappear and the application Update state on the Installed screen changes from Update Available to Up to date.