TrueNAS 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.

Enterprise Apps

11 minute read.

Last Modified 2024-12-02 09:57 EST

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.

TrueNAS Enterprise
TrueNAS Enterprise-licensed systems do not have applications available by default. To enable applications as part of the Enterprise license, consult with iXsystems.
Only install qualified applications from the Enterprise applications train with the assistance of iXsystems Support.
Contacting Support
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
iXsystems Customer Support
Support Portal https://support.ixsystems.com
Email support@ixsystems.com
Telephone and Other Resources https://www.ixsystems.com/support/

iXsystems Customer Support
Support Portal	https://support.ixsystems.com
Email	support@ixsystems.com
Telephone and Other Resources	https://www.ixsystems.com/support/

TrueNAS is certified with leading hypervisors and backup solutions to streamline storage operations and ensure compatibility with your existing IT infrastructure. TrueNAS Enterprise storage appliances deliver a wide range of features and scalability for virtualization and private cloud environments, with the ability to create off-site backups with scheduled sync and replication features. TrueNAS applications expand the capabilities of your system by adding third-party software but can add significant risk to system stability and security.

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

App Pool Selection

We recommend users keep the container use case in mind when choosing an applications pool. Select a pool with enough space for all the application containers you intend to use.

For stability, we recommend using SSD storage for the apps pool.

TrueNAS 24.10 and newer creates a hidden ix-apps dataset on the apps pool and mounts the hidden directory at /mnt/.ix-apps. The ix-apps dataset does not inherit encryption if an encrypted pool is selected as the pool for applications. See App Dataset Types for more information.

App Dataset Types

ix-apps Dataset

TrueNAS 24.10 and newer creates a hidden ix-apps dataset, mounted at /mnt/.ix-apps, to store Docker configuration, catalog data, and app metadata. 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

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 to grant an ACE. Failing to configure host path ACLs prevents the app from deploying!

Select Force Flag in ACL Options. 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.

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

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 > Install via YAML to open the Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.

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

App Directory Services

TrueNAS allows configuring an Active Directory or LDAP server to handle authentication and authorization services, domain, and other account settings. Identify your existing Kerberos realm and keytab information. You might need to supply your LDAP server host name, LDAP server base and bind distinguished names (DN), and the bind password.

TrueNAS is configured with default port numbers, but you can change these. Before making a port number change, refer to the Default Ports for a list of used and available ports before changing default port assignments.

iXsystems Support can assist Enterprise customers with configuring directory service settings in TrueNAS with the information customers provide, but they do not configure customer Active Directory system settings.

For more information on configuring general application functions and installation wizard screens, see TrueNAS Apps.

Understanding App Install Wizard Settings

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 must configure the datasets before beginning the app installation using the wizard.
The ix-apps dataset is for internal use only.
TrueNAS systems with applications deployed that upgrade from earlier releases to 24.10 continue to see the ix-Applications dataset on the pool chosen for applications to use. New installs or systems upgrading where applications are not deployed and a pool is not chosen for apps use the hidden ix-apps dataset. Choosing the pool for apps to use, creates this dataset to store all container-related data. To expose storage volumes found in the ix-applications dataset, take a recursive snapshot.
Some applications require specific storage volumes for configuration and other data. Apps with these requirements might indicate this in the wizard UI but refer to tutorials for specifics. After configuring required storage volumes you can add storage volumes. To configure additional storage volumes for the application, click Add to select the type of storage to configure. The three storage options are:
- ixVolume
- Host path
- SMB share
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 to grant an ACE. 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.

For information on adding to or changing the train for the apps catalog, see Managing App Trains.

Enterprise Apps Contents

MinIO Enterprise: Tutorials for installing and configuring the MinIO Enterprise application in an Enterprise-licensed deployment.
Syncthing (Enterprise): Provides general information, guidelines, installation instructions, and use scenarios for the Enterprise version of the Syncthing app.