TrueNAS SCALETrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.


Installed Applications Screen

The first time you go to Apps, the Installed applications screen displays an Apps Service Not Configured status on the screen header.

Apps Service Not Configured
Figure 1: Apps Service Not Configured

After setting the pool apps uses, this changes to Apps Service Running.

The Installed applications screen displays Check Available Apps before you install the first application.

Installed Applications Screen No Apps
Figure 2: Installed Applications Screen No Apps

Click Check Available Apps or Discover Apps to open the Discover screen to see application widgets available in the TRUENAS catalog.

After installing an application, the Installed screen populates the Applications area with a table listing installed applications. Select an application to view the information widgets for applications, with options to edit the application settings, open container pod shell or logs, and access the Web Portal for the application, if applicable.

Installed Applications Screen with Apps
Figure 3: Installed Applications Screen with Apps

Application widgets vary by app, but all include the Application Info and Workloads widgets. Some include the History and Notes widgets.

Choosing the Apps Pool

You must choose the pool apps use before you can add applications. The first time you go to the Applications screen, click Settings > Choose Pool to choose a storage pool for Apps.

Choosing a Pool for Apps
Figure 4: Choosing a Pool for Apps

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.

TrueNAS creates an ix-applications dataset on the chosen pool and uses it to store all container-related data. The dataset is for internal use only. Set up a new dataset before installing your applications if you want to store your application data in a location separate from other storage on your system. For example, create the datasets for the Nextcloud application, and, if installing Plex, create the dataset(s) for Plex data storage needs.

Special consideration should be given 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 HTTPS redirect is active, go to System Settings > General > GUI > Settings and locate the Web Interface HTTP -> HTTPS Redirect checkbox. To disable HTTPS redirects, clear this option and click Save, then clear the browser cache before attempting to connect to the app again.

General System Settings
Figure 5: General System Settings

After an apps storage pool is configured, the status changes to Apps Service Running.

Unsetting the Apps Pool

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.

Changing Official Application Networking

Official applications use the default system-level Kubernetes node IP settings.

You can change the Kubernetes node IP to assign an external interface to your apps, separate from the web UI interface, in Apps > Settings > Advanced Settings.

Advanced/Kubernetes Settings
Figure 6: Advanced/Kubernetes Settings

