Reorganize advanced guidance info

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.

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" >}}

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" >}}).
 
@@ -60,15 +64,6 @@ 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 recommend using SSD storage for the applications pool.
 
-{{< hint type=tip title="Encrypted Pool Apps Pool" >}}
-Choosing an encrypted pool as the apps pool can introduce issues with apps not deploying when the pool is locked, result in apps failing to migrate after a manual upgrade and reboot, or produce a host path error if the pool is passphrase-encrypted.
-For these reasons, we do not recommend choosing an encrypted pool for apps.
-Apps configured to use datasets created on an encrypted pool are also encrypted and can have the same deployment issues as the apps pool.
-If your system does not have an unencrypted pool available, forcing you to use an encrypted pool for app storage, you need to unlock the pool and datasets after manual system upgrades.
-If migration fails due to a locked pool or dataset, you must unlock these storage options and re-initiate migration.
-The best practice is to create and use an unencrypted pool for apps and app dataset storage volumes.
-{{< /hint >}}
-
 Select the pool and click **Save**. If you close the dialog to set the pool later, click **Configuration > Choose Pool** to set the pool.
 
 {{< trueimage src="/images/SCALE/Apps/AppsSettingsChoosePool.png" alt="Choosing a Pool for Apps" id="Choosing a Pool for Apps" >}}
@@ -80,6 +75,8 @@ 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.
 
@@ -110,7 +107,7 @@ 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 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**.
 
@@ -254,7 +251,7 @@ 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.
 
 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.
+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.
@@ -292,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" >}}
+
 <div class="noprint">
 
 ## Apps Contents

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 >}}

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 <file>/mnt/.ix-apps</file>, 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).

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.
+
+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.

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 <file>/mnt/.ix-apps</file>.
+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.