TrueNAS AppsTrueNAS Apps: Tutorials
Application maintenance is independent from TrueNAS version release cycles.
App versions, features, options, and installation behavior at time of access might vary from documented tutorials and UI reference.

Photoprism

The TrueNAS Photoprism app provides an efficient way to install, manage, and utilize the various capabilities of Photoprism. TrueNAS deploys the Photoprism app in a Docker container using Docker Compose. After successfully deploying the app, you can access the Photoprism web interface from TrueNAS. The Photoprism interface allows you to organize, search, and share your photos with advanced features like AI-based image classification, facial recognition, and geotagging. You can also manage photo collections, create albums, and utilize powerful search tools to find specific images based on metadata and tags.

Before You Begin

Prepare TrueNAS before installing Photoprism by:

  • Set a pool for applications to use if not already assigned.

    You can use either an existing pool or create a new one. TrueNAS creates the ix-apps (hidden) dataset in the pool set as the application pool. This dataset is internally managed, so you cannot use this as the parent when you create required application datasets.

    After setting the pool, the Installed Applications screen displays Apps Service Running on the top screen banner.

  • Locate the run-as user for the app.

    Take note of the run-as user for the app, shown on the app information screen in the Run As Context widget and in the Application Metadata widget on the Installed applications screen after the app fully deploys. The run-as user(s) get added to the ACL permissions for each dataset used as a host path storage volume.

Photoprism uses three datasets: import, storage, and originals. Ensure that your import dataset is configured with a functioning SMB share, as this is the dataset Photoprism uses to access and import your desired photos. Follow the instructions below in **Creating Datasets for Apps** to correctly set up these datasets.

  • Create datasets for the storage volumes for the app.

    Do not create encrypted datasets for apps if not required! Using an encrypted dataset can result in undesired behaviors after upgrading TrueNAS when pools and datasets are locked. When datasets for the containers are locked, the container does not mount, and the apps do not start. To resolve issues, unlock the dataset(s) by entering the passphrase/key to allow datasets to mount and apps to start.

    Go to Datasets and select the pool or dataset where you want to place the dataset(s) for the app. For example, /tank/apps/appName.

Create a parent dataset, such as appName, and then the storage datasets (config and data) under it. Select apps as the Dataset Preset for these datasets. You can modify the dataset ACLs at the time of creation, or modify them later when adding them in the app.

  • (Optional) Create a new TrueNAS user account to manage this application. When creating a new user account to manage this application or using an existing TrueNAS administrator account, enable sudo permissions for that TrueNAS user account, select Create New Primary Group, and add the appropriate group in the Auxiliary Group for the type of user you want to create. Make note of the UID for the new user to add in the installation wizard.

    Add the user ID to the dataset ACL permissions when setting up app storage volumes in the Install app wizard.

Installing the Application

This basic procedure covers the required Photoprism app settings. For optional settings, see Understanding App Installation Wizard Settings.

You can have multiple deployments of the same app (for example, two or more from the stable or enterprise trains, or a combination of the stable and enterprise trains).

Naming Multiple App Deployments

Each deployment of the same app requires a unique name. App names can include numbers, dashes, or underscores (for example, syncthing2, syncthing-test, syncthing_1, minio2, etc.).

Use a consistent file-naming convention to avoid conflict situations where data does not or cannot synchronize because of file name conflicts. Path and file names in apps are case-sensitive. For example, a file named MyData.txt is not the same as the mydata.txt file in Syncthing.

Go to Apps, click on Discover Apps, and locate the Photoprism widget by either scrolling down to it or begin typing the name into the search field. To locate the Photoprism app widget, begin typing Photoprism into the search field to show app widgets matching the search input.

Example of Locating an App Widget
Figure 3: Example of Locating an App Widget

If this is the first application installed, TrueNAS displays a dialog about configuring apps.

Configuring Apps Dialog

Click Confirm then Agree to close the dialog and open the application details screen.

If not the first time installing apps the dialog does not show, click on the widget to open the app information screen.

Click Install to open the Photoprism installation wizard.

Application configuration settings are grouped into several sections, each explained below in Understanding App Installation Wizard Settings. To find specific fields begin typing in the Search Input Fields search field to show the section or field, scroll down to a particular section, or click on the section heading in the list of sections on the upper-right of the wizard screen.

Install Photoprism Screen
Figure 5: Install Photoprism Screen

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 shows an update badge and the Application Info widget on the Installed applications screen shows the Update button.

Enter the Photoprism Configuration settings and enter an Admin Password.

The TrueNAS app is configured with all the required environment variables, but if you want to further customize the container, click Add to the right of Additional Environment Variables for each to enter the variable(s) and values(s).

(Optional) If you created a new user to administer apps, enter that user ID in the user and group fields. See User and Group Configuration and Network Configuration for more details.

Leave Host Network unselected.