We recommend using the default Kubernetes node IP ( to ensure apps function correctly.

Managing Container Images

The Settings dropdown includes an option Click Settings > Manage Container Images to open the Manage Container Images screen.

Apps Manage Container Images
Figure 7: Apps Manage Container Images

Update or delete images from this screen, or click Pull Image to download a specific custom image to TrueNAS.

Pull a Container Image
Figure 8: Pull a Container Image

To download a specific image, click the button and 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.

Upgrading Apps

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.

Update Application Window
Figure 9: Update Application Window

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.

Deleting Apps

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.

Delete Application Dialog
Figure 10: Delete Application Dialog

Click Confirm then Continue to delete the application.

Using App Settings

The Settings dropdown list at the top of the Installed applications screen provides these options:

  • Choose Pool where you set the pool apps uses and create the ix-applications dataset.
  • Advanced Setting where you can make changes to the Kubernetes node IP setting.
  • Unset Pool where you can unset the apps pool, and if desired, then choose a different pool for apps to use.
  • Manage Container Images where you can manage every container image downloaded to TrueNAS.

Discover Applications Screen

The Discover screen displays New & Updated Apps application widgets for the official TRUENAS catalog Chart, Community, and Enterprise trains. Non-Enterprise systems show the Chart catalog of apps by default. The Chart catalog train has official applications that are pre-configured and only require a name during deployment.

Enterprise applications display automatically for Enterprise=licensed systems, but community users can add these apps using the Manage Catalogs screen. App trains display based on the Trains settings on the Edit Catalog screen.

See Using SCALE Catalogs for more information on managing catalogs.

Applications Discover Screen
Figure 11: Applications Discover Screen

The Discover screen includes three links:

The Custom App button opens a wizard where you can install unofficial apps or an app not included in a catalog.

Browse the widgets or use the search field to find an available application. Click on an application widget to go to the application information screen.

Refreshing Charts

You can refresh the charts catalog by clicking Refresh Charts on the Discover screen. You can also refresh all catalogs from the Catalogs screen. Click Manage Catalogs, then click Refresh All. Refresh the catalog after adding or editing the catalogs on your system.

Using the Discover Screen Filters

To filter the app widgets shown, click the down arrow to the right of Filters.

Discover Apps Filter Options
Figure 12: Discover Apps Filter Options

You can filter by catalog, app category, name, catalog name, and date last updated. Click on the option then begin typing the name of the app into the search field to narrow the widgets to fit the filter criteria. Click in Categories to select apps based on the selection you make. Click in the field again to add another category from the dropdown list to select multiple categories.

Installing Official Applications

From the application information screen, click Install to open the installation wizard for the application.

Application Information Screen Example
Figure 13: Application Information Screen Example

After installing an application, the Installed applications screen shows the application in the Deploying state. It changes to Running when the application is ready to use.

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 applications 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. Also includes the version number for the application. Do not change the version number for official apps or those included in a SCALE catalog. When a new version becomes available, the Installed application screen banner and application row displays an update alert, and the Application Info widget displays an update button> Updating the app changes the version shown on the edit wizard for the application.

  • Application Configuration shows settings that app requires to deploy. This section can be named anything. For example, the MinIO app uses MinIO Configuration.

    Typical settings include user credentials, environment variables, additional argument settings, name of the node, or even sizing parameters.

    If not using the default user and group provided, add the new user (and group) to manage the application before using the installation wizard.

  • 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 options include using the default ixVolume setting that adds a storage volume under the ix-applications dataset, host path where you select existing dataset(s) to use, or in some cases the SMB share option where you configure a share for the application to use. The Add button allows you to configure additional storage volumes for the application to use in addition to the main storage volume (dataset).

    If the application requires specific datasets, configure these before using the installation wizard.

    Browsing to select a path

    Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.

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

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.

Refer to individual tutorials in the Community or Enterprise sections of the Documentation Hub for more details on application settings. Installation and editing wizards include tooltips to help users configure application settings.

Allocating GPU

Users with compatible hardware can allocate one or more GPU devices to an application for use in hardware acceleration. This 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.

Resources Configuration
Figure 15: Resources Configuration

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. It is not possible at this time to specify which available GPU device is allocated to the application and assigned devices can change on reboot.

Select GPU Allocation
Figure 16: Select GPU Allocation
Troubleshooting GPU Allocation

If installed GPU devices do not populate as available for allocation in GPU Configuration:

  1. Ensure the GPU devices you want to allocate are not configured as isolated. Go to System Settings > Advanced and locate the Isolated GPU Device(s) widget. If necessary, click Configure, deselect the device(s) you want to allocate, and click Save.

  2. Ensure the GPU devices you want to allocate are not assigned to any existing VMs. Go to Virtualization. Select an existing VM and click on that row to expand it, then click Edit. Scroll down to GPU and review configured devices. If necessary, deselect the device you want to allocate to applications. Repeat for any additional VMs on the system.

If the GPU was previously isolated and/or assigned to a VM, a reboot could be required to free it up for app allocation. Restart the system then return to the Resources Configuration section of the application to see if expected devices are available.

Installing Custom Applications

To deploy a custom application, go to Discover and click Custom App to open the Install Custom App screen. See Using Install Custom App for more information.

Changing Custom Application Networking

Custom applications use the system-level Kubernetes Node IP settings by default.

You can assign an external interface to custom apps using one of the Networking section settings found on the Install Custom App screen.

Unless you need to run an application separately from the Web UI, we recommend using the default Kubernetes Node IP ( to ensure apps function correctly.

Section Contents

  • Using SCALE Catalogs: Provides basic information on adding or managing application catalogs in TrueNAS SCALE.

  • Using Install Custom App: Provides information on using Install Custom App to configure custom or third-party applications in TrueNAS SCALE.

  • Securing Apps: Securing TrueNAS applications with VPNs and Zero Trust.

  • Community Apps: Notes about community applications and individual tutorials for applications.

  • Enterprise Applications: Tutorials for using TrueNAS SCALE applications in an Enterprise-licensed deployment.

  • Sandboxes (Jail-like Containers): Provides advanced users information on deploying custom FreeBSD jail-like containers in SCALE.