From ad011248333be4de1bb01f7bacd01509120aa5ed Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 10:03:36 -0500 Subject: [PATCH 01/23] Update _index.md --- content/TruenasApps/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/TruenasApps/_index.md b/content/TruenasApps/_index.md index 166096be48..05e4661253 100644 --- a/content/TruenasApps/_index.md +++ b/content/TruenasApps/_index.md @@ -50,9 +50,9 @@ You must choose a pool before you can install an application. {{< /expand >}} -{{< expand "App Dataset and File Sharing" "v" >}} +{{< expand "App Datasets" "v" >}} -{{< include file="/static/includes/apps/AppsFileSharing.md" >}} +{{< include file="/static/includes/apps/AppsDatasets.md" >}} {{< /expand >}} @@ -88,7 +88,7 @@ You must set the pool before you can add any application. 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 also recommend using SSD storage for the applications pool. +For stability, we recommend using SSD storage for the applications pool. Select the pool and click **Save**. If you close the dialog to set the pool later, click **Configuration > Choose Pool** to set the pool. From 38bb063ec0d635f453730d2a65f205f2d0df1039 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 10:03:38 -0500 Subject: [PATCH 02/23] Update _index.md --- content/TruenasApps/EnterpriseApps/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/TruenasApps/EnterpriseApps/_index.md b/content/TruenasApps/EnterpriseApps/_index.md index d2a5cf371f..a72fa7d96b 100644 --- a/content/TruenasApps/EnterpriseApps/_index.md +++ b/content/TruenasApps/EnterpriseApps/_index.md @@ -33,9 +33,9 @@ Keep these general best practices in mind when using applications with TrueNAS: {{< /expand >}} -{{< expand "App Dataset and File Sharing" "v" >}} +{{< expand "App Datasets" "v" >}} -{{< include file="/static/includes/apps/AppsFileSharing.md" >}} +{{< include file="/static/includes/apps/AppsDatasets.md" >}} {{< /expand >}} From 664e144e5fdb0bfe24f7cb5b5f7a11c32307973b Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 10:03:41 -0500 Subject: [PATCH 03/23] Create AppsDatasets.md --- static/includes/apps/AppsDatasets.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 static/includes/apps/AppsDatasets.md diff --git a/static/includes/apps/AppsDatasets.md b/static/includes/apps/AppsDatasets.md new file mode 100644 index 0000000000..e1a4d2e457 --- /dev/null +++ b/static/includes/apps/AppsDatasets.md @@ -0,0 +1,28 @@ + + +There are two general types of datasets used for app storage in TrueNAS: + +**ix-apps Dataset** + +TrueNAS 24.10 and newer + + + +{{< 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 continue to see 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 ix-volumes 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. +{{< /hint >}} + +**host path datasets** + + + From a7950e2fae669c0efec292d0124daded2dde7a15 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 10:03:43 -0500 Subject: [PATCH 04/23] Delete AppsFileSharing.md --- static/includes/apps/AppsFileSharing.md | 11 ----------- 1 file changed, 11 deletions(-) delete mode 100644 static/includes/apps/AppsFileSharing.md diff --git a/static/includes/apps/AppsFileSharing.md b/static/includes/apps/AppsFileSharing.md deleted file mode 100644 index 55b2493337..0000000000 --- a/static/includes/apps/AppsFileSharing.md +++ /dev/null @@ -1,11 +0,0 @@ - - -TrueNAS provides two default storage options, ixVolumes and host path to a pre-existing dataset. - -Selecting the ixVolume allows TrueNAS to create the storage volume for the application. -If the application requires datasets with specific names, you must create them before launching the application installation wizard. - -{{< hint type=info >}} -Earlier versions of TrueNAS had issues with apps failing to deploy if the application and an SMB or NFS share had the same host path to a dataset. -This issue no longer exists, but we still recommended creating datasets for applications that do not share the same host path as an SMB or NFS share. -{{< /hint >}} \ No newline at end of file From b83a51ad408ecdef7baebc7ead650086b357d09a Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 10:03:45 -0500 Subject: [PATCH 05/23] Update AppsInstallWizardSettings.md --- .../apps/AppsInstallWizardSettings.md | 25 +++++++------------ 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/static/includes/apps/AppsInstallWizardSettings.md b/static/includes/apps/AppsInstallWizardSettings.md index f1b0703d91..4c41085498 100644 --- a/static/includes/apps/AppsInstallWizardSettings.md +++ b/static/includes/apps/AppsInstallWizardSettings.md @@ -31,32 +31,25 @@ All apps in the **stable** train, some **community** train apps, and all apps in * **Storage Configuration** shows options to configure storage for the application. Storage configuration can include the primary data mount volume, a configuration volume, postgres volumes, and an option to add additional storage volumes. The primary mount volumes have two options: -* **ixVolume** that creates a storage volume inside the hidden **ix-apps** dataset. This is the default setting. -* **Host Path** that allows you to select an existing dataset created for the application. Shows additional fields to select the path to the dataset and add the mount point. + * **ixVolume** creates a storage volume inside the hidden **ix-apps** dataset. This is the default setting. + * **Host Path** allows you to select an existing dataset created for the application. Shows additional fields to select the path to the dataset and add the mount point. ixVolumes are not recommended for permanent storage volumes, they are intended for use as rapid storage for a test deployment of the container. We recommend adding datasets and configuring the container storage volumes with the host path option. - Host path add existing dataset(s) as the storage volumes. You must configure the datasets before beginning the app installation using the wizard. + Host paths add existing dataset(s) as the storage volumes. + You must configure the datasets before beginning the app installation using the wizard. - {{< hint type="note" title="ix-apps Dataset" >}} - The **ix-apps** dataset is for internal use only. - - TrueNAS systems with applications deployed that upgrade from earlier releases to 24.10 continue to see the **ix-Applications** dataset on the pool chosen for applications to use. - New installs or systems upgrading where applications are not deployed and a pool is not chosen for apps use the hidden **ix-apps** dataset. - Choosing the pool for apps to use, creates this dataset to store all container-related data. - To expose storage volumes found in the **ix-applications** dataset, take a recursive snapshot. - {{< /hint >}} - - Some applications require specific storage volumes for configuration and other data. Apps with these requirements might indicate this in the wizard UI but refer to tutorials for specifics. - After configuring required storage volumes you can add storage volumes. + Some applications require specific storage volumes for configuration and other data. + Apps with these requirements might indicate this in the wizard UI but refer to tutorials for specifics. + After configuring required storage volumes you can add additional storage volumes if needed. Click **Add** to select the type of storage and configure additional storage volumes for the application. The three storage options are: * **ixVolume** * **Host path** - * **SMB share** that allows you to create a storage volume used by an SMB share. + * **SMB share** that allows you to create a storage volume used by an SMB share. - An SMB share option allows you to configure a share for the application to use. + An SMB share option allows you to mount a persistent claim top an SMB share for the application to use. If the application requires specific datasets or you want to allow SMB share access, configure the dataset(s) and SMB share before using the installation wizard. ixVolumes do not require setting up an ACL and ACE entry but host paths do. From 30ad31a4c03ddeb8db02eb0d66e86545b13717f5 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 10:03:47 -0500 Subject: [PATCH 06/23] Update AppsPoolOrDataset.md --- static/includes/apps/AppsPoolOrDataset.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/static/includes/apps/AppsPoolOrDataset.md b/static/includes/apps/AppsPoolOrDataset.md index df85be1bfb..543857a7b7 100644 --- a/static/includes/apps/AppsPoolOrDataset.md +++ b/static/includes/apps/AppsPoolOrDataset.md @@ -3,7 +3,6 @@ We recommend users keep the container use case in mind when choosing a pool. Select a pool with enough space for all the application containers you intend to use. -TrueNAS creates the **ix-apps** dataset on the chosen pool and uses it to store all container-related data. This is for internal use only. +For stability, we recommend using SSD storage for the applications pool. -TrueNAS provides two default storage options, the default ixVolume or setting a host path to a preexisting dataset. -If you intend to store your application data in a location separate from other storage on your system, create a new dataset before launching the app installation wizard. + From bf6621c502494cc36e198ce3d43acf5b6289e250 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 10:23:15 -0500 Subject: [PATCH 07/23] Update AppsDatasets.md --- static/includes/apps/AppsDatasets.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/static/includes/apps/AppsDatasets.md b/static/includes/apps/AppsDatasets.md index e1a4d2e457..1c2bedea3e 100644 --- a/static/includes/apps/AppsDatasets.md +++ b/static/includes/apps/AppsDatasets.md @@ -4,12 +4,13 @@ There are two general types of datasets used for app storage in TrueNAS: **ix-apps Dataset** -TrueNAS 24.10 and newer +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 for internal use only. - +App data storage configured using {{< 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. +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 continue to see 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 ix-volumes present in ix-applications are cloned under the ix-apps dataset and promoted. From 05bdf1fa81bd6be9cad70f0ab4168f4dd5beee3d Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 12:39:11 -0500 Subject: [PATCH 08/23] Update _index.md --- content/TruenasApps/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/TruenasApps/_index.md b/content/TruenasApps/_index.md index 05e4661253..da7ebd8698 100644 --- a/content/TruenasApps/_index.md +++ b/content/TruenasApps/_index.md @@ -50,7 +50,7 @@ You must choose a pool before you can install an application. {{< /expand >}} -{{< expand "App Datasets" "v" >}} +{{< expand "App Dataset Types" "v" >}} {{< include file="/static/includes/apps/AppsDatasets.md" >}} From e422a9f03135a01d0876943b3047c81c3c457d4e Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 12:39:13 -0500 Subject: [PATCH 09/23] Update _index.md --- content/TruenasApps/EnterpriseApps/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/TruenasApps/EnterpriseApps/_index.md b/content/TruenasApps/EnterpriseApps/_index.md index a72fa7d96b..61802c4176 100644 --- a/content/TruenasApps/EnterpriseApps/_index.md +++ b/content/TruenasApps/EnterpriseApps/_index.md @@ -33,7 +33,7 @@ Keep these general best practices in mind when using applications with TrueNAS: {{< /expand >}} -{{< expand "App Datasets" "v" >}} +{{< expand "App Dataset Types" "v" >}} {{< include file="/static/includes/apps/AppsDatasets.md" >}} From 89c3fc6adf495b6031492a3474a634305ab0c803 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 12:39:15 -0500 Subject: [PATCH 10/23] Update AppsDatasets.md --- static/includes/apps/AppsDatasets.md | 34 ++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/static/includes/apps/AppsDatasets.md b/static/includes/apps/AppsDatasets.md index 1c2bedea3e..e0a6ff2bc6 100644 --- a/static/includes/apps/AppsDatasets.md +++ b/static/includes/apps/AppsDatasets.md @@ -1,29 +1,49 @@ -There are two general types of datasets used for app storage in TrueNAS: - **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 for internal use only. -App data storage configured using + {{< 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 continue to see 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 ix-volumes present in ix-applications are cloned under the ix-apps dataset and promoted. +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. {{< /hint >}} - -**host path datasets** - + +**ixVolume Datasets** + +Choose **ixVolume** in app storage configuration to allow TrueNAS to automatically create a storage volume 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 adding datasets and configuring the container storage volumes with the host path option. + +**Host Path Datasets** + +**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). From 2fe239aaa64e7d37befc69870427e2ac83304c59 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 12:39:17 -0500 Subject: [PATCH 11/23] Update AppsInstallWizardSettings.md --- static/includes/apps/AppsInstallWizardSettings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/static/includes/apps/AppsInstallWizardSettings.md b/static/includes/apps/AppsInstallWizardSettings.md index 4c41085498..1742c3f071 100644 --- a/static/includes/apps/AppsInstallWizardSettings.md +++ b/static/includes/apps/AppsInstallWizardSettings.md @@ -47,9 +47,9 @@ All apps in the **stable** train, some **community** train apps, and all apps in The three storage options are: * **ixVolume** * **Host path** - * **SMB share** that allows you to create a storage volume used by an SMB share. + * **SMB share** that allows you to mount an SMB share as a Docker storage volume. - An SMB share option allows you to mount a persistent claim top an SMB share for the application to use. + An SMB share option allows you to mount an SMB share as a Docker volume for the application to use. If the application requires specific datasets or you want to allow SMB share access, configure the dataset(s) and SMB share before using the installation wizard. ixVolumes do not require setting up an ACL and ACE entry but host paths do. From 3180ebf69acfa27358f0987eb88d6febca455efe Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 12:39:19 -0500 Subject: [PATCH 12/23] Update AppsPoolOrDataset.md --- static/includes/apps/AppsPoolOrDataset.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/static/includes/apps/AppsPoolOrDataset.md b/static/includes/apps/AppsPoolOrDataset.md index 543857a7b7..f4b59738d6 100644 --- a/static/includes/apps/AppsPoolOrDataset.md +++ b/static/includes/apps/AppsPoolOrDataset.md @@ -1,8 +1,8 @@ -We recommend users keep the container use case in mind when choosing a pool. +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 applications pool. +For stability, we recommend using SSD storage for the apps pool. From 3962ea80c7f0bf31b9550565337bc7b9afa365a5 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 19 Nov 2024 15:27:12 -0500 Subject: [PATCH 13/23] Update AppsDatasets.md --- static/includes/apps/AppsDatasets.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/static/includes/apps/AppsDatasets.md b/static/includes/apps/AppsDatasets.md index e0a6ff2bc6..63f9d49bdf 100644 --- a/static/includes/apps/AppsDatasets.md +++ b/static/includes/apps/AppsDatasets.md @@ -3,8 +3,13 @@ **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. + + + +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 continue to see the ix-applications dataset. +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. +It can be safely removed after fully migrating to 24.10, but apps will not function if reverted to 24.04 without the ix-applications dataset. {{< /hint >}} - - **ixVolume Datasets** -Choose **ixVolume** in app storage configuration to allow TrueNAS to automatically create a storage volume inside the hidden ix-apps dataset. +**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 adding datasets and configuring the container storage volumes with the host path option. +We recommend manually adding datasets and configuring container storage volumes with the host path option. **Host Path Datasets** +**Host Path** datasets allow users to mount existing TrueNAS storage paths to locations within the app container. +Create the TrueNAS dataset(s) before assigning them as host paths within the app installation screen. + + **SMB Share Volumes** Some app storage configurations include the **SMB/CIFS Share** option. From 64b7326715e975204593d15eb6612e4b725e5556 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Wed, 20 Nov 2024 11:18:21 -0500 Subject: [PATCH 15/23] Update _index.md --- content/TruenasApps/_index.md | 32 +------------------------------- 1 file changed, 1 insertion(+), 31 deletions(-) diff --git a/content/TruenasApps/_index.md b/content/TruenasApps/_index.md index da7ebd8698..dfd5ceb5af 100644 --- a/content/TruenasApps/_index.md +++ b/content/TruenasApps/_index.md @@ -44,37 +44,7 @@ Make sure the application is required for your specific use requirements and doe You must choose a pool before you can install an application. -{{< 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" >}} - -{{< /expand >}} +{{< include file="/static/includes/apps/AppsBestPractices.md" >}} For more information on screens and screen functions, refer to the UI Reference article on [Apps Screens]({{< relref "SCALE/SCALEUIReference/Apps/_index.md" >}}). From c1caebadb6ad01b88228d5e9e9b863ed676afa51 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Wed, 20 Nov 2024 11:18:23 -0500 Subject: [PATCH 16/23] Update _index.md --- content/TruenasApps/EnterpriseApps/_index.md | 36 +------------------- 1 file changed, 1 insertion(+), 35 deletions(-) diff --git a/content/TruenasApps/EnterpriseApps/_index.md b/content/TruenasApps/EnterpriseApps/_index.md index 61802c4176..fff05fb2d4 100644 --- a/content/TruenasApps/EnterpriseApps/_index.md +++ b/content/TruenasApps/EnterpriseApps/_index.md @@ -25,41 +25,7 @@ TrueNAS is certified with leading hypervisors and backup solutions to streamline TrueNAS Enterprise storage appliances deliver a wide range of features and scalability for virtualization and private cloud environments, with the ability to create off-site backups with scheduled sync and replication features. TrueNAS applications expand the capabilities of your system by adding third-party software but can add significant risk to system stability and security. -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 "Docker Compose 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 >}} +{{< include file="/static/includes/apps/AppsBestPractices.md" >}} For more information on configuring general application functions and installation wizard screens, see [TrueNAS Apps]({{< relref "/content/TruenasApps/_index.md" >}}). From a25b4a1b031e821d5dd919f84337385aa5d9dbc5 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Wed, 20 Nov 2024 11:18:25 -0500 Subject: [PATCH 17/23] Create AppsBestPractices.md --- static/includes/apps/AppsBestPractices.md | 37 +++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 static/includes/apps/AppsBestPractices.md diff --git a/static/includes/apps/AppsBestPractices.md b/static/includes/apps/AppsBestPractices.md new file mode 100644 index 0000000000..a90e91324b --- /dev/null +++ b/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 >}} From 777eb4daef646aaeaf0e7e58c41b6164d06567d9 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Wed, 20 Nov 2024 11:18:27 -0500 Subject: [PATCH 18/23] Update AppsDatasets.md --- static/includes/apps/AppsDatasets.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/static/includes/apps/AppsDatasets.md b/static/includes/apps/AppsDatasets.md index 34c28d9276..f71cc87464 100644 --- a/static/includes/apps/AppsDatasets.md +++ b/static/includes/apps/AppsDatasets.md @@ -35,9 +35,27 @@ We recommend manually adding datasets and configuring container storage volumes **Host Path Datasets** -**Host Path** datasets allow users to mount existing TrueNAS storage paths to locations within the app container. +**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** From 09b552d15eae23190863541a40bc248496aa2cc5 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Wed, 20 Nov 2024 11:18:29 -0500 Subject: [PATCH 19/23] Update AppsInstallWizardSettings.md --- .../includes/apps/AppsInstallWizardSettings.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/static/includes/apps/AppsInstallWizardSettings.md b/static/includes/apps/AppsInstallWizardSettings.md index 1742c3f071..9de6be3f5e 100644 --- a/static/includes/apps/AppsInstallWizardSettings.md +++ b/static/includes/apps/AppsInstallWizardSettings.md @@ -52,12 +52,20 @@ All apps in the **stable** train, some **community** train apps, and all apps in An SMB share option allows you to mount an SMB share as a Docker volume for the application to use. If the application requires specific datasets or you want to allow SMB share access, configure the dataset(s) and SMB share before using the installation wizard. - ixVolumes do not require setting up an ACL and ACE entry but host paths do. - After entering the dataset name as the mount point, select **Enable ACL** to browse to or enter the path to the dataset. - Enter the UID for either the default user assigned to the app or the UID for the TrueNAS user created to serve as the app administrator as the user in the ACE entry and set permissions to full control. - Failing to enable host path ACLs prevents the app from deploying! + ixVolumes do not require setting up an Access Control List (ACL) and Access Control Entry (ACE) in the app configuration settings, but host paths do. + 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** to allow TrueNAS to update the application to the next version. This allows updates and writing to the storage volume if it has data in it. + 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. * **Resources Configuration** shows CPU and memory settings for the container pod. In most cases, you can accept the default settings, or you can change these settings to limit the system resources available to the application. From 7c1789a8fdcdb794f18ee24e9b25c939d420a20b Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Wed, 20 Nov 2024 11:18:31 -0500 Subject: [PATCH 20/23] Update AppsPoolOrDataset.md --- static/includes/apps/AppsPoolOrDataset.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/static/includes/apps/AppsPoolOrDataset.md b/static/includes/apps/AppsPoolOrDataset.md index f4b59738d6..b3dd9ff6b6 100644 --- a/static/includes/apps/AppsPoolOrDataset.md +++ b/static/includes/apps/AppsPoolOrDataset.md @@ -4,5 +4,3 @@ 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. - - From f41bd1877db1ee5c096f800cb6fb7d4e8565f135 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Wed, 20 Nov 2024 11:23:36 -0500 Subject: [PATCH 21/23] remove legacy ix-applications mentions --- content/SCALE/SCALEUIReference/Datasets/_index.md | 4 ++-- static/includes/CreateDatasetSCALE.md | 2 +- static/includes/apps/AppsSMBErrorWarning.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/content/SCALE/SCALEUIReference/Datasets/_index.md b/content/SCALE/SCALEUIReference/Datasets/_index.md index 5e84341b5a..9bcbbf2224 100644 --- a/content/SCALE/SCALEUIReference/Datasets/_index.md +++ b/content/SCALE/SCALEUIReference/Datasets/_index.md @@ -192,7 +192,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 >}} @@ -275,7 +275,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:
  • **Generic** - Select for general storage datasets that are not associated with SMB shares, or apps. Sets the ACL to POSIX.
  • **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.
  • **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.
  • **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.
    • 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:
  • **Generic** - Select for general storage datasets that are not associated with SMB shares, or apps. Sets the ACL to POSIX.
  • **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.
  • **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.
  • **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.
    • Setting cannot be edited after saving the dataset. | {{< /truetable >}} {{< /expand >}} diff --git a/static/includes/CreateDatasetSCALE.md b/static/includes/CreateDatasetSCALE.md index aea57d02df..a1f4ce9656 100644 --- a/static/includes/CreateDatasetSCALE.md +++ b/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. diff --git a/static/includes/apps/AppsSMBErrorWarning.md b/static/includes/apps/AppsSMBErrorWarning.md index 1567df09d1..5a0ad39911 100644 --- a/static/includes/apps/AppsSMBErrorWarning.md +++ b/static/includes/apps/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. \ No newline at end of file +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. From 68434a3a96a93e8a072f51221d1fdfead0dd1272 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Wed, 20 Nov 2024 11:42:54 -0500 Subject: [PATCH 22/23] Rename pool snippet --- static/includes/apps/{AppsPoolOrDataset.md => AppsPool.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename static/includes/apps/{AppsPoolOrDataset.md => AppsPool.md} (100%) diff --git a/static/includes/apps/AppsPoolOrDataset.md b/static/includes/apps/AppsPool.md similarity index 100% rename from static/includes/apps/AppsPoolOrDataset.md rename to static/includes/apps/AppsPool.md From b4252ae4d46eebad4a61c0054281e2cbaad187b2 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Wed, 20 Nov 2024 15:00:31 -0500 Subject: [PATCH 23/23] Update static/includes/apps/AppsDatasets.md Co-authored-by: MicJ <92740932+micjohnson777@users.noreply.github.com> --- static/includes/apps/AppsDatasets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/includes/apps/AppsDatasets.md b/static/includes/apps/AppsDatasets.md index f71cc87464..7fca76ed22 100644 --- a/static/includes/apps/AppsDatasets.md +++ b/static/includes/apps/AppsDatasets.md @@ -19,7 +19,7 @@ App storage ixVolumes present in ix-applications are cloned under the ix-apps da 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 will not function if reverted to 24.04 without 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**