Add your Storage Configuration settings.

Set Host Path (Path that already exists on the system) in Type for Photoprism Import Storage. Select Enable ACL, and then enter or browse to select the import dataset to populate the Host Path field. This is the dataset that should have a usable SMB share configured.

Add Photoprism Data Storage
Figure 6: Add Photoprism Data Storage

Select Add to the right of ACL Entries for each user or group entry you want to add. For example, add the 568 user and 0, and give each FULL_CONTROL Access.

Repeat the above storage configuration steps for the Photoprism Storage and Photoprism Originals Storage options, ensuring that your storage and originals datasets are set as the Host Path (Path that already exists on the system) for each configuration.

Select Force Flag.

See Storage Configuration Settings below for more information.

Accept the defaults in Resources Configuration, and select the GPU option if applicable.

Click Install. A progress dialog displays before switching to the Installed applications screen. The Installed screen displays with the nextcloud app in the Deploying state. Status changes to Running when ready to use.

Photoprism Installed
Figure 7: Photoprism Installed

Click Web UI on the Application Info widget to open the Photoprism web portal sign-in screen.

Sign in using the admin username and the password you set when configuring Photoprism.

Photoprism Sign In Screen
Figure 8: Photoprism Sign In Screen
Photoprism Dashboard
Figure 9: Photoprism Dashboard

Understanding App Installation Wizard Settings

The following section provides more detailed explanations of the settings in each section of the Install Photoprism installation wizard.

Application Name Settings

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 shows an update badge and the Application Info widget on the Installed applications screen shows the Update button.

Photoprism Configuration Settings

Photoprism configuration settings include setting up credentials, APT packages (previously referred to as the commands), the host IP and port, data directory path, upload limits, execution times, memory limits and cache memory consumption, adding a cron job with schedule, and adding additional environment variables.

If you have an existing Photoprism account, add the credential for that account in the Admin Password field. If you do not have an existing account, enter the name and password you want to use to create the Photoprism login credentials.

Adding Environment Variables

The app wizard is configured with all settings required to deploy the container, but you can add additional settings if you want to further customize the app in TrueNAS.

Click Add to the right of Environmental Variables to show a set of fields to configure the application with additional variables.

You can add environment variables to the app configuration after deploying it. Click Edit on the Application Info widget for the app found on the Installed Application screen to open the edit screen.

Refer to Photoprism documentation for more information on environment variables.

User and Group Configuration

Some TrueNAS apps have predefined run-as user and group IDs. These assignments vary based on the app train and other variables such as installing but not running as the root user.

Default user and group IDs are:

  • 568 (apps user), used in some community apps and all apps in the enterprise train
  • 0 (root user).

Accept the default user and group ID in the User and Group Configuration section or enter the user ID for a new TrueNAS user created to serve as the administrator for Photoprism.

Create any app administrator user before installing the application, and take note of the UID. Enter this user ID when configuring the user for the app and as the user when setting up storage volume permissions.

Network Configuration

The default web port for Photoprism is 20800.

We do not recommend selecting Host Network unless required for the specific application or workload. When required or strongly recommended for an application, TrueNAS typically enables host networking by default.

When host networking is disabled, specific ports from the container are exposed on the local network and mapped to a host port. This is the default Docker networking behavior. This approach provides better isolation, flexibility in port assignments, and improved security compared to enabling host networking.

Select Host Network to bypass port mapping, granting the container direct access network interfaces on the host. This can improve performance, especially in deployments with many users, and simplify network configuration, but compromises isolation and introduces the risk of port conflicts, limiting the ability to run multiple instances of the same app. For most deployments, default port mapping is more secure and versatile.

All TrueNAS apps are assigned default port numbers. Accept the default port numbers, but if changing port number assignments, enter a number within the range 1-65535, however, 0-1024 might require the application to have elevated privileges. Before changing default ports, refer to the TrueNAS default port list for a list of assigned and available port numbers.

The app does not require configuring advanced DNS options. Accept the default settings or click Add to the right of DNS Options to enter the option name and value.

To use a certificate, best practice is to create the self-signed certificate before you begin using the app installation wizard. If you did not create a certificate before starting the installation wizard you can select the default TrueNAS certificate and edit the app to change the certificate after deploying the application.

Select the certificate created in TrueNAS for the app from the Certificate dropdown list.

Storage Configuration

TrueNAS provides two options for storage volumes: ixVolumes and host paths.

Setting the Storage Volume Type

To allow TrueNAS to create the storage volume, leave Type set to ixVolume (Dataset created automatically by the system). This adds a storage volume for the application nested in the hidden ix-apps dataset, located on the pool selected as the apps pool. Using ixVolume is intended for a test deployment of an app but not for a full app deployment, as data does not persist for these volumes after deleting the app where a dataset does. Datasets make recovering, transferring, and accessing app configuration, user, or other data possible where ixVolumes do not.

