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.
Managing Apps
18 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 Notes.
TrueNAS applications 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.
This article covers how to discover, install, and manage applications. For details on setting up the TrueNAS Apps service, configuring global settings, and other general information, see TrueNAS Apps and individual app tutorials.
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.
The Discover screen shows application widgets based on the trains selected on the Train Settings screen.
Use the Discover screen links to access other functions.
- Refresh Catalog - Refreshes the list of app widgets after changing train settings or changes to the catalog.
- Manage Installed Apps - Opens the Installed apps screen where you access the Configuration menu to manage general application settings.
- Custom App - Allows users to deploy custom applications.
Click on an app widget to open the app information screen with details about the selected application.
TrueNAS applications are available in three catalogs (trains):
Enterprise
Applications validated by TrueNAS Engineering for Enterprise deployment on TrueNAS Enterprise-licensed systems.
These applications receive either Enterprise Deployment Support or full Enterprise Application Support from the TrueNAS Support team.
Stable
Applications tested by the TrueNAS Engineering team and chosen based on their functionality and integration with TrueNAS.
TrueNAS Engineering can provide software maintenance for these applications, but the TrueNAS Support team does not offer continual support. Issues for these applications are tracked separately and addressed on a best-effort basis in the community forums and other user-driven resources.
Community
Applications proposed and maintained by the TrueNAS community without official TrueNAS support.
Issues for these applications are tracked separately and addressed on a best-effort basis in the community forums and other user-driven resources.
Some apps proposed by community members might be adopted as official Stable train apps.
See App Support Definitions for more information on application support levels.
TrueNAS Community Edition systems populate the Discover apps screen with the Stable and Community catalogs populate by default. TrueNAS Enterprise-licensed systems show the Enterprise catalog.
Users can change the apps displayed on the Discover screen by adding or removing trains. To add or remove a train, Settings on the Configuration dropdown list to open the Settings screen.
Select the Preferred Trains checkbox(es) for the train(s) to include, then click Save.
After making a change, go to the Discover screen and click on Refresh Catalog to pull the catalog from the repository and refresh it in TrueNAS.
To remove a train from the catalog, deselect the checkbox for the train on the Settings screen, then click Save. You must have at least one train selected.
The information screen includes two version numbers for the selected application: App Version and Version. App Version is the version of the upstream Docker image the app installs, such as 24.04.10.2.1 for Collabora. The App Version also appears in the Application Info widget on the Installed applications screen. Version is the revision number of the app in the TrueNAS app train, for example 1.2.2. The Version is the number used to identify app updates in TrueNAS. It also appears on the Installed applications screen, on the Discover screen app widget, and in the install wizard for the app.
Click Refresh Catalog on the Discover screen to refresh the app catalog. Refresh the app catalog after adding or editing the app trains on your system.
To change how app widgets show on the screen, click the down arrow to the right of Filters, and select the filter option to use.
To quickly locate a specific app, begin typing the name in the search field. The screen shows apps matching the typed entry.
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.
The ix-apps dataset is the base-level storage volume for app data. Additionally, configuration options for individual apps include one or more of the following storage types: ixVolume datasets, host path datasets, SMB share volumes, and Tmpfs.
If an application requires specific host path datasets, create the datasets before installing the application. For example, the Nextcloud app requires three datasets: html for app data, data for user data, and postgres_data for the database data storage volume. Create these datasets before installing the app. See individual app information screens and app tutorials for more information.
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
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 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 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.
Some app storage configurations include the SMB/CIFS Share option. Use this option to mount an existing SMB share using a Docker volume.
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.
The first time you go to Apps, a dialog prompts you to choose the pool for apps to use. You must set the app pool before you can install applications. Select the pool as described in the Choosing the Apps Pool.
The Installed applications screen displays Check Available Apps before you install the first application.
Click either 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.
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 and 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 exit 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 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 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.
After clicking Install on an application wizard screen, the Installed applications screen opens showing the application in the Deploying state before changing to Running. Applications that crash show the Crashed status. Clicking Stop changes the status to Stopping before going to Stopped. Click Start to restart the application.
The screen defaults to selecting the first app row listed on the Applications table and showing the application widgets that first app. To modify installed application settings, click on the app row in the Applications table, then click Edit on the Application Info widget.
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 pass through a GPU device to an application for use in hardware acceleration.
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.
The GPU passthrough option shows in the Resources Configuration section of the application installation wizard screen or the Edit screen for a deployed application.
Click Passthrough available (non-NVIDIA) GPUs to have TrueNAS pass an AMD or Intel GPU to the application.
Select NVIDIA GPU(s) displays if an NVIDIA GPU is available, with installed drivers. Click Use this GPU to pass that GPU to the application.
Apps stuck in a deploying state can result from various configuration problems. To check the logs for information on deployment issues encountered, click Logs View Logs on the Workloads widget for the app.
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
See Installing Custom Applications for a detailed tutorial with deployment examples.
Installed applications appear on the Installed applications screen. Click on an app row to view Details, including the Application Info, Workloads, Notes, and Application Metadata widgets.
Apps with available upgrades show a yellow circle with an exclamation point on the right side of the Applications table row, and the Installed application screen banner displays an Update or an Update All button. To upgrade an app, select the app row and click Update on the Application Info widget. To upgrade multiple apps, either click the Update All button on the Installed applications banner or select the checkbox to the left of the application row to show the Bulk Actions button. Click Bulk Actions and select Upgrade All to upgrade the apps selected. Upgrade options only show if TrueNAS 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 App dialog.
Select Remove iXVolumes to delete hidden app storage from the apps pool. Select Force-Remove iXVolumes to delete app storage created on TrueNAS 24.04 and migrated to 24.10 or later. Proceed with caution as this option removes both legacy Kubernetes and current Docker data for the application.
Select Remove Images to prune Docker images of the deleted app.
Click Confirm then Continue to delete the application.
Apps on the Installed screen, showing either the Deploying or Running status, can be stopped using the stop button on the Applications table row for the app.
Running apps show the restart icon button that allows you to stop and then restart the application. Click the icon button to stop then automatically restart the app.