TrueNAS Apps: UI ReferenceApplication 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.
Custom App Screens
13 minute read.
Custom App on the Discover screen opens the Install iX App guided installation wizard. more_vert > Install via YAML opens the Add Custom App screen with an advanced YAML editor for deploying apps using Docker Compose.
The Install iX App screen allows you to configure third-party applications using Docker settings. Use the wizard to configure applications not included in the official catalog.
The panel on the right of the screen links to each setting area. Click on a heading or setting to jump to that area of the screen. Click in the Search Input Fields to see a list of setting links.
Settings are grouped into Application Name, Image Configuration, Container Configuration, Security Context Configuration, Network Configuration, Portal Configuration, Storage Configuration, and Resources Configuration sections.
Application Name has two required settings, Application Name and version. After completing the installation these settings are not editable.
Image Configuration settings specify the container image details. They define the image, tag, and when TrueNAS pulls the image from the remote repository.
Container Configuration settings specify the entrypoint, commands, timezone, environment variables, and restart policy to use for the image. These can override any existing variables stored in the image. Check the documentation for the application you want to install for required entrypoints, commands, or variables.
Security Context Configuration settings allow you to run the container in privileged mode, grant the container Linux kernel capabilities, or define a user to run the container.
Network Configuration settings specify network, ports, and DNS servers if the container needs a custom networking configuration.
See the Docker documentation for more details on host networking.
Use port forwarding to reroute container ports that default to the same port number used by another system service or container. See Default Ports for a list of assigned ports in TrueNAS. See the Docker Container Discovery documentation for more on overlaying ports.
By default, containers use the DNS settings from the host system. You can change the DNS policy and define separate nameservers and search domains. See the Docker DNS services documentation for more details.
The Portal Configuration settings configure the web UI portal for the container.
Click Add to display the web portal configuration settings.
The Storage Configuration settings specify persistent storage paths and share data claims separate from the lifecycle of the container. For more details, see the Docker storage documentation.
You can mount TrueNAS storage locations inside the container with host path volumes. Create the storage volumes in TrueNAS and set the host path volume to a dataset and directory path. Define the path to the system storage and the container internal path for the system storage location to appear. Alternatively, select ixVolume to allow TrueNAS to create a dataset on the apps storage pool. Both Host Path and ixVolume attach container storage as a bind mount. See Docker Bind Mount documentation for more information.
Users can create additional SMB share volume claims within the container to access an SMB share. Share volumes consume space from the pool chosen for application management.
Finally, Tmpfs allows the container to utilize a temporary directory on the RAM. See the Docker tmpfs documentation for more information.
Resources Configuration settings configure resources for the container.
Resource limits specify the CPU and memory limits to place on the container.
GPU Configuration settings configure GPU device allocation for application processes. Settings only display if the system detects available GPU device(s). See Allocating GPU for more information.
The Add Custom App screen allows you to configure third-party applications using Docker Compose YAML syntax. Use the YAML editor to configure applications not included in the official catalog. See the Docker Compose overview from Docker for more information.
Installing custom applications via YAML requires advanced knowledge of Docker Compose and YAML Syntax. Users should be prepared to troubleshoot and debug their own installations. The TrueNAS forums are available for community support.
TrueNAS applies basic YAML syntax validation to custom applications, but does not apply additional validation of configuration parameters before executing the file as written.
Setting | Description |
---|---|
Name | Enter a name for the application to be used in the TrueNAS UI. The name must use lowercase alphanumeric characters, start with an alphabetic character, and can end with alphanumeric character. A hyphen (- ) is allowed but not as the first or last character, for example abc123, abc, abcd-1232, but not -abcd. |
Custom Config | Enter a Docker Compose YAML file for the application. |
Click Save to initiate app deployment.