To use an existing dataset, which is the recommended option, set Type to Host Path (Path that already exists on the system).

If the install wizard shows a Mount Path, either accept the default value or enter the correct mount path. For example, if the dataset name is data, enter /data as the mount path.

During this step, ensure that the import dataset is configured with an SMB share and selected as the host path for the Photoprism Import Storage Type, as this is the dataset Photoprism utilizes for the import process.

Select Enable ACL to define ACL permissions and populate the Host Path field by either entering or browsing to and selecting the dataset location. Populating the Host Path with the dataset location and then selecting Enable ACL clears the values, so we recommend selecting Enable ACL before entering the host path.

Repeat the above for each required dataset.

You can add extra storage volumes at the time of installation or edit the application after it deploys. Stop the app before editing settings.

Setting Dataset ACL Permissions

You can configure ACL permissions for the required dataset in the Install Photoprism wizard, or from the Datasets screen any time after adding the datasets.

Select Enable ACL to show the ACL and ACE Entries options. Configure ACE entries for each UID and/or GID you recorded from the Run As Context widget in Before You Begin.

Configuring ACE Entries

Enter or browse to select the dataset and populate Host Path.

Next, click Add to the right of ACL Entries to show the permissions settings. Set ID Type to Entry is for a USER or Entry is for a GROUP. If you configured a group in TrueNAS that you want to give access to instead of a single user, set the ID to the group option and enter the GID for that group.

Enter the UID and/or GID as one of the following:

  • The default app user:
    • 568 for apps in all trains if the app can run as any non-root user.
    • 999 for all postgres storage volumes.
    • 0 if running as root.
    • 473 for MinIO app in the stable train.
  • The run-as-user UID set as a default for the app. The run-as user shows on the app details screen in the Run As Content widget, and on the Installed application screen after the app deploys. You can refer to the tutorial for the app, or look in the questions.yaml file found in the GitHub repository for the application to find this UID/GID.
  • The user ID for the new or existing TrueNAS user added to serve as the administrator for the app.

If the app shows User and Group Configuration settings, the default UID shows on the screen. If not, choose the run-as user ID found in the Run As Content widget.

Use the default user ID 999 for all postgres storage volumes, not the run-as user.

If you created a new TrueNAS user to serve as the app administration user, add an entry record and enter the UID for this user in addition to the run-as user ID.

When adding the ACL entry for the run-as user, default user, and/or optional TrueNAS app administrator user, and postgres user ID, set the Access permissions level to FULL CONTROL.

Select Force Flag to apply the ACL even if the path has existing data. This allows you to update the app when an update is available.

Adding ACL Permissions from the Datasets Screen First, select the dataset row, and scroll down to the Permissions widget, and then click Edit to open the Edit ACL screen. Change the @owner and @group values from root to the administrative user for your TrueNAS system, and click apply for each. Next, add an ACL entry for the run-as user. Save the ACL before leaving the screen.

Mounting an SMB Share Storage Volume

TrueNAS Additional Storage options include the ability to mount an SMB share inside the container pod. The SMB share on your import dataset from prior steps does not require further configuration in this step.

Configuring Additional Storage Volumes

If you choose to configure additional storage volumes, click Add to the right of Additional Storage to show the Type field with three options:

  • HostPath (Path that already exists on the system)
  • ixVolume (Dataset created automatically by the system)
  • SMB/CIFS Share (Mounts a volume to a SMB share)

The host path option requires an existing dataset on the system. The SMB/CIFS share option shows settings for configuring an SMB share as a storage option.

Set Type an SMB/CIFS Share (Mounts a volume to a SMB share) to add an SMB share storage volume.

Select Read Only to make the storage volume read only.

Enter the path inside the container to mount the storage for the share volume in Mount Path.

Enter the server address for the SMB share in Server, the path to mount the SMB share in Path, and the share authentication user credentials in User and Password. (Optional) enter the share domain name in domain.

Permissions are currently limited to the permissions of the user that mounted the share.

Use the SMB option for data synchronization between a share and the app if the option shows on the screen. A present, only the Syncthing app includes this option.

Resources Configuration

Resources Configuration Settings
Figure 13: Resources Configuration 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 2 CPU cores and 4096 megabytes available memory. The application might use considerably less system resources.

To customize the CPU and memory allocated to the container the app uses, enter new CPU values as a plain integer value (letter suffix is not required). The default is 4096.

Accept the default value (4 Gb) allocated memory or enter a new limit in bytes. Enter a plain integer without the measurement suffix, for example, 129 not 129M or 123MiB.

GPU Configuration provides the option to enable GPU passthrough. Select Passthrough available (non-NVIDIA) GPUs or, if your system has an NVIDIA GPU device, select Use this GPU.

For more information on GPU passthrough, see TrueNAS Apps.