TrueNAS Enterprise
TrueNAS SCALE
TrueNAS CORE
Compare Editions
TrueCommand
Software Status
FreeNAS
Compare Systems
F-Series
M-Series
H-Series
R-Series
Mini Series
Download TrueNAS SCALE
Download TrueNAS CORE
Get TrueNAS Enterprise
Contact an Enterprise SpecialistTrueNAS 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.
TrueNAS Apps
17 minute read.
TrueNAS applications allow for quick and easy integration of third-party software and TrueNAS. The TrueNAS applications backend changed in 24.10 to Docker images managed with Docker Compose. Earlier TrueNAS releases operated with Kubernetes K3 and Helm providing containers for applications. For more information on this change refer to the 24.10 Release Note.
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 is certified with leading hypervisors and backup solutions to streamline storage operations and ensure compatibility with your existing IT infrastructure. TrueNAS delivers 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 they can add significant risk to system stability and security.
All applications added to TrueNAS are intended to expand system functionality far beyond what is typically expected from a NAS.
Applications are provided “as-is” and can introduce system stability or security issues when installed. Make sure the application is required for your specific use requirements and does not violate your security policies before installation.
You must choose a pool before you can install an application.
For more information on screens and screen functions, refer to the UI Reference article on Apps Screens.
You are prompted to select the pool for apps the first time you click on Apps. You can exit out of this if you are not ready to deploy apps or do not have a pool configured for apps to use for storage. You must set the pool before you can add any application.
We recommend keeping the application use case in mind when choosing a pool. Select a pool with enough space for all the applications you intend to use. For stability, we also recommend using SSD storage for the applications pool.
Select the pool and click Save. If you close the dialog to set the pool later, click Settings > Choose Pool to set the pool.
If you want to set up new datasets to store your application data in a location separate from other storage on your system, create the datasets before installing the application. For example, create the datasets for the Nextcloud app before installing the app.
To select a different pool for apps to use, click Settings > Unset Pool. This turns off the apps service until you choose another pool for apps to use.
TrueNAS applications are available in three catalogs (trains):
- stable - Default train of official apps, vetted by iXsystems, chosen because of the features and functionality of the app, and how they integrate with TrueNAS.
- enterprise - Default train of apps, simplified and validated for Enterprise users for Enterprise-licensed systems.
- community - Apps proposed and maintained by the community
The default TrueNAS Stable catalog populates the Discover apps screen with apps.
Some apps proposed by community members might be adopted as official stable train apps. iXsystems maintains official apps for non-Enterprise and community users.
Users can change apps on the Discover screen from the Train Settings screen. Click Train Settings on the Settings dropdown menu to open the Train Settings screen, then select the desired train(s). To show only the one train of apps, for example, the enterprise train, after selecting enterprise deselect the stable checkbox and click Save.
For more information on trains, see Managing App Trains.
Some applications deploy as the root user for initial configuration before operating as a non-root user. Keep these general best practices in mind when using applications with TrueNAS.
While on the Installed application screen, click Settings > Manage Container Images to open the Manage Container Images screen.
Delete images or add new ones from this screen.
Click Pull Image to download a specific custom image to TrueNAS.
To download a specific image, click the button, then enter a valid path and tag to the image. Enter the path using the format registry/repository/image to identify the specific image. The default latest tag downloads the most recent image version.
When downloading a private image, enter user account credentials that allow access to the private registry.
Apps display a yellow circle with an exclamation point that indicates an upgrade is available, and the Installed application screen banner displays an Update or Update All button when upgrades are available. To upgrade an app to the latest version, click Update on the Application Info widget or to upgrade multiple apps, click the Update All button on the Installed applications banner. Both buttons only display if TrueNAS SCALE detects an available update for installed applications.
Update opens an upgrade window that includes two selectable options, Images (to be updated) and Changelog. Click on the down arrow to see the options available for each.
Click Upgrade to begin the process. A counter dialog opens showing 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.
To delete an application, click Stop on the application row. After the app status changes to stopped, click Delete on the Application Info widget for the selected application to open the Delete dialog.
Click Confirm then Continue to delete the application.
The first time you go to Apps, you are prompted to choose the pool apps use. You must set the app pool before you can install applications. Select the pool as described in the Choosing the Application Pool.
The Installed applications screen displays Check Available Apps before you install the first application.
Ether click on Check Available Apps or Discover Apps to open the Discover screen.
Search for the application widget, then click on that widget to open the information screen for the app and access the installation wizard.
Note that having the pool configured as an SMB share results in an error when the ix-applications directory is contained within that pool. To avoid this error, place the SMB shares within the pool as individual datasets alongside the ix-applications folder.
If the application requires specific datasets, configure these before using the installation wizard.
After clicking on an app widget on the Discover Apps screen, the information screen for that app opens. Click Install to open the installation wizard for the application.
The installation wizard configuration sections vary by application, with some including more configuration areas than others. Each application tutorial provides information on steps to take before launching an app installation wizard, but if a tutorial does not exist, click Install on the app information screen to open the wizard. Review settings ahead of time to check for required settings then exit the wizard to do the necessary steps before returning to install the application. Click Discover on the breadcrumb at the top of the app wizard screen to exiting the without saving.
Apps submitted and maintained by community members using the Custom App option might not include an installation wizard. Refer to tutorials created and maintained by the community for more information on deploying and using these applications.
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 exiting 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, 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 SCALE 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 that creates a storage volume inside the hidden ix-apps dataset. This is the default setting.
Host Path that allows you to select an existing dataset created for the application. Shows additional fields to select the path to the dataset and add the mount point.
ixVolumes are not recommended for permanent storage volumes, they are intended for use as 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 path 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. Click Add to select the type of storage and configure additional storage volumes for the application. The three storage options are:
- ixVolume
- Host path
- SMB share that allows you to create a storage volume used by an SMB share.
An SMB share option allows you to configure a share 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 ACL and ACE entry but host paths do. After entering the dataset name as the mount point, select Enable ACL to browse to or enter the path to the dataset. Enter the UID for either the default user assigned to the app or the UID for the TrueNAS user created to serve as the app administrator as the user in the ACE entry and set permissions to full control. Failing to enable host path ACLs prevents the app from deploying!
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.
After installing an application, the Installed applications screen opens showing the application in the Deploying state. It changes to Running when the application is ready to use.
To modify installed application settings, click on the app row on the Applications table on the Installed screen, then click Edit on the Application Info widget. Ensure you have the right app row selected or you end up accessing the first app listed in the table of deployed apps.
Refer to individual tutorials in the Stable, Community, or Enterprise sections of the Documentation Hub for more details on configuring application settings.
Users with compatible hardware can allocate one or more GPU devices to an application for use in hardware acceleration. Allocating GPUs is an advanced process that could require significant troubleshooting depending on installed GPU device(s) and application-specific criteria.
GPU devices can be available for the host operating system (OS) and applications or can be isolated for use in a Virtual Machine (VM). A single GPU cannot be shared between the OS/applications and a VM.
Allocate GPU from the Resources Configuration section of the application installation wizard screen or the Edit screen for a deployed application.
Click the GPU Resource allocation row for the type of GPU (AMD, Intel, or NVIDIA) and select the number of GPU devices the application is allowed access to. You cannot specify which available GPU device TrueNAS allocates to the application. Furthermore, assigned devices can change on reboot.
Beginning in TrueNAS 24.10, NVIDIA drivers are no longer automatically installed. Users must manually install drivers from the TrueNAS UI.
If running TrueNAS 24.10 or higher:
Go to Apps > Installed and click on the Configuration.
Click on Settings to open the settings configuration panel.
Select Install NVIDIA Drivers, which is available to users with compatible GPUs.
- Select Install NVIDIA Drivers, and click Save.
The Discover screen shows application widgets based on the trains selected on the Train Settings screen.
Non-Enterprise systems show the stable catalog of apps by default. These are official applications that are pre-configured and only require a name during deployment.
Enterprise-licensed systems display the enterprise train of applications simplified and validated for Enterprise systems. Community users can add the community and enterprise trains on the Train Settings screen.
Use the Discover screen links to access other functions.
- Refresh Catalog
- Manage Installed Apps
Manage Installed Apps opens the Installed apps screen where you access the Settings menu to manage general application settings.
Click Refresh Catalog on the Discover screen to refresh the apps catalog. Refresh the apps catalog after adding or editing the trains on your system.
To change the way app widgets show on the screen, click the down arrow to the right of Filters, and select the filter option you want to use.
To quickly locate a specific app, begin typing the name in the search field.
To sort app widgets by category, click on Categories. To select multiple categories, click Categories again and select another category from the dropdown.
After installing an application, the Installed applications screen shows the app in the Deploying state. The status changes to Running when the application is fully deployed and ready to use.
Custom App opens a screen where you can upload a yaml file for an unofficial app or one not included in a TrueNAS catalog. To deploy a custom application, go to Discover and click Custom App to open the Install Custom App screen.