Skip to content

High performance self-hosted photo and video management solution.

docs: Update TrueNAS docs for TrueNAS SCALE 24.10 (#14067)

Nicholas Flamyc58bd307cee7
diff --git a/docs/docs/install/img/truenas01.png b/docs/docs/install/img/truenas01.png
index 81b0430a75..e648ab3734 100644
Binary files a/docs/docs/install/img/truenas01.png and b/docs/docs/install/img/truenas01.png differ
diff --git a/docs/docs/install/img/truenas02.png b/docs/docs/install/img/truenas02.png
index ae7d41e624..66f0dec7fa 100644
Binary files a/docs/docs/install/img/truenas02.png and b/docs/docs/install/img/truenas02.png differ
diff --git a/docs/docs/install/img/truenas03.png b/docs/docs/install/img/truenas03.png
index 90ff25b7ac..d9970f5aeb 100644
Binary files a/docs/docs/install/img/truenas03.png and b/docs/docs/install/img/truenas03.png differ
diff --git a/docs/docs/install/img/truenas04.png b/docs/docs/install/img/truenas04.png
index 281d02350a..45fa87e5e5 100644
Binary files a/docs/docs/install/img/truenas04.png and b/docs/docs/install/img/truenas04.png differ
diff --git a/docs/docs/install/img/truenas05.png b/docs/docs/install/img/truenas05.png
index 919b008030..0f9d6a835a 100644
Binary files a/docs/docs/install/img/truenas05.png and b/docs/docs/install/img/truenas05.png differ
diff --git a/docs/docs/install/img/truenas06.png b/docs/docs/install/img/truenas06.png
index 26cf06738a..3daf250e36 100644
Binary files a/docs/docs/install/img/truenas06.png and b/docs/docs/install/img/truenas06.png differ
diff --git a/docs/docs/install/img/truenas07.png b/docs/docs/install/img/truenas07.png
index 17943e5c81..946c1401ac 100644
Binary files a/docs/docs/install/img/truenas07.png and b/docs/docs/install/img/truenas07.png differ
diff --git a/docs/docs/install/img/truenas08.png b/docs/docs/install/img/truenas08.png
index 4c5a90be6b..4ace8b49ca 100644
Binary files a/docs/docs/install/img/truenas08.png and b/docs/docs/install/img/truenas08.png differ
diff --git a/docs/docs/install/img/truenas09.png b/docs/docs/install/img/truenas09.png
index 647c7295b4..41830fe9e6 100644
Binary files a/docs/docs/install/img/truenas09.png and b/docs/docs/install/img/truenas09.png differ
diff --git a/docs/docs/install/img/truenas10.png b/docs/docs/install/img/truenas10.png
new file mode 100644
index 0000000000..730685c309
Binary files /dev/null and b/docs/docs/install/img/truenas10.png differ
diff --git a/docs/docs/install/img/truenas11.png b/docs/docs/install/img/truenas11.png
new file mode 100644
index 0000000000..88c166aed3
Binary files /dev/null and b/docs/docs/install/img/truenas11.png differ
diff --git a/docs/docs/install/img/truenas12.png b/docs/docs/install/img/truenas12.png
new file mode 100644
index 0000000000..a107a85f24
Binary files /dev/null and b/docs/docs/install/img/truenas12.png differ
diff --git a/docs/docs/install/truenas.md b/docs/docs/install/truenas.md
index ffb559ed12..f35e9aa37a 100644
--- a/docs/docs/install/truenas.md
+++ b/docs/docs/install/truenas.md
@@ -7,7 +7,9 @@ sidebar_position: 80
:::note
This is a community contribution and not officially supported by the Immich team, but included here for convenience.
-**Please report issues to the corresponding [Github Repository](https://github.com/truenas/charts/tree/master/community/immich).**
+Community support can be found in the dedicated channel on the [Discord Server](https://discord.immich.app/).
+
+**Please report app issues to the corresponding [Github Repository](https://github.com/truenas/charts/tree/master/community/immich).**
:::
Immich can easily be installed on TrueNAS SCALE via the **Community** train application.
@@ -20,18 +22,26 @@ TrueNAS SCALE makes installing and updating Immich easy, but you must use the Im
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](/docs/install/environment-variables.md) documentation to see if you want to configure any during installation.
-You can configure environment variables at any time after deploying the application.
+Before installing the Immich app in SCALE, review the [Environment Variables](#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
-You can allow SCALE to create the datasets Immich requires automatically during app installation.
-Or before beginning app installation, [create the datasets](https://www.truenas.com/docs/scale/scaletutorials/storage/datasets/datasetsscale/) to use in the **Storage Configuration** section during installation.
-Immich requires seven datasets: **library**, **pgBackup**, **pgData**, **profile**, **thumbs**, **uploads**, and **video**.
-You can organize these as one parent with seven child datasets, for example `mnt/tank/immich/library`, `mnt/tank/immich/pgBackup`, and so on.
+Before beginning app installation, [create the datasets](https://www.truenas.com/docs/scale/scaletutorials/storage/datasets/datasetsscale/) 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.
+
+<img
+src={require('./img/truenas12.png').default}
+width="30%"
+alt="Immich App Widget"
+className="border rounded-xl"
+/>
:::info Permissions
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.
-The **library** dataset must have [ACL mode](https://www.truenas.com/docs/core/coretutorials/storage/pools/permissions/#access-control-lists) set to `Passthrough` if you plan on using a [storage template](/docs/administration/storage-template.mdx) 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 **uploads** to **library**, immich performs `chmod` internally and needs to be allowed to execute the command.
+If the **library** dataset uses ACL it must have [ACL mode](https://www.truenas.com/docs/core/coretutorials/storage/pools/permissions/#access-control-lists) set to `Passthrough` if you plan on using a [storage template](/docs/administration/storage-template.mdx) 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.](https://github.com/immich-app/immich/pull/13017)
:::
## Installing the Immich Application
@@ -47,6 +57,8 @@ className="border rounded-xl"
Click on the widget to open the **Immich** application details screen.
+<br/><br/>
+
<img
src={require('./img/truenas02.png').default}
width="100%"
@@ -56,9 +68,13 @@ className="border rounded-xl"
Click **Install** to open the Immich application configuration screen.
+<br/><br/>
+
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
+
<img
src={require('./img/truenas03.png').default}
width="100%"
@@ -66,133 +82,174 @@ alt="Install Immich Screen"
className="border rounded-xl"
/>
-Accept the default values in **Application Name** and **Version**.
-
-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.
-
-Accept the default port in **Web Port**.
-
-Immich requires seven storage datasets.
-You can allow SCALE to create them for you, or use the dataset(s) created in [First Steps](#first-steps).
-Select the storage options you want to use for **Immich Uploads Storage**, **Immich Library Storage**, **Immich Thumbs Storage**, **Immich Profile Storage**, **Immich Video Storage**, **Immich Postgres Data Storage**, **Immich Postgres Backup Storage**.
-Select **ixVolume (dataset created automatically by the system)** in **Type** to let SCALE create the dataset or select **Host Path** to use the existing datasets created on the system.
+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 defaults in Resources or change the CPU and memory limits to suit your use case.
+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.
-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**.
+### Immich Configuration
<img
-src={require('./img/truenas04.png').default}
-width="100%"
-alt="Immich Installed"
+src={require('./img/truenas05.png').default}
+width="40%"
+alt="Configuration Settings"
className="border rounded-xl"
/>
-Click **Web Portal** on the **Application Info** widget to open the Immich web interface to set up your account and begin uploading photos.
+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.
-:::tip
-For more information on how to use the application once installed, please refer to the [Post Install](/docs/install/post-install.mdx) guide.
-:::
+Untick **Enable Machine Learning** if you will not use face recognition, image search, and smart duplicate detection.
-## Editing Environment Variables
+Accept the default option or select the **Machine Learning Image Type** for your hardware based on the [Hardware-Accelerated Machine Learning Supported Backends](/docs/features/ml-hardware-acceleration.md#supported-backends).
-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.
-The settings on the edit screen are the same as on the install screen.
-You cannot edit **Storage Configuration** paths after the initial app install.
+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`.
-Click **Update** to save changes.
-TrueNAS automatically updates, recreates, and redeploys the Immich container with the updated environment variables.
+The **Redis Password** should be set to a custom value using only the characters `A-Za-z0-9`.
-## Updating the App
+Accept the **Log Level** default of **Log**.
-When updates become available, SCALE alerts and provides easy updates.
-To update the app to the latest version, click **Update** on the **Application Info** widget from the **Installed Applications** screen.
+Leave **Hugging Face Endpoint** blank. (This is for downloading ML models from a different source.)
-Update opens an update window for the application that includes two selectable options, Images (to be updated) and Changelog. Click on the down arrow to see the options available for each.
+Leave **Additional Environment Variables** blank or see [Environment Variables](#environment-variables) to set before installing.
-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.
+### Network Configuration
-## Understanding Immich Settings in TrueNAS SCALE
+<img
+src={require('./img/truenas06.png').default}
+width="40%"
+alt="Networking Settings"
+className="border rounded-xl"
+/>
-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 port `30041` in **WebUI Port** or enter a custom port number.
+:::info Allowed Port Numbers
+Only numbers within the range 9000-65535 may be used on SCALE versions below TrueNAS Scale 24.10 Electric Eel.
-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.
+Regardless of version, to avoid port conflicts, don't use [ports on this list](https://www.truenas.com/docs/references/defaultports/).
+:::
-### Immich Configuration Settings
+### Storage Configuration
-You can accept the defaults in the **Immich Configuration** settings, or enter the settings you want to use.
+Immich requires seven storage datasets.
<img
-src={require('./img/truenas05.png').default}
-width="100%"
-alt="Configuration Settings"
+src={require('./img/truenas07.png').default}
+width="20%"
+alt="Configure Storage ixVolumes"
className="border rounded-xl"
/>
-Accept the default setting 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.
+:::note Default Setting (Not recommended)
+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)
+:::
-You can enter a **Public Login Message** to display on the login page, or leave it blank.
+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](#setting-up-storage-datasets): **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`.
-### Networking Settings
+<img
+src={require('./img/truenas08.png').default}
+width="40%"
+alt="Configure Storage Host Paths"
+className="border rounded-xl"
+/>
+The image above has example values.
-Accept the default port numbers in **Web Port**.
-The SCALE Immich app listens on port **30041**.
+<br/>
-Refer to the TrueNAS [default port list](https://www.truenas.com/docs/references/defaultports/) for a list of assigned port numbers.
-To change the port numbers, enter a number within the range 9000-65535.
+### Additional Storage [(External Libraries)](/docs/features/libraries)
<img
-src={require('./img/truenas06.png').default}
-width="100%"
-alt="Networking Settings"
+src={require('./img/truenas10.png').default}
+width="40%"
+alt="Configure Storage Host Paths"
className="border rounded-xl"
/>
-### Storage Settings
+You may configure [External Libraries](/docs/features/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.
+
+<!-- A section for Labels would go here but I don't know what they do. -->
-You can install Immich using the default setting **ixVolume (dataset created automatically by the system)** or use the host path option with datasets [created before installing the app](#first-steps).
+### Resources Configuration
<img
-src={require('./img/truenas07.png').default}
-width="100%"
-alt="Configure Storage ixVolumes"
+src={require('./img/truenas09.png').default}
+width="40%"
+alt="Resource Limits"
className="border rounded-xl"
/>
-Select **Host Path (Path that already exists on the system)** to browse to and select the datasets.
+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.
+
+:::info Older SCALE Versions
+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](/docs/features/hardware-transcoding) and/or [Hardware-Accelerated Machine Learning](/docs/features/ml-hardware-acceleration.md). More info: [GPU Passtrough Docs for TrueNAS Apps](https://www.truenas.com/docs/truenasapps/#gpu-passthrough)
+
+### 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**.
<img
-src={require('./img/truenas08.png').default}
+src={require('./img/truenas04.png').default}
width="100%"
-alt="Configure Storage Host Paths"
+alt="Immich Installed"
className="border rounded-xl"
/>
-### Resource Configuration Settings
+Click **Web Portal** on the **Application Info** widget to open the Immich web interface to set up your account and begin uploading photos.
+
+:::tip
+For more information on how to use the application once installed, please refer to the [Post Install](/docs/install/post-install.mdx) guide.
+:::
+
+## Edit App Settings
-Accept the default values in **Resources Configuration** or enter new CPU and memory values
-By default, this application is limited to use no more than 4 CPU cores and 8 Gigabytes available memory. The application might use considerably less system resources.
+- 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](/docs/install/environment-variables) by clicking **Add** on the **Additional Environment Variables** option and filling in the **Name** and **Value**.
<img
-src={require('./img/truenas09.png').default}
-width="100%"
-alt="Resource Limits"
+src={require('./img/truenas11.png').default}
+width="40%"
+alt="Environment Variables"
className="border rounded-xl"
/>
-To customize the CPU and memory allocated to the container Immich uses, enter new CPU values as a plain integer value followed by the suffix m (milli).
-Default is 4000m.
+:::info
+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](#edit-app-settings).
+
+Some examples are: `IMMICH_VERSION`, `UPLOAD_LOCATION`, `DB_DATA_LOCATION`, `TZ`, `IMMICH_LOG_LEVEL`, `DB_PASSWORD`, `REDIS_PASSWORD`.
+:::
-Accept the default value 8Gi allocated memory or enter a new limit in bytes.
-Enter a plain integer followed by the measurement suffix, for example 129M or 123Mi.
+## Updating the App
-Systems with compatible GPU(s) display devices in **GPU Configuration**.
-See [Managing GPUs](https://www.truenas.com/docs/scale/scaletutorials/systemsettings/advanced/managegpuscale/) for more information about allocating isolated GPU devices in TrueNAS SCALE.
+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.