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
22 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.
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. See Advanced Guidance below for more information about apps pool selection.
As of 24.10, TrueNAS apps use Docker containers and Docker Compose for deployment. Docker is an open-source software that manages images and container deployments.
The default system-level settings are found in Apps > Settings.
For more information on screens and screen functions, refer to the UI Reference article on Apps Screens.
Use the Configuration dropdown to access the Choose Pool, Unset Pool, Manage Container Images, and Settings options.
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.
Select the pool and click Save. If you close the dialog to set the pool later, click Configuration > Choose Pool to set the pool.
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 app stability and performance, we recommend using SSD storage for the apps pool due to their faster speed and resilience for repeated read/writes.
TrueNAS 24.10 and newer creates a hidden ix-apps dataset on the apps pool and mounts the hidden directory at
See Understanding App Storage for more information about the ix-apps dataset and other app data storage volumes.
To select a different pool for apps to use, click Configuration > Unset Pool. This turns off the apps service until you choose another pool for apps 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.
TrueNAS 24.10 and newer creates a hidden ix-apps dataset, 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.
Click Configuration > Settings to open the Settings screen, which contains options for setting app trains, configuring app networking, installing NVIDIA drivers (if compatible hardware is present), and allowing TrueNAS to monitor for Docker image updates.
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.
Click Settings on the Configuration dropdown menu to open the 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.
Go to Apps > Installed, click Configuration, and select Settings.
To add another range of IP addresses, click Add to the right of Address Pools, then select a range from the dropdown list of options, and enter the desired value in Size.
Base shows the default IP address and subnet, and Size shows the network size of each docker network that is cut off from the base subnet.
This setting replaces the Kubernetes Settings option for Bind Network in 24.04 and earlier. Use to resolve issues where apps experience issues where TrueNAS device is not reachable from some networks. Select the network option, or add additional options to resolve the network connection issues.
Give special consideration when TrueNAS is installed in a VM, as VMs are not configured to use HTTPS.
Enabling HTTPS redirect can interfere with the accessibility of some apps. To determine if the HTTPS redirect is active, go to System > General Settings > GUI > Settings and locate the Web Interface HTTP -> HTTPS Redirect checkbox.
To disable HTTPS redirects, clear the checkbox and click Save, then clear the browser cache before attempting to connect to the app again.
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.
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 screen.
Select Install NVIDIA Drivers, which is available to users with compatible GPUs.
Select Install NVIDIA Drivers, and click Save.
Select Check for docker image updates (selected by default) to enable TrueNAS to periodically check for Docker image updates. This applies to all Docker images present on the system for either catalog or custom applications. Disable to prevent TrueNAS from monitoring for upstream image updates.
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, pre-configured to only require a name during a test deployment, or some customization for a full 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 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.
Click on an app widget to open the app information screen with details about the selected application.
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 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.
Note that having the pool configured as an SMB share results in an error when the ix-apps directory is contained within that pool. To avoid this error, place the SMB shares within the pool as individual datasets alongside the ix-apps dataset.
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 Understanding App Storage Volumes, individual app information screens, and app tutorials for more information.
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 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.
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, first, click on the app row on 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.
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 more information.
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 dialog.
Select Remove ixVolumes to delete hidden app storage from the Apps pool.
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.
While on the Installed application screen, click Configuration > Manage Container Images to open the Manage Container Images screen.
Delete images or add new ones from this screen.
Pull Image downloads a specific custom image to TrueNAS.
To download a specific image, click Pull Image, 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.