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.
Plex
18 minute read.
Plex is a media server that allows you to manage and stream your media (music, movies, live TV, etc.) to any Plex client.
Before you install the Plex app:
Set up a Plex account.
After installing the Plex app and logging into Plex through the Web Portal button in TrueNAS, if you have not already configured your Plex account media server, Plex shows the configuration screens to set up the media server, add libraries, and customize your Plex account.
Set a pool for applications to use if not already assigned.
You can use either an existing pool or create a new one. TrueNAS creates the ix-apps (hidden) dataset in the pool set as the application pool. This dataset is internally managed, so you cannot use this as the parent when you create required application datasets.
After setting the pool, the Installed Applications screen displays Apps Service Running on the top screen banner.
Locate the run-as user for the app.
Take note of the run-as user for the app, shown on the app information screen in the Run As Context widget and in the Application Metadata widget on the Installed applications screen after the app fully deploys. The run-as user(s) get added to the ACL permissions for each dataset used as a host path storage volume.
Create datasets for the storage volumes for the app.
Do not create encrypted datasets for apps if not required! Using an encrypted dataset can result in undesired behaviors after upgrading TrueNAS when pools and datasets are locked. When datasets for the containers are locked, the container does not mount, and the apps do not start. To resolve issues, unlock the dataset(s) by entering the passphrase/key to allow datasets to mount and apps to start.Go to Datasets and select the pool or dataset where you want to place the dataset(s) for the app. For example, /tank/apps/appName.
Plex uses for storage volumes: data to use as the Plex data directory for database and metadata storage, and config for Plex application configuration storage.
You can create a dataset or use a temporary directory option for log data. Transcode data is not useful or meant for persistent storage, so using a temporary directory is a better option.
You can set up the permissions (ACLs) for these datasets after adding them using the Edit ACL screen, or wait and use the Install Plex wizard ACL settings to add permissions. You can also edit permissions after using either method.
This basic procedure covers the required Plex app settings. For optional settings, see Understanding App Installation Wizard Settings.
You can have multiple deployments of the same app (for example, two or more from the stable or enterprise trains, or a combination of the stable and enterprise trains).
Go to Apps, click on Discover Apps, and locate the app widget by either scrolling down to it or begin typing the name into the search field. For example, to locate the MinIO app widget, begin typing minIO into the search field to show app widgets matching the search input.
If this is the first application installed, TrueNAS displays a dialog about configuring apps.
If not the first time installing apps the dialog does not show, click on the widget to open the app information screen.
Click Install to open the app installation wizard.
Application configuration settings are grouped into several sections, each explained below in Understanding App Installation Wizard Settings. To find specific fields begin typing in the Search Input Fields search field to show the section or field, scroll down to a particular section, or click on the section heading in the list of sections on the upper-right of the wizard screen.
Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.
Accept the default version number in Version. When a new version becomes available, the application shows an update badge and the Application Info widget on the Installed applications screen shows the Update button.
Next, enter the Plex Configuration settings. For a basic installation, you can accept the default values.
Select the timezone where your TrueNAS system is located. Begin typing the location into the Timezone field to filter the list until the location shows, then select it.
While logged into your Plex account, go to the Plex Claim Code web page to copy the Claim Code string provided by Plex, and then paste it into the TrueNAS Install Plex wizard Claim Token field. This authentication token provides TrueNAS access to your Plex account.
Next, either accept the default values shown or enter the IP addresses for local network connections (Ethernet or WiFi routers) you want in your Plex network. See Setting Up Local Network below for more information.
You can add devices and additional environment variables, but this is not required to deploy the app. For more information, see Adding Devices below.
Accept the default values in User and Group Configuration and Network Configurations. (Optional) If you created a new user to administer apps, enter that user ID in the user and group fields. See User and Group Configuration and Network Configuration for more details.
Add your Storage Configuration settings.
Add any labels you want to use to organize your media files. For example, labeling video files as movies or sports, etc. Labels allow you to create custom groupings or classifications beyond the default metadata provided by Plex.
Accept the defaults in Resources Configuration and select the GPU option if you have a compatible GPU installed in the system and want to use it for hardware-accelerated transcoding.
Click Install. A progress dialog opens before switching to the Installed applications screen. The Installed screen shows the plex app in the Deploying state until fully installed and then the status changes to Running when ready to use.
Click Web Portal on the Application Info widget to open the Plex web portal sign-in screen.
After signing in, Plex guides you through several initial media server configuration screens if this is a new account or shows your default Plex media screen for your existing configured account.
The following section provides more detailed explanations of the settings in each section of the Install installation wizard.
Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.
Accept the default version number in Version. When a new version becomes available, the application shows an update badge and the Application Info widget on the Installed applications screen shows the Update button.
Plex configuration settings include setting up the server timezone, authentication to the Plex account, location of the Plex container image, local network settings, and adding devices or additional environment variables to apply to the container.
Select the timezone where your TrueNAS system is located. Begin typing the location into the Timezone field to filter the list until the location shows, then select it.
TrueNAS authenticates to the Plex account using a Plex claim token. While signed into your Plex account, copy the token provided by Plex into the Claim Token field. The Plex app does not deploy if you do not include this token.
Accept the default value in Image to use the container image for the TrueNAS app.
TrueNAS shows the default IP addresses detected for your system. If these address fields are not shown in the wizard, your network is considered to be on the external network.
Accept the default values or enter IP addresses for local network connections (Ethernet or WiFi routers) you want to add to your Plex local network. These addresses define how Plex interacts with devices and services on your network and can optimize how your Plex media server communicates with devices in your home.
Specified addresses are considered on the local network when enforcing bandwidth restrictions. If left blank, only the subnet for the server is considered to be on your local network. When the host network is not enabled, the server subnet is the network for Docker. Therefore, all connections from other clients are considered to be on the external network. If set, all other IP addresses are considered to be external to your local network.
Plex account settings allow you to add and manage devices, such as a USB TV tuner or similar hardware, that connect to your media server, both on the local network you define and remotely from external network connections. Adding devices in the TrueNAS Plex app passes devices through to your Plex account. Click Add to the right of Devices in the Install Plex wizard for each device to add.
Enter the device name in Host Device and Container Device. For example, device /dev/dvb.
Refer to Plex documentation for more information on environment variables they provide to customize your app deployment.
The default web port for Plex is 32400.
The app does not require configuring advanced DNS options. Accept the default settings or click Add to the right of DNS Options to enter the option name and value.
TrueNAS provides options for data and configuration storage volumes: ixVolumes and host paths. Logs and transcode data can use these storage options or you can create directories to hold log and transcode data. Both logs and transcode data are not intended for persistent data storage.
Logs and transcode data can use the temporary directory option that creates a Docker volume in the hidden ix-apps dataset.
Transcode data chunks are streamed to a player and meant to be discarded after use, like notes on a scratchpad. This makes the tmpfs directory option a better choice for this transcode data as it creates a Linux temporary filesystem type in RAM.
Neither directory storage option provides easy access to stored data, so if you want to store and access log data, create a dataset called logs.
Plex required host path storage volumes:
- data to use as the Plex data directory for database and metadata storage.
- config to use as the Plex app configuration storage volume.
- logs optional if you want to save and have easy access to log data.
If organizing datasets under a parent dataset named plex, configure the ACL permissions for this parent dataset and add an ACE entry for the run-as (root or 0) or assigned user (568).
See Before You Begin for more information on creating app datasets.
You can configure ACL permissions for the required dataset in the Install Plex wizard, or from the Datasets screen any time after adding the datasets.
Select Enable ACL to show the ACL and ACE Entries options. Configure ACE entries for each UID and/or GID you recorded from the Run As Context widget in Before You Begin.
Configuring ACE Entries
Enter or browse to select the dataset and populate Host Path.
Next, click Add to the right of ACL Entries to show the permissions settings. Set ID Type to Entry is for a USER or Entry is for a GROUP. If you configured a group in TrueNAS that you want to give access to instead of a single user, set the ID to the group option and enter the GID for that group.
Enter the UID and/or GID as one of the following:
- The default app user:
- 568 for apps in all trains if the app can run as any non-root user.
- 999 for all postgres storage volumes.
- 0 if running as root.
- 473 for MinIO app in the stable train.
- The run-as-user UID set as a default for the app.
The run-as user shows on the app details screen in the Run As Content widget, and on the Installed application screen after the app deploys.
You can refer to the tutorial for the app, or look in the
questions.yaml file found in the GitHub repository for the application to find this UID/GID. - The user ID for the new or existing TrueNAS user added to serve as the administrator for the app.
If the app shows User and Group Configuration settings, the default UID shows on the screen. If not, choose the run-as user ID found in the Run As Content widget.
Use the default user ID 999 for all postgres storage volumes, not the run-as user.
If you created a new TrueNAS user to serve as the app administration user, add an entry record and enter the UID for this user in addition to the run-as user ID.
When adding the ACL entry for the run-as user, default user, and/or optional TrueNAS app administrator user, and postgres user ID, set the Access permissions level to FULL CONTROL.
Select Force Flag to apply the ACL even if the path has existing data. This allows you to update the app when an update is available.
TrueNAS Additional Storage options include the ability to mount an SMB share inside the container pod.
Set Type an SMB/CIFS Share (Mounts a volume to a SMB share) to add an SMB share storage volume.
Select Read Only to make the storage volume read only.
Enter the path inside the container to mount the storage for the share volume in Mount Path.
Enter the server address for the SMB share in Server, the path to mount the SMB share in Path, and the share authentication user credentials in User and Password. (Optional) enter the share domain name in domain.
Permissions are currently limited to the permissions of the user that mounted the share.
Use the SMB option for data synchronization between a share and the app if the option shows on the screen. A present, only the Syncthing app includes this option.
Accept the default values in Resources Configuration or enter new CPU and memory values. By default, this application is limited to use no more than 2 CPU cores and 4096 megabytes available memory. The application might use considerably less system resources.
To customize the CPU and memory allocated to the container the app uses, enter new CPU values as a plain integer value (letter suffix is not required). The default is 4096.
Accept the default value (4 Gb) allocated memory or enter a new limit in bytes. Enter a plain integer without the measurement suffix, for example, 129 not 129M or 123MiB.
GPU Configuration provides the option to enable GPU passthrough. Select Passthrough available (non-NVIDIA) GPUs or, if your system has an NVIDIA GPU device, select Use this GPU.
For more information on GPU passthrough, see TrueNAS Apps.
Before editing Plex app settings, stop the app, and then edit settings. After saving changes, restart the app.
Refer to the Plex support website and documentation for assistance with your Plex media server issues.
You must get a claim token from Plex and add it to the app or Plex does not deploy. If your app is not deploying, try obtaining a fresh claim token from Plex. Stop the Plex app, then edit the TrueNAS Plex app settings to paste the new token into the Claim Token field. Save the change. Restart the app.
If the app still does not start, try clearing your screen cache. This can sometimes prevent showing the app as fully deployed.
If Plex reports issues with drivers you might have to delete the app and recreate a fresh app container using the same datasets. Also, check Apps > Configuration > Settings to make sure the NVIDIA driver option is selected.
Search the TrueNAS forum for Plex discussion threads for other tips and suggestions.
Check the dataset permissions, and verify the user accessing these files has the correct permissions. You can edit dataset permissions using the Edit button on the Permissions widget on the Datasets screen. Select the dataset, scroll down to the Permissions widget, and click Edit to open the Edit ACL screen. Check the ACL entries list for the user accessing the files. If not present, click Add ACL Entry, select User, and locate the user name on the User dropdown list. Assign the level of permissions you want to assign, then save the ACL changes.
You can also add the user in the Plex app settings. Click on the Plex app row on the Installed application table. Stop the app, then click Edit. Scroll down to the storage volume for Data, click Add to the right of ACL Entries. Select Entry is for a USER as the ID Type, enter the user ID number, and then select the level of permission you want to allow. Save the changes, then restart the app.