PD-1583 / 25.04 / Pd 1583 address ix apps and ix applications datasets (

#3271)

* Update _index.md

* Update _index.md

* Create AppsDatasets.md

* Delete AppsFileSharing.md

* Update AppsInstallWizardSettings.md

* Update AppsPoolOrDataset.md

* Update AppsDatasets.md

* Update _index.md

* Update _index.md

* Update AppsDatasets.md

* Update AppsInstallWizardSettings.md

* Update AppsPoolOrDataset.md

* Update AppsDatasets.md

* Update AppsDatasets.md

* Update _index.md

* Update _index.md

* Create AppsBestPractices.md

* Update AppsDatasets.md

* Update AppsInstallWizardSettings.md

* Update AppsPoolOrDataset.md

* remove legacy ix-applications mentions

* Rename pool snippet

* Update static/includes/apps/AppsDatasets.md

Co-authored-by: MicJ <[email protected]>

---------

Co-authored-by: MicJ <[email protected]>
(cherry picked from commit 72cedcd)

content/SCALEUIReference/Datasets/_index.md

@@ -187,7 +187,7 @@ Click to show a selectable checklist of **Permissions Advanced** and **Flags Adv
 
 {{< trueimage src="/images/SCALE/Datasets/PermissionsWidgetOwnerNSFv4Options.png" alt="Permissions Widget Owner NFSv4 Options" id="Permissions Widget Owner NFSv4 Options" >}}
 
-A dataset with a POSIX ACL type, such as the ix-applications dataset, is only editable using the **Edit** button.
+A dataset with a POSIX ACL type is only editable using the **Edit** button.
 
 **Edit** opens the [**Edit ACL**]({{< relref "EditACLScreens.md" >}}) for ACL type.
 {{< /expand >}}
@@ -270,7 +270,7 @@ The common settings are **Parent Path**, **Name**, and the **Dataset Preset** (p
 |---------|-------------|
 | **Parent path** | Read-only field that displays the dataset path. Populated with the parent dataset path, adds the name given to the dataset after entering it in **Name**. For example, *tank/shares/smbshare1*. |
 | **Name** | Enter a unique identifier for the dataset. Names allow upper and lower case letters, numbers, and the dash (-) or underscore (_) special characters, but TrueNAS does not allow trailing spaces after the dataset name. You cannot change the dataset name after clicking **Save**. The **Name** field on the **Edit Dataset** screen shows the path. |
-| **Dataset Preset** | Select the option from the dropdown list to define the type of data sharing the dataset uses. The options optimize the dataset for a sharing protocol or app and set the ACL type best suited to the dataset purpose. Options are: <br><li>**Generic** - Select for general storage datasets that are not associated with SMB shares, or apps. Sets the ACL to POSIX.<br><li>**SMB** - Select to optimize the dataset for SMB shares. Displays the **Create SMB Share** option pre-selected and **SMB Name** field populated with the value entered in **Name**. Sets the ACL to NFSv4. <br><li> **Apps** - Select to optimize the dataset for use by any application. Sets the ACL to NFSv4. If you plan to deploy container applications, the system automatically creates the **ix-applications** dataset but this is not used for application data storage. <br><li>**Multiprotocol** - Select if configuring a multi-protocol or mixed-mode NFS and SMB sharing protocols. Allows clients to use either protocol to access the same data. Displays the **Create NFS Share** and **Create SMB Share** options pre-selected and the **SMB Name** field populated with the value entered in **Name**. See [Multiprotcol Shares]({{< relref "MixedModeShares.md" >}}) for more information. Sets the ACL to NFSv4.<br></li>Setting cannot be edited after saving the dataset. |
+| **Dataset Preset** | Select the option from the dropdown list to define the type of data sharing the dataset uses. The options optimize the dataset for a sharing protocol or app and set the ACL type best suited to the dataset purpose. Options are: <br><li>**Generic** - Select for general storage datasets that are not associated with SMB shares, or apps. Sets the ACL to POSIX.<br><li>**SMB** - Select to optimize the dataset for SMB shares. Displays the **Create SMB Share** option pre-selected and **SMB Name** field populated with the value entered in **Name**. Sets the ACL to NFSv4. <br><li> **Apps** - Select to optimize the dataset for use by any application. Sets the ACL to NFSv4. If you plan to deploy container applications, the system automatically creates the **ix-apps** dataset for Docker storage for but separate datasets used for application data storage. <br><li>**Multiprotocol** - Select if configuring a multi-protocol or mixed-mode NFS and SMB sharing protocols. Allows clients to use either protocol to access the same data. Displays the **Create NFS Share** and **Create SMB Share** options pre-selected and the **SMB Name** field populated with the value entered in **Name**. See [Multiprotcol Shares]({{< relref "MixedModeShares.md" >}}) for more information. Sets the ACL to NFSv4.<br></li>Setting cannot be edited after saving the dataset. |
 {{< /truetable >}}
 {{< /expand >}}
 

static/includes/AppsSMBErrorWarning.md

@@ -1,4 +1,4 @@
 

 
-Note that having the pool configured as an SMB share results in an error when the ix-applications directory is contained within that pool.
-To avoid this error, place the SMB shares within the pool as individual datasets alongside the ix-applications folder.
+Note that having the pool configured as an SMB share results in an error when the ix-apps directory is contained within that pool.
+To avoid this error, place the SMB shares within the pool as individual datasets alongside the ix-apps dataset.

static/includes/CreateDatasetSCALE.md

@@ -14,7 +14,7 @@ Select the **Dataset Preset** option you want to use. Options are:
 
 If creating an SMB or multi-protocol (SMB and NFS) share the dataset name value auto-populates the share name field with the dataset name.
 
-If you plan to deploy container applications, the system automatically creates the **ix-applications** dataset, but this dataset is not used for application data storage.
+If you plan to deploy container applications, the system automatically creates the **ix-apps** dataset for Docker storage for but separate datasets used for application data storage.
 If you want to store data by application, create the dataset(s) first, then deploy your application.
 When creating a dataset for an application, select **Apps** as the **Dataset Preset**. This optimizes the dataset for use by an application.
 

static/includes/apps/AppsBestPractices.md

@@ -0,0 +1,37 @@
+

+
+Keep these general best practices in mind when using applications with TrueNAS:
+
+{{< expand "App Pool Selection" "v" >}}
+
+{{< include file="/static/includes/apps/AppsPoolOrDataset.md" >}}
+
+{{< /expand >}}
+
+{{< expand "App Dataset Types" "v" >}}
+
+{{< include file="/static/includes/apps/AppsDatasets.md" >}}
+
+{{< /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" >}}
+
+{{< include file="/static/includes/apps/AppsCustomApp.md" >}}
+
+{{< /expand >}}
+
+{{< expand "App Directory Services" "v" >}}
+
+{{< 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

@@ -0,0 +1,63 @@
+

+
+**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.
+Any modification of it can result in instability and loss of app functionality.
+
+Do not include the ix-apps dataset inside of an SMB or NFS share.
+
+Back up and restore functionality as well as migration of the ix-apps dataset from one apps pool to another are not currently supported by the TrueNAS interface.
+Support for these features is planned for a future TrueNAS release version.
+
+{{< hint type="note" title="ix-Applications Dataset" >}}
+TrueNAS 24.04 and earlier versions stored applications data in an **ix-applications** dataset on the configured apps pool.
+Systems with applications deployed that upgrade from earlier releases to 24.10 retain the ix-applications dataset.
+During the migration process, 24.10 reads the stored Kubernetes app data in the ix-applications dataset, ports them to Docker, and saves them in the new ix-apps dataset.
+App storage ixVolumes present in ix-applications are cloned under the ix-apps dataset and promoted.
+
+The app data retained in ix-applications enables TrueNAS to revert to 24.04 with functional applications.
+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 allow TrueNAS to automatically create an app storage path inside the hidden ix-apps dataset.
+
+ixVolumes are typically created with appropriate permissions to deploy the application.
+If needed, use **Enable ACL** in **Storage Configuration** to configure ACL entries for an ixVolume.
+
+ixVolumes are not recommended for permanent storage volumes, they are intended for use as rapid storage for a test deployment of the container.
+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 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.
+
+Mounting a host path does not automatically configure appropriate permissions to deploy the application.
+Use **Enable ACL** in **Storage Configuration** to configure ACL entries for each host path.
+
+{{< expand "Configuring Host Path ACL Entries" "v" >}}
+After entering the path inside the container in **Mount Path**, select **Enable ACL**.
+Browse to or enter the path to the dataset in **Host Path**.
+Click **Add** next to **ACL Entries** to display a set of ACE fields.
+Use **ID Type** to select whether the ACE is for a user or a group.
+Enter the UID or GID in **ID** and adjust the permissions level in **Access**.
+
+Refer to the app **Run As Context** on the app details screen for default ID requirements.
+A user or group ID does not need to exist locally on TrueNAS or match the name configured in the container to grant an ACE.
+Failing to configure host path ACLs prevents the app from deploying!
+
+Select **Force Flag** in **ACL Options**.
+This allows TrueNAS to write ACL entries to the storage volume if it has existing data in it.
+**Force Flag** is required to edit or update an existing application.
+{{< /expand >}}
+
+**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/AppsPool.md

@@ -0,0 +1,6 @@
+

+
+We recommend users keep the container use case in mind when choosing an applications pool.
+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.