From 9a3029bf924e7ff0df5e80894859ff37c2f673a3 Mon Sep 17 00:00:00 2001 From: MicJ <92740932+micjohnson777@users.noreply.github.com> Date: Mon, 2 Dec 2024 07:42:24 -0500 Subject: [PATCH] PD-1555 / 25.04 / PD-1555 Add Version, Stopping Apps, and Encrypted Apps Pool Information (#3308) * PD-1555 Add Version, Stopping Apps, and Encrypted Apps Pool Information This commit adds information on the two app version fields, using the stop app button for apps in either running or deploying state, and on choosing an encrypted pool for apps and using an encrypted dataset for an app storage volume to the main /TruenasApps/_index.md file. * Reorganize advanced guidance info --------- Co-authored-by: DjP-iX <133042991+DjP-iX@users.noreply.github.com> --- content/TruenasApps/CommunityApps/_index.md | 2 + content/TruenasApps/StableApps/_index.md | 2 + content/TruenasApps/_index.md | 71 +++++++++++++++----- static/includes/apps/AppsBestPractices.md | 12 +--- static/includes/apps/AppsDatasets.md | 8 +-- static/includes/apps/AppsDirectoryService.md | 3 +- static/includes/apps/AppsDockerCompose.md | 5 -- static/includes/apps/AppsPool.md | 4 ++ 8 files changed, 71 insertions(+), 36 deletions(-) delete mode 100644 static/includes/apps/AppsDockerCompose.md diff --git a/content/TruenasApps/CommunityApps/_index.md b/content/TruenasApps/CommunityApps/_index.md index 55c9b3cba0..27761c9a83 100644 --- a/content/TruenasApps/CommunityApps/_index.md +++ b/content/TruenasApps/CommunityApps/_index.md @@ -27,6 +27,8 @@ Go to the **Discover** screen and click **Refresh Catalog**, to the right of the For more information on adding to or changing the train for the apps catalog, see [Managing App Trains]({{< relref "UsingTrains.md" >}}). +{{< include file="/static/includes/apps/AppsBestPractices.md" >}} + Applications are provided "as-is" and can introduce system stability or security issues when installed. Some applications deploy as the **root** user for initial configuration before changing to operate as a non-root user. diff --git a/content/TruenasApps/StableApps/_index.md b/content/TruenasApps/StableApps/_index.md index 9d884c39b7..c6e965b023 100644 --- a/content/TruenasApps/StableApps/_index.md +++ b/content/TruenasApps/StableApps/_index.md @@ -26,6 +26,8 @@ The tutorials in this section are for the commonly-used **stable** train catalog For information on adding to or changing the train for the apps catalog, see [Managing App Trains]({{< relref "UsingTrains.md" >}}). +{{< include file="/static/includes/apps/AppsBestPractices.md" >}} + ## Understanding App Install Wizard Settings {{< include file="/static/includes/apps/AppsInstallWizardSettings.md" >}} diff --git a/content/TruenasApps/_index.md b/content/TruenasApps/_index.md index dfd5ceb5af..d9c66d8d4c 100644 --- a/content/TruenasApps/_index.md +++ b/content/TruenasApps/_index.md @@ -43,8 +43,12 @@ Applications are provided "as-is" and can introduce system stability or security 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](#advanced-guidance) below for more information about apps pool selection. -{{< include file="/static/includes/apps/AppsBestPractices.md" >}} +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]({{< relref "SCALE/SCALEUIReference/Apps/_index.md" >}}). @@ -71,12 +75,14 @@ For example, create the datasets for the Nextcloud app before installing the app {{< trueimage src="/images/SCALE/SystemSettings/SystemSettingsGUISettingsSCALE.png" alt="General System Settings" id="General System Settings" >}} +See [Advanced Guidance](#advanced-guidance) below for more information about apps pool selection and datasets. + ### Unsetting the Apps Pool 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. ### Configuring Apps Settings -Click **Configuration > Settings** to open the **Settings** screen, which contains options for setting apps trains, configuring app networking, installing NVIDIA drivers (if compatible hardware is present), and allowing TrueNAS to monitor for Docker image updates. +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. {{< trueimage src="/images/SCALE/Apps/AppsSettingScreen.png" alt="Apps Settings Screen" id="Apps Settings Screen" >}} @@ -101,15 +107,15 @@ Some applications deploy as the **root** user for initial configuration before o Keep these general best practices in mind when using applications with TrueNAS. #### Changing Apps Network Settings -Go to **Apps > Installed**, click **Configuration** and then on **Settings**. +Go to **Apps > Installed**, click **Configuration**, and select **Settings**. -To add an additional 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**. +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. {{< hint type="info" title="Apps Networking Troubleshooting Tip!" >}} -This setting replaces the Kubernetes Settings option for Bind Network in 24.04 and earlier. -Use to resolve issues where apps experiences issues where TrueNAS device is not reachable from some networks. +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. {{< /hint >}} @@ -148,7 +154,7 @@ 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. ## Installing an Application -The first time you go to **Apps**, a dialog prompts your to choose the pool apps use. You must set the app pool before you can install applications. +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 Application Pool**](#choosing-the-application-pool). The **Installed** applications screen displays **Check Available Apps** before you install the first application. @@ -157,12 +163,17 @@ The **Installed** applications screen displays **Check Available Apps** before y Click either **Check Available Apps** or **Discover Apps** to open the **[Discover](#using-the-discover-applications-screen)** screen. -Search for the application widget, then click on that widget to open the information screen for the app and to access the installation wizard. +Search for the application widget, then click on that widget to open the information screen for the app and access the installation wizard. {{< include file="/static/includes/apps/AppsSMBErrorWarning.md" >}} If an application requires specific datasets, configure them before launching the installation wizard. +### App Version Verses Version +The **Application Info** widget on the **Installed** applications screen shows the **App Version**, which is the main container version, and is provided for information purposes. +This **App Version** also shows on the upgrade dialog, and the application details screen just above the **Version**. +The **Version** information is the basis for app updates in TrueNAS, and is found on the app widget, and in the app Install wizard. + ### Using an App 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. @@ -172,7 +183,7 @@ 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 exiting the without saving. +Click **Discover** on the breadcrumb at the top of the app wizard screen to exit without saving. {{< hint type="info" title="Community Maintained Apps" >}} Apps submitted and maintained by community members using the **Custom App** option might not include an installation wizard. @@ -183,16 +194,16 @@ Refer to tutorials created and maintained by the community for more information 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. Click **Stop** changes the status to **Stopping** before going to **Stopped**. +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. +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]({{< relref "/content/TruenasApps/StableApps/_index.md" >}}), [Community]({{< relref "/content/TruenasApps/CommunityApps/_index.md" >}}), or [Enterprise]({{< relref "/content/TruenasApps/EnterpriseApps/_index.md" >}}) sections of the Documentation Hub for more details on configuring application settings. #### GPU Passthrough -Users with compatible hardware can passthrough a GPU device to an application for use in hardware acceleration. +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)]({{< relref "managegpuscale.md" >}}). A single GPU cannot be shared between the OS/applications and a VM. @@ -203,7 +214,7 @@ The GPU passthrough option shows in the **Resources Configuration** section of t Click **Passthrough available (non-NVIDIA) GPUs** to have TrueNAS pass an AMD or Intel GPU to the application. -**Select MVIDIA GPU(s)** displays if an NVIDIA GPU is available, with [installed drivers](#installing-nvidia-drivers). +**Select NVIDIA GPU(s)** displays if an NVIDIA GPU is available, with [installed drivers](#installing-nvidia-drivers). Click **Use this GPU** to pass that GPU to the application. ### Installing Custom Applications @@ -214,7 +225,7 @@ See [Installing Custom Applications]({{< relref "UsingCustomApp.md" >}}) for mor ## Upgrading Apps 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. +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. @@ -236,6 +247,12 @@ Select **Remove ixVolumes** to delete hidden app storage from the Apps pool. Click **Confirm** then **Continue** to delete the application. +## Stopping Apps +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. + +Apps stuck in a deploying state can result from various configuration problems. +To check the logs for information on deployment issues encountered, click **View Logs**on the **Workloads** widget for the app. + ## Discover Screen Options The **Discover** screen shows application widgets based on the trains selected on the **Train Settings** screen. @@ -254,8 +271,8 @@ Use the **Discover** screen links to access other functions. * **Manage Installed Apps** - Opens the **Installed** apps screen where you access the **Configuration** menu to manage general application settings. ### Refreshing the Apps Catalog -Click **Refresh Catalog** on the **Discover** screen to refresh the apps catalog. -Refresh the apps catalog after adding or editing the app trains on your system. +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. ### Using the Discover Screen Filters 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. @@ -272,6 +289,28 @@ To select multiple categories, click **Categories** again and select another cat 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. +## Advanced Guidance + +Below, you'll find additional details about TrueNAS apps administration, including best practices and in-depth insights. + +### App Pool Selection + +{{< include file="/static/includes/apps/AppsPool.md" >}} + +### App Dataset Types + +{{< include file="/static/includes/apps/AppsDatasets.md" >}} + +### Custom Apps + +{{< include file="/static/includes/apps/CustomAppIntro.md" >}} + +{{< include file="/static/includes/apps/AppsCustomApp.md" >}} + +### App Directory Services + +{{< include file="/static/includes/apps/AppsDirectoryService.md" >}} +
## Apps Contents diff --git a/static/includes/apps/AppsBestPractices.md b/static/includes/apps/AppsBestPractices.md index a90e91324b..214d866722 100644 --- a/static/includes/apps/AppsBestPractices.md +++ b/static/includes/apps/AppsBestPractices.md @@ -1,10 +1,10 @@ -Keep these general best practices in mind when using applications with TrueNAS: +Below, you'll find additional details about TrueNAS apps administration, including best practices and in-depth insights. {{< expand "App Pool Selection" "v" >}} -{{< include file="/static/includes/apps/AppsPoolOrDataset.md" >}} +{{< include file="/static/includes/apps/AppsPool.md" >}} {{< /expand >}} @@ -14,12 +14,6 @@ Keep these general best practices in mind when using applications with TrueNAS: {{< /expand >}} -{{< expand "Apps General Settings" "v" >}} - -{{< include file="/static/includes/apps/AppsDockerCompose.md" >}} - -{{< /expand >}} - {{< expand "Custom Apps" "v" >}} {{< include file="/static/includes/apps/CustomAppIntro.md" >}} @@ -32,6 +26,4 @@ Keep these general best practices in mind when using applications with TrueNAS: {{< include file="/static/includes/apps/AppsDirectoryService.md" >}} -iXsystems Support can assist Enterprise customers with configuring directory service settings in TrueNAS with the [information customers provide]({{< relref "/SCALE/GettingStarted/Install/_index.md" >}}), but they do not configure customer Active Directory system settings. - {{< /expand >}} diff --git a/static/includes/apps/AppsDatasets.md b/static/includes/apps/AppsDatasets.md index 1f42826199..6adffc9eaa 100644 --- a/static/includes/apps/AppsDatasets.md +++ b/static/includes/apps/AppsDatasets.md @@ -1,6 +1,6 @@ -**ix-apps Dataset** +#### ix-apps Dataset TrueNAS 24.10 and newer creates a hidden **ix-apps** dataset, mounted at /mnt/.ix-apps, to store Docker configuration, catalog data, and app metadata. The ix-apps dataset is internally managed by TrueNAS and hidden to prevent user misconfiguration. @@ -24,7 +24,7 @@ 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. {{< /hint >}} -**ixVolume Datasets** +#### ixVolume Datasets **ixVolume** datasets allow TrueNAS to automatically create an app storage path inside the hidden ix-apps dataset. @@ -35,7 +35,7 @@ ixVolumes are not recommended for permanent storage volumes, they are intended f 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 Path Datasets** +#### Host Path Datasets **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. @@ -59,7 +59,7 @@ This allows TrueNAS to write ACL entries to the storage volume if it has existin **Force Flag** is required to edit or update an existing application. {{< /expand >}} -**SMB Share Volumes** +#### SMB Share Volumes Some app storage configurations include the **SMB/CIFS Share** option. Use this option to mount an existing SMB share using a Docker [volume](https://docs.docker.com/engine/storage/#volumes). diff --git a/static/includes/apps/AppsDirectoryService.md b/static/includes/apps/AppsDirectoryService.md index 3ae7889e40..9d1eeadc88 100644 --- a/static/includes/apps/AppsDirectoryService.md +++ b/static/includes/apps/AppsDirectoryService.md @@ -6,4 +6,5 @@ You might need to supply your LDAP server host name, LDAP server base and bind d TrueNAS is configured with default port numbers, but you can change these. Before making a port number change, refer to the [Default Ports](https://www.truenas.com/docs/references/defaultports/) for a list of used and available ports before changing default port assignments. -TrueNAS requires assinging a node port greater than 9000. \ No newline at end of file + +iXsystems Support can assist Enterprise customers with configuring directory service settings in TrueNAS with the [information customers provide]({{< relref "/SCALE/GettingStarted/Install/_index.md" >}}), but they do not configure customer Active Directory system settings. diff --git a/static/includes/apps/AppsDockerCompose.md b/static/includes/apps/AppsDockerCompose.md deleted file mode 100644 index 44a347e12b..0000000000 --- a/static/includes/apps/AppsDockerCompose.md +++ /dev/null @@ -1,5 +0,0 @@ - - -As of 24.10, TrueNAS apps use Docker containers and Docker Compose. -Docker Compose is an open-source container and image software that manages images and container deployments. -The default system-level settings are found in **Apps > Settings**. \ No newline at end of file diff --git a/static/includes/apps/AppsPool.md b/static/includes/apps/AppsPool.md index b3dd9ff6b6..8c355c056a 100644 --- a/static/includes/apps/AppsPool.md +++ b/static/includes/apps/AppsPool.md @@ -4,3 +4,7 @@ We recommend users keep the container use case in mind when choosing an applicat Select a pool with enough space for all the application containers you intend to use. For stability, we recommend using SSD storage for the apps pool. + +TrueNAS 24.10 and newer creates a hidden **ix-apps** dataset on the apps pool and mounts the hidden directory at /mnt/.ix-apps. +The ix-apps dataset does not inherit encryption if an encrypted pool is selected as the pool for applications. +See App Dataset Types for more information.