Community Apps

Documentation for applications within the Community train is created and maintained by members of the TrueNAS community. The TrueNAS Documentation Hub hosts but does not validate or maintain articles within this section.

Community contributions are highly encouraged! Please see Contributing to TrueNAS Application Documentation to learn how you can assist.

We welcome community contributions to keep this documentation current! Click Edit Page in the top right corner to propose changes to this article. See Updating Content for more information.

Community Supported

Stable and Community train apps receive Community Support only and are not supported by the official TrueNAS Support team. See the App Support Definitions for more details.

Below, you’ll find additional details about TrueNAS apps administration, including best practices and in-depth insights.

App Dataset Types

ix-apps Dataset

TrueNAS 24.10 and newer creates a hidden ix-apps dataset to store Docker configuration, catalog data, and app metadata. This dataset is physically located on the selected pool for apps and mounted at /mnt/.ix-apps. The ix-apps dataset is internally managed by TrueNAS and hidden to prevent user misconfiguration. Any modification of it can result in instability and loss of app functionality.

Do not include the ix-apps dataset inside of an SMB or NFS share.

The ix-apps dataset does not inherit encryption if an encrypted pool is selected as the pool for applications.

Back up and restore functionality as well as migration of the ix-apps dataset from one apps pool to another are not currently supported by the TrueNAS interface. Support for these features is planned for a future TrueNAS release version.

TrueNAS 24.04 and earlier versions stored applications data in an ix-applications dataset on the configured apps pool. Systems with applications deployed that upgrade from earlier releases to 24.10 retain the ix-applications dataset. During the migration process, 24.10 reads the stored Kubernetes app data in the ix-applications dataset, ports them to Docker, and saves them in the new ix-apps dataset. App storage ixVolumes present in ix-applications are cloned under the ix-apps dataset and promoted.

The app data retained in ix-applications enables TrueNAS to revert to 24.04 with functional applications. TrueNAS 24.10 or newer does not use app data in the ix-applications dataset. It can be safely removed after fully migrating to 24.10, but apps do not function if reverted to 24.04 without the ix-applications dataset.

ixVolume Datasets

ixVolume datasets allow TrueNAS to automatically create an app storage path inside the hidden ix-apps dataset.

ixVolumes are typically created with appropriate permissions to deploy the application. If needed, use Enable ACL in Storage Configuration to configure ACL entries for an ixVolume.

ixVolumes are not recommended for permanent storage volumes, they are intended for use as rapid storage for a test deployment of the container. Though they can simplify test deployment, ixVolumes complicate tasks like app data backup. We recommend manually adding datasets and configuring container storage volumes with the host path option.

Host Path Datasets

Host Paths allow users to mount existing TrueNAS datasets to paths within the app container. Create the TrueNAS dataset(s) before assigning them as host paths within the app installation screen.

Mounting a host path does not automatically configure appropriate permissions to deploy the application. Use Enable ACL in Storage Configuration to configure ACL entries for each host path.

Configuring Host Path ACL Entries

ixVolumes do not require setting up an Access Control List (ACL) and Access Control Entry (ACE) in the app configuration settings, but host paths do. After entering the path inside the container in Mount Path, select Enable ACL. Browse to or enter the path to the dataset in Host Path. Click Add next to ACL Entries to display a set of ACE fields. Use ID Type to select whether the ACE is for a user or a group. Enter the UID or GID in ID and adjust the permissions level in Access.

Refer to the app Run As Context on the app details screen for default ID requirements. A user or group ID does not need to exist locally on TrueNAS or match the name configured in the container. You do not need to add these users in Credentials to add the UID/GID as an ACE for the host path dataset.

If the app has run-as users, you need to add an ACL entry for these users on the appropriate host path(s). For example, an app with multiple containers might include run-as users for the app itself, a redis container, and a postgres container. In this case, add an ACE for the app run-as user to hostpath(s) for the app itself, add an ACE for the redis run-as user to the redis storage hostpath, and select the Automatic Permissions option to add permissions for the postgres run-as user to the postgres storage dataset. Failing to configure host path ACLs prevents the app from deploying!

Select Force Flag to allow TrueNAS to update the application to the next version. This allows TrueNAS to write ACL entries to the storage volume if it has existing data in it. Force Flag is required to edit or update an existing application.

Postgres Datasets

When storage volumes include a postgres dataset, do not select Enable ACL to configure permissions. Instead, proceed with entering or browsing to select the dataset to populate the Host Path field, and then select the Automatic Permissions option. This configures permissions for the postgres dataset and, if configured, the parent dataset used to organize required datasets for the app.

As with other host path storage volumes, you can create a dataset when entering the host path.

You can use Enable ACL to manually configure ACL permissions for the postgres dataset and a parent dataset, but getting the ACL permissions right is involved and if not correctly configured, you are likely to receive errors after clicking Install on the application installation wizard. Additionally, the Automatic Permissions option does not show on the wizard screen.

Why should I use Automatic Permissions?

Before the Automatic Permissions option, users deploying apps with postgres datasets receive errors or tracebacks prompting them to add built-in users such as the netdata user and others. These built-in users show in the Run As Context widget on the information screen for each app. These users are not added as users through the Credentials > Users > Add User screen and might not show on the list of users. They are run-as users for the app that should be added as ACL entries to the ACL for the dataset host path.

Additionally, the parent dataset created for app datasets nested as children under the parent has different ACL requirements that must be set up when creating the parent dataset. To simplify the process and avoid issues with normal ACL behaviors, use the Automatic Permissions option which properly configures the ACE entries for parent and postgres datasets, and only on empty directories so configure this before using the app to store data.

You can reverse setting the host path with Enable ACL selected and configure ACE entries before you click Install to finish the installation. At this point, you should not receive the error again. If you do not reverse the Enable ACL selection and click Install, when you receive the error, untangling permission issues for the parent and postgres datasets becomes complicated. We recommend you use the Automatic Permissions option.

SMB Share Volumes

Some app storage configurations include the SMB/CIFS Share option. Use this option to mount an existing SMB share using a Docker volume.

Tmpfs Directories

Some app storage configurations include the Tmpfs (Temporary directory created on the RAM) option. Use this option to configure a memory-backed temporary directory, such as for transcoding. See the Docker tmpfs documentation for more information.

Custom Apps

TrueNAS includes the ability to install third-party apps in Docker containers that allow users to deploy apps not included in the catalog. Generally, any container that follows the Open Container Initiative specifications can be deployed.

To deploy a custom application, go to Apps and click Discover Apps. Click Custom App to open the Install iX App screen with a guided installation wizard. Click more_vert > Install via YAML to open the Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.

TrueNAS also allows users to convert already installed apps into custom applications. Select the app you wish to convert, and then click the triple dot icon button next to Edit to open the menu containing Update and Convert to custom app options.

Select Convert to custom app from the dropdown list, then select Confirm to convert the app.

After converting, clicking the Edit button within the Application Info window opens an Edit App YAML window. This gives users the option to enter a custom app configuration.

We recommend setting up your storage, user, or other configuration requirements before beginning deployment. You should have access to information such as:

• The path to the image repository
• Any container entrypoint commands or arguments
• Container environment variables
• Network settings
• IP addresses and DNS nameservers
• Container and node port settings
• Storage volume locations
• Certificates for image security

The installation wizard configuration sections vary by application, with some including more configuration areas than others. Click Install to review settings ahead of time to check for required settings. Click Discover on the breadcrumb at the top of the installation wizard to exit the screen without saving and until you are ready return and configure the app settings.

All apps in the stable train, some community train apps, and all apps in the enterprise train generally include these basic setting sections:

• Application Name shows the default name for the application.

  If deploying more than one instance of the application, you must change the default name.

  Do not change the Version number for official apps or those included in a TrueNAS catalog. When a new version becomes available, the Installed application screen shows an update alert, and the Application Info widget shows an Update button. Updating the app changes the version to the currently available release.

• Application Configuration shows required and optional settings for the app. Typical settings include user credentials, environment variables, additional argument settings, the name of the node, or even sizing parameters.

• User and Group Configuration shows the user and group ID for the default user assigned to the app. If not using a default user and group provided, add a new user to manage the application before using the installation wizard, then enter the UID in both the user and group fields. This section is not always included in app installation wizards.

• Network Configuration shows network settings the app needs to communicate with TrueNAS and the Internet. Settings include the default port assignment, host name, IP addresses, and other network settings.

  If changing the port number to something other than the default setting, refer to Default Ports for a list of used and available port numbers.

  Some network configuration settings include the option to add a certificate. Create the certificate authority and certificate before using the installation wizard if using a certificate is required for the application.

• Storage Configuration shows options to configure storage for the application. Storage configuration can include the primary data mount volume, a configuration volume, postgres volumes, and an option to add additional storage volumes. The primary mount volumes have two options:

  • ixVolume creates a storage volume inside the hidden ix-apps dataset. This is the default setting.
  • Host Path allows you to select an existing dataset created for the application. It shows additional fields for selecting the path to the dataset and adding the mount point.

  ixVolumes are not recommended for permanent storage volumes, they are intended for rapid storage for a test deployment of the container. We recommend adding datasets and configuring the container storage volumes with the host path option.

  Host paths add existing dataset(s) as the storage volumes. You can configure the datasets before beginning the app installation using the wizard or click Create Dataset in the app install wizard.

  Some applications require specific storage volumes for configuration and other data. Apps with these requirements indicate this in the wizard UI or details screen. Refer to tutorials for specifics.

  Depending on the app, storage options include:

  • ixVolume
  • Host path
  • SMB share
  • Tmpfs (Temporary directory created on the RAM)

  See Understanding App Storage Volumes for more information.

  After configuring required storage volumes you can add additional storage volumes. To configure additional storage volumes for the application, click Add to select the type of storage to configure.

  An SMB share option allows you to mount an SMB share as a Docker volume for the application to use. If the application requires specific datasets or you want to allow SMB share access, configure the dataset(s) and SMB share before using the installation wizard.

  ixVolumes do not require setting up an Access Control List (ACL) and Access Control Entry (ACE) in the app configuration settings, but host paths do. After entering the path inside the container in Mount Path, select Enable ACL. Browse to or enter the path to the dataset in Host Path. Click Add next to ACL Entries to display a set of ACE fields. Use ID Type to select whether the ACE is for a user or a group. Enter the UID or GID in ID and adjust the permissions level in Access.

  Refer to the app Run As Context on the app details screen for default ID requirements. A user or group ID does not need to exist locally on TrueNAS or match the name configured in the container. You do not need to add these users in Credentials to add the UID/GID as an ACE for the host path dataset.

  If the app has run-as users, you need to add an ACL entry for these users on the appropriate host path(s). For example, an app with multiple containers might include run-as users for the app itself, a redis container, and a postgres container. In this case, add an ACE for the app run-as user to hostpath(s) for the app itself, add an ACE for the redis run-as user to the redis storage hostpath, and select the Automatic Permissions option to add permissions for the postgres run-as user to the postgres storage dataset. Failing to configure host path ACLs prevents the app from deploying!

  Select Force Flag to allow TrueNAS to update the application to the next version. This allows TrueNAS to write ACL entries to the storage volume if it has existing data in it. Force Flag is required to edit or update an existing application.

• Resources Configuration shows CPU and memory settings for the container pod. In most cases, you can accept the default settings, or you can change these settings to limit the system resources available to the application.

  Some apps include GPU settings if the app allows or requires GPU passthrough.

After installing an app, you can modify most settings by selecting the app on the Installed applications screen and then clicking the Edit button on the Application Info widget for that app.

For more detailed information on application install wizard settings, see each of the tutorials provided in this section.