From e1f4599f65700c0cb327d4559a18f63320857ad2 Mon Sep 17 00:00:00 2001 From: MicJ Date: Tue, 26 Nov 2024 09:50:13 -0500 Subject: [PATCH 01/20] PD-1556 Update Apps Contribution and Tutorial Template This PR updates the apps tutorial template and changes embedded instructions to commented-out content instead of using code blocks that didn't render well. It also updates the contributing article to provide more instructions on using the tutorial template. --- .../Applications/AppArticleTemplate.md | 262 ++++++++++++------ content/Contributing/Applications/_index.md | 117 +++++++- 2 files changed, 287 insertions(+), 92 deletions(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index 25bfabb3dc..62453fed6e 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -11,24 +11,51 @@ tags: {{< hint type=note title="Work in Progress" >}} This partial template is awaiting further development. Check back for updates! + +Template instructions are commented out of the rendered copy of this template but show in the Markdown file. {{< /hint >}} + -``` -``` *AppName* is a community-maintained application. -Enter a description of this app and common or specific uses for it. Also, include any links to documentation created by the application developer. + ## Before You Begin -``` -``` -Enter information about the configuration or preparation steps required before beginning the installation process. + +

}} + + +{{< include file="/static/includes/apps/BeforeYouBeginAddNewAppUser.md" >}} + + + +## Installing the Application +{{< hint info >}} +This basic procedure covers the required *appName* app settings. +For optional settings, see [Understanding App Installation Wizard Settings](#understanding-app-installation-wizard-settings). +{{< /hint >}} -Click on the widget to open the ***AppNName*** information screen. +{{< include file="/static/includes/apps/AddMultipleAppInstancesAndNaming.md" >}} +{{< include file="/static/includes/apps/LocateAndOpenInstallWizard.md" >}} + {{\< trueimage src="/images/SCALE/Apps/AppNameDetailsScreen.png" alt="*AppName* Information Screen" id="*AppName* Information Screen" >}} -Click **Install** to open the **Install *AppNName*** configuration wizard. +{{< include file="/static/includes/apps/AppsWizardAppNameAndVersion.md" >}} + + +Enter the ***App* Configuration** settings. + +The TrueNAS app is configured with all the required environment variables, but if you want to further customize the container, click **Add** to the right of **Additional Environment Variables** for each to enter the variable(s) and values(s). + + + *AppName* app.Add your **Storage Configuration** settings. + +Set **Host Path (Path that already exists on the system)** in **Type** for ***Data Storage***. +Select **Enable ACL**, and then enter or browse to and select the **data** dataset to populate the **Host Path** field. + + +Select **Add** to the right of **ACL Entries** for each user or group entry you want to add. +For example, add the **568** user and **0**, and give each **FULL_CONTROL Access**. + +Select **Force Flag**. + +Repeat the storage steps above each additional storage volume. + +Accept the defaults in **Resources Configuration**, and select the GPU option if applicable. + +Click **Install**. A progress dialog displays before switching to the **Installed** applications screen. +The **Installed** screen displays with the **nextcloud** app in the **Deploying** state. Status changes to **Running** when ready to use. + +Click **Web Portal** on the **Application Info** widget to open the *AppName* web portal sign-in screen. + +## Understanding App Installation Wizard Settings +The following section provides more detailed explanations of the settings in each section of the **Install *Appname*** installation wizard. + + +### Application Name Settings + +{{< include file="/static/includes/apps/AppsWizardAppNameAndVersion.md" >}} + +### *AppName* Configuration Settings + +*AppName* configuration settings include setting up credentials, *APT packages* (previously referred to as the commands), the *host IP and port, data directory path, upload limits, execution times, memory limits and cache memory consumption, adding a cron job with schedule, and adding additional environment variables*. + +If you have an existing *AppName* account add the credentials for that account in the **Admin User** and **Admin Password** fields. +If you do not have an existing account enter the name and password you want to use to create the *AppName* login credentials. + +#### Adding Environment Variables +{{< include file="/static/includes/apps/AppInstallWizardEnvironVariablesSettings.md" >}} +Refer to [*AppName* documentation](URL for environment variables documentation provided in the app provider) for more information on environment variables. + + +### User and Group Configuration + -{{\< trueimage src="/images/SCALE/Apps/InstallAppNameScreen.png" alt="Install *AppName* Screen" id="Install *AppName* Screen" >}} +{{< include file="/static/includes/apps/AppInstallWizardUserAndGroupConfig.md" >}} -Scroll down to each section or click the navigation menu item on the right of the screen to jump to that section. +The run-as user information is found on the *AppName* app details screen in the **Run-As Content** widget. + -Accept the default name or enter a new name for your application if you prefer. -Enter a name that consists of, and begins or ends with lowercase alphanumeric characters. -Do not use a hyphen as the first or last character. For example, *appName*, or *app-name*, but not *-appName* or *appName-*. +### Network Configuration +The default web port for *AppName* is ***30027***. + +{{< include file="/static/includes/apps/AppInstallWizardNetworkConfig.md" >}} +{{< include file="/static/includes/apps/AppsInstallWizardDefaultPorts.md" >}} +{{< include file="/static/includes/apps/AppsInstallWizardAdvancedDNSSettings.md" >}} +{{< include file="/static/includes/apps/AppInstallWizardCertificateSettings.md" >}} -Do not change the **Version**. TrueNAS alerts you when a new version is available for deployed apps, and allows you to update through the click of a button on the **Installed** application screen. +### Storage Configuration +TrueNAS provides two options for storage volumes: ixVolumes and host paths. -1. Enter the ***AppName* Configuration** settings: +{{< include file="/static/includes/apps/InstallAppsStorageConfig.md" >}} + - {{\< trueimage src="/images/SCALE/Apps/InstallAppNameNetworkConfig.png" alt="*AppName* Network Settings" id="*AppName* Network Settings" >}} +{{< include file="/static/includes/apps/InstallAppsStorageConfig2.md" >}} -4. Accept the default **Network Configuration** settings unless you need to add custom settings. - If you want to use different ports, check the [Default Ports](https://www.truenas.com/docs/references/defaultports/) for a list of available or unavailable port numbers. - Leave **Host Network** unselected. +See **Mounting an SMB Share** below for details. -5. Configure the **Storage Configuration** settings. - You can use the default **ixVolume** option to allow TrueNAS to create a data storage volume or select **Host Path** to select the path to the new datasets created earlier in this document. +{{< expand "Creating App Datasets" "v" >}} +To create the *AppName* app datasets, go to **Datasets**, select the dataset you want to use as the parent dataset, then click **Add Dataset** to [add a dataset]({{< relref "DatasetsScale.md" >}}). +In this example, we create the *AppName* datasets under the root parent dataset ***tank***. - {{\< trueimage src="/images/SCALE/Apps/InstallAppNameStorage.png" alt="Add Datasets" id="Add Datasets" >}} +Enter ***AppName*** in **Name**, and select **Apps** as the **Dataset Preset**. +Click **Advanced Options** if you want to make any other setting changes. Click **Save**. +When prompted, select **Return to Pool List** to configure permissions later after adding the other three datasets, or open the ACL editor to edit ACL permissions immediately after adding the dataset. - Select the option to configure ACL entries if you want to configure this while installing the app, otherwise, use the **Permissions** widget for each dataset to edit ACL settings and ACE entries for the app user. +Next, select the ***AppName*** dataset, and click **Add Dataset** to add the first child dataset. +Enter ***config*** in **Name** and select **Apps** as the **Dataset Preset**. +Click **Advanced Options** if you want to make any other setting changes. Click **Save**. - To modify the dataset permissions, select **Enable ACL** to show the option to create an ACL entry to customize the dataset permissions. - - Repeat the above for any additional datasets. +Repeat this to add the other child datasets to the ***AppName*** parent dataset. +When finished you should have the ***AppName*** parent dataset with *three* child datasets under it. Our example paths are: +* */mnt/tank/appname/****config*** +* */mnt/tank/appname/****data*** +* */mnt/tank/appname/****postgresdata*** + - Setting up an SMB share option to set up data sharing using SMB. +#### ACL and ACE Settings -6. Review the **Resource Configuration** settings. - Accept the default values or enter new CPU and memory values. - By default, this application is limited to using no more than 2 CPUs and 4096 megabytes of available memory. - The application might use considerably less system resources. +{{< include file="/static/includes/apps/InstallWizardACLConfiguration.md" >}} - To customize the CPU and memory allocated to the container uses, enter new CPU values as a plain integer value. - The default is 2, which means the app can use 2 cores. +#### Mounting an SMB Share +TrueNAS **Additional Storage** options include the ability to mount an SMB share inside the container pod. - Accept the default value of 4096 MB allocated memory or enter a new limit in megabytes. - Enter a plain integer. For example, 8192. +{{< include file="/static/includes/apps/InstallWizardStorageSMBOption.md" >}} -7. Click **Install**. - The system opens the **Installed** applications screen with the *AppName* app in the **Deploying** state. - When the installation completes it changes to **Running**. +### Resource Configuration + -### Using the Web Portal -Click **Web Portal** on the **Application Info** widget to open the application web interface. +{{< include file="/static/includes/apps/InstallWizardResourceConfig.md" >}} +{{< include file="/static/includes/apps/InstallWizardGPUPassthrough.md" >}} -The time required to install the app varies depending on your hardware and network configuration. -``` -``` +## Troubleshooting Tips \ No newline at end of file diff --git a/content/Contributing/Applications/_index.md b/content/Contributing/Applications/_index.md index 6a21bb627b..57e30ef6e1 100644 --- a/content/Contributing/Applications/_index.md +++ b/content/Contributing/Applications/_index.md @@ -37,7 +37,7 @@ Users can submit changes to an existing application catalogs through: To request a feature change, go to the [TrueNAS Community Forum](https://forums.truenas.com/), and click **Feature Request**. Read the **About the Feature Requests category - README First** topic, then click **Open Draft** on the top right of the screen. Populate the new request form with the relevant information for each section, **Problem/Justification**, **Impact**, and **User Story**. - The form provides guidance on how to populate these sections. + The form guides you on populating these sections. Click **Create Topic** to add your suggestion to the list of topics. Users vote and comment on these suggestions. @@ -49,23 +49,118 @@ Users can submit changes to an existing application catalogs through: To see a current list of apps, visit the [TrueNAS Apps repository](https://github.com/truenas/apps) on GitHub. ## Contributing to TrueNAS Application Documentation -Community members can submit change requests or add new tutorials to the Community Apps tutorials section of the Documentation Hub. +Community members can submit change requests or add new tutorials to the **Truenas Apps > Community Apps** tutorials section of the Documentation Hub. + For more information on submitting change requests, forking repos, and submitting PRs, see [Updating Content]({{< relref "/Contributing/Documentation/ContentUpdate.md" >}}). +### Submitting New Tutorial Articles When submitting new tutorials or requesting changes to existing TrueNAS Documentation Hub application tutorials: -* Create the PR against a forked copy of the [TrueNAS Documentation Hub public repository](https://github.com/truenas/documentation/tree/master). - - In your local forked repository, open the existing article file in either the **CommunityApps** or the **StableApps** folder of the **/content/TrueNASApps/** directory. +1. Create the PR against a forked copy of the [TrueNAS Documentation Hub public repository](https://github.com/truenas/documentation/tree/master). + +2. Open the existing article file in the /content/TrueNASApps/CommunityApps directory of your local forked repository. - If submitting a new tutorial, add the new tutorial to the **CommunityApps** folder in your local copy of the repository. +3. Add the new tutorial to the CommunityApps folder in your local copy of the repository if submitting a new tutorial. - Use the text editor of your choice to make changes to the [application tutorial template]({{< relref "/Contributing/Applications/AppArticleTemplate.md" >}}) as the basis for your new article. +4. Use the text editor of your choice to make changes to the [application tutorial template]({{< relref "/Contributing/Applications/AppArticleTemplate.md" >}}) as the basis for your new article. Article content is written in Commonmark Markdown. - (Optional) Save images in the **/documentation/static/images/scale/apps** folder of your local branch. +5. (Optional) Save images in the **/documentation/static/images/scale/apps** folder of your local branch. + +6. Submit the PR against the **Master** branch. + +### Using the App Tutorial Template +Upon opening the app tutorial template Markdown file, delete the commented-out sections that provide instructions for using it. +Feel free to change standard article content by adding or removing sections to fit the app installation process. +Change the front matter description: parameter at the top of the article to suit the subject and content of the new tutorial. +The description: text must not exceed 160 alphanumeric or special characters, including spaces between characters. - Submit the PR against the **Master** branch. +#### Formatting Tips for Content Development +Standard text emphasis: +* Apply **Bold** to UI elements seen on the screen, including field, button, and navigation option names, other descriptions, etc. + Use double asterisks preceding and following the name or text string to make it bold. + Do not use bold in code strings. -* Click **Edit Article** at the top of the Documentation Hub article to request changes to an existing article. - Refer to the [Content Updates]({{< relref "/Contributing/Documentation/ContentUpdate.md" >}}) article for more details. +* Apply *Italics* to any variable. + Use single asterisks preceding and following the name or text string to make it italics. + If using a variable in a code example, use the HTML tags and not the Markdown tags. + +* Apply HTML file tags when entering a path to a file or file name, for example iso. + +* Apply HTML keyboard tags to keys on a keyboard, such as Enter. + +When entering commands, command strings, or code blocks: + +* Apply backticks(`) or HTML tags to format command strings or output. + +* Apply HTML tags to strings with variables. + + * Do not enclose variables in angle or square brackets as these can also be part of command syntax. + + * Do not enter variables in all caps unless the command requires entering the value in all caps. + +To create a code block, either use three backticks on the line before and after the content block, or use the HTML code tags. + +#### Using the Apps Snippet Library +When creating your articles you can use the library of snippets that contain explanations of settings and configuration instructions for the various app Install Wizard settings in your submitted content. +These snippets are maintained by the Technical Documentation team, but you can submit change requests for these files just as with full articles if you find content that needs updating or changing. + +The tutorial template includes the shortcode that calls these files into the app wizard sections of the Stable Apps and Enterprise Apps tutorials in the Documentation Hub. +To use snippets where the template does not have one, enter the include file shortcode where you want to call another snippet. +The shortcode to call snippet files is {{< include file="/static/includes/apps/snippetFileName.md" >}} where *snippetFileName.md* is the name of the snippet file. + +The following table shows the current list of snippet files. +{{< expand "App Tutorial Snippet Files" "v" >}} +Snippet files are located in the /documentation/static/includes/apps folder. +Not all snippet files in this folder apply to tutorial content. +Refer to the tables below for a list of snippet files with content about tutorial sections. +Open and read snippet files to determine where to use them in your tutorial. + +**Before You Beging Snippets** +{{< truetable >}} +| File Name | Snippet Use and Content | +|-----------|-------------------------| +| BeforeYouBeginStableApps.md | Bullet point for adding the apps pool, adding a new user for the app administrator, and adding datasets. Does does not include details on adding datasets as these vary by app. | +| BeforeYouBeginAddAppCertificate.md | Bullet point for adding a certificate if required for the app. Also include the AddingAppCertificate.md snippet with detailed instructions on adding a self-signed certificate. | +| AddingAppCertificate.md | Detailed set procedure on adding a self-signed certificate authority (CA) and certificate. | +| BeforeYouBeginAddNewUser.md | Single bullet point and procedure for adding a new user as a TrueNAS app administrator. | +{{< /truetable >}} + +**Installing the App** +{{< truetable >}} +| File Name | Snippet Use and Content | +|-----------|---------------------| +| LocateAndOpenInstallWizard.md | Describes locating the app widget, and opening the install wizard for the app. | + MultipleAppInstancesAndNaming.md | Describes adding more than one instance of the same app and naming it. For example, adding two stable or community app instances, or an enterprise and stable train version of the same app. | +| Configuring the app | InstallWizardEnvironVariablesSettings.md | Details the Environment Variable settings. Can use this if the procedure requires adding environment variables, or leave the snippet in the Understanding App Install Wizard section and refer to it for more information. | +| InstallWizardAdvancedDNSSettings.md | Details the Advanced DNS setting options that might be included as part of the app configuration or network configuration settings. +| | | +| | | +{{< /truetable >}} + +**Understanding App Install Wizard Settings** +{{< truetable >}} +| Wizard Settings | File Name | Snippet Use and Content | +|---------|-----------|---------------------| +| App Name and Version | InstallWizardAppNameAndVersion.md | Details the **Application Name** and **Version** settings. | +| Advanced DNS | InstallWizardAdvancedDNSSettings.md | Details DNS option settings. Might be included as a Network Configuration or App Configuration setting option. | +| Environment Variables | InstallWizardEnvironVariablesSettings.md | Use in the Install Wizard Setting section, or if adding environment variables is required for configuring the app, use in the configuring the app procedure section. | +| Timezone | InstallWizardTimezoneSetting.md | | +| Network (default ports) | InstallWizardDefaultPorts.md | Details changing the default port assignment. Can use this snippet in the Before You Begin and/or Installing the App sections, but is more suited to the section explaining the Network settings. | +| Host Network | InstallWizardHostNetworkSettings.md | Details the **Host Network** setting in the Network Configuration section of the wizard. Use when the wizard includes this setting. | +| Certificate ID | InstallWizardCertificateSettings.md | Details **Certificate ID** settings, that might be optional and recommended, or required to deploy the app. Include this snippet if you used the two certificate snippets in the Before You Begin section. | +| Storage Configuration | InstallAppsStorageConfig.md | Adds the **Setting the Storage Volume Type** expand section detailing storage volume types, configuring host path storage volume ACL permissions using the **Enable ACL** and **ACL Entries** options. Does not cover specific datasets required by the app. | +| Storage Configuration | InstallAppsStorageConfig2.md | Adds the **Configuring Additional Storage Volumes** expand section detailing adding additional storage volumes, with a list of the **Additional Storage** types. | +| Storage ACL permissions | InstallWizardStorageACLConfig.md | Details on the Edit ACL and ACE Entries settings. Includes the **Configuring ACE Entries** expand detailing how to add ACE entries, default user IDs for apps, or postgres storage volumes. | +| Additional Storage SMB Option | InstallWizardStorageSMBOption.md | Details on the Additional Storage volume SMB share option. | +| Storage Temporary and tmpfs directories | InstallWizardStorageTemporaryAndTmpfs.md | Details on the **Temporary** and **Tmpfs** directory storage options that are available as primary and/or additional storage volume types, and when to use each. | +| Users and Groups | InstallWizardUserAndGroupConfig.md | Details user and group setting options. | +| Resource Configuration | InstallWizardResourceConfig.md | Details CPU and memory setting options for all apps. If the app includes GPU passthrough, use with the InstallWizardGPUPassthrough.md snippet. | +| GPU Passthrough | InstallWizardGPUPassthrough.md | Details information on GPU settings if the app includes the GPU passthrough settings. Not present if the app does not detect a GPU device. | +{{< /truetable >}} +{{< /expand >}} + +### Requesting Edits to Existing Articles +Click **Edit Article** at the top of the Documentation Hub article to request changes to an existing article. + +Refer to the [Content Updates]({{< relref "/Contributing/Documentation/ContentUpdate.md" >}}) article for more details. From 416a67191279954fee00e4c8f30aa4f69e5daadb Mon Sep 17 00:00:00 2001 From: MicJ Date: Tue, 26 Nov 2024 09:59:13 -0500 Subject: [PATCH 02/20] PD-1556 Fix formatting issues --- content/Contributing/Applications/_index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/Contributing/Applications/_index.md b/content/Contributing/Applications/_index.md index 57e30ef6e1..a48a1d9784 100644 --- a/content/Contributing/Applications/_index.md +++ b/content/Contributing/Applications/_index.md @@ -107,7 +107,7 @@ These snippets are maintained by the Technical Documentation team, but you can s The tutorial template includes the shortcode that calls these files into the app wizard sections of the Stable Apps and Enterprise Apps tutorials in the Documentation Hub. To use snippets where the template does not have one, enter the include file shortcode where you want to call another snippet. -The shortcode to call snippet files is {{< include file="/static/includes/apps/snippetFileName.md" >}} where *snippetFileName.md* is the name of the snippet file. +The shortcode to call snippet files is include file="/static/includes/apps/snippetFileName.md" enclosed in two curly brackets and one angle bracket preceding and following the string, and where *snippetFileName.md* is the name of the snippet file. The following table shows the current list of snippet files. {{< expand "App Tutorial Snippet Files" "v" >}} @@ -134,8 +134,6 @@ Open and read snippet files to determine where to use them in your tutorial. MultipleAppInstancesAndNaming.md | Describes adding more than one instance of the same app and naming it. For example, adding two stable or community app instances, or an enterprise and stable train version of the same app. | | Configuring the app | InstallWizardEnvironVariablesSettings.md | Details the Environment Variable settings. Can use this if the procedure requires adding environment variables, or leave the snippet in the Understanding App Install Wizard section and refer to it for more information. | | InstallWizardAdvancedDNSSettings.md | Details the Advanced DNS setting options that might be included as part of the app configuration or network configuration settings. -| | | -| | | {{< /truetable >}} **Understanding App Install Wizard Settings** From 542d901d1c5377ad79432004319bf59611800965 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Mon, 2 Dec 2024 15:14:57 -0500 Subject: [PATCH 03/20] Update _index.md --- content/Contributing/Applications/_index.md | 29 +++++++++++---------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/content/Contributing/Applications/_index.md b/content/Contributing/Applications/_index.md index a48a1d9784..7961152e51 100644 --- a/content/Contributing/Applications/_index.md +++ b/content/Contributing/Applications/_index.md @@ -70,10 +70,11 @@ When submitting new tutorials or requesting changes to existing TrueNAS Document 6. Submit the PR against the **Master** branch. ### Using the App Tutorial Template -Upon opening the app tutorial template Markdown file, delete the commented-out sections that provide instructions for using it. Feel free to change standard article content by adding or removing sections to fit the app installation process. Change the front matter description: parameter at the top of the article to suit the subject and content of the new tutorial. -The description: text must not exceed 160 alphanumeric or special characters, including spaces between characters. +Description text must not exceed 160 alphanumeric or special characters, including spaces between characters. +After updating content, delete commented-out sections providing instructions for using this template when they are no longer needed. +When documenting a **Community** train app, not delete any of the commented-out instructions in the COMMUNITY APP INTRO SNIPPETS section. #### Formatting Tips for Content Development Standard text emphasis: @@ -83,23 +84,23 @@ Standard text emphasis: * Apply *Italics* to any variable. Use single asterisks preceding and following the name or text string to make it italics. - If using a variable in a code example, use the HTML tags and not the Markdown tags. + If using a variable in a code example, use the HTML tags (\\) and not the Markdown tags. -* Apply HTML file tags when entering a path to a file or file name, for example iso. +* Apply HTML file tags (\\) when entering a path to a file or file name, for example \iso\, which renders as iso. -* Apply HTML keyboard tags to keys on a keyboard, such as Enter. +* Apply HTML keyboard tags (\\) to keys on a keyboard, for example \Enter\, which renders as Enter. When entering commands, command strings, or code blocks: -* Apply backticks(`) or HTML tags to format command strings or output. +* Apply backticks(\`\`) or HTML \\ tags to format command strings or output, for example \`string\` or \string\, which render as string. -* Apply HTML tags to strings with variables. +* Apply HTML \\ tags to strings with variables. * Do not enclose variables in angle or square brackets as these can also be part of command syntax. * Do not enter variables in all caps unless the command requires entering the value in all caps. -To create a code block, either use three backticks on the line before and after the content block, or use the HTML code tags. +To create a code block, either use three backticks (```) on the line before and after the content block, or use the HTML code tags. #### Using the Apps Snippet Library When creating your articles you can use the library of snippets that contain explanations of settings and configuration instructions for the various app Install Wizard settings in your submitted content. @@ -107,7 +108,7 @@ These snippets are maintained by the Technical Documentation team, but you can s The tutorial template includes the shortcode that calls these files into the app wizard sections of the Stable Apps and Enterprise Apps tutorials in the Documentation Hub. To use snippets where the template does not have one, enter the include file shortcode where you want to call another snippet. -The shortcode to call snippet files is include file="/static/includes/apps/snippetFileName.md" enclosed in two curly brackets and one angle bracket preceding and following the string, and where *snippetFileName.md* is the name of the snippet file. +The shortcode to call snippet files is {{\}}, where *snippetFileName.md* is the name of the snippet file. The following table shows the current list of snippet files. {{< expand "App Tutorial Snippet Files" "v" >}} @@ -116,7 +117,7 @@ Not all snippet files in this folder apply to tutorial content. Refer to the tables below for a list of snippet files with content about tutorial sections. Open and read snippet files to determine where to use them in your tutorial. -**Before You Beging Snippets** +**Before You Begin Snippets** {{< truetable >}} | File Name | Snippet Use and Content | |-----------|-------------------------| @@ -131,9 +132,9 @@ Open and read snippet files to determine where to use them in your tutorial. | File Name | Snippet Use and Content | |-----------|---------------------| | LocateAndOpenInstallWizard.md | Describes locating the app widget, and opening the install wizard for the app. | - MultipleAppInstancesAndNaming.md | Describes adding more than one instance of the same app and naming it. For example, adding two stable or community app instances, or an enterprise and stable train version of the same app. | +| MultipleAppInstancesAndNaming.md | Describes adding more than one instance of the same app and naming it. For example, adding two stable or community app instances, or an enterprise and stable train version of the same app. | | Configuring the app | InstallWizardEnvironVariablesSettings.md | Details the Environment Variable settings. Can use this if the procedure requires adding environment variables, or leave the snippet in the Understanding App Install Wizard section and refer to it for more information. | -| InstallWizardAdvancedDNSSettings.md | Details the Advanced DNS setting options that might be included as part of the app configuration or network configuration settings. +| InstallWizardAdvancedDNSSettings.md | Details the Advanced DNS setting options that might be included as part of the app configuration or network configuration settings. | {{< /truetable >}} **Understanding App Install Wizard Settings** @@ -158,7 +159,7 @@ Open and read snippet files to determine where to use them in your tutorial. {{< /truetable >}} {{< /expand >}} -### Requesting Edits to Existing Articles -Click **Edit Article** at the top of the Documentation Hub article to request changes to an existing article. +### Suggesting Edits to Existing Articles +Click **Edit Article** at the top of the Documentation Hub article to suggest changes to an existing article. Refer to the [Content Updates]({{< relref "/Contributing/Documentation/ContentUpdate.md" >}}) article for more details. From a8783a63d7c60e2372f226b237daf69c179913d8 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Mon, 2 Dec 2024 15:15:01 -0500 Subject: [PATCH 04/20] Update AppArticleTemplate.md --- .../Applications/AppArticleTemplate.md | 120 ++++++++++++------ 1 file changed, 79 insertions(+), 41 deletions(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index 62453fed6e..aa59d41e17 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -8,18 +8,26 @@ tags: - apps --- -{{< hint type=note title="Work in Progress" >}} -This partial template is awaiting further development. +{{< hint type=important icon=gdoc_code title="Work in Progress" >}} +We are actively developing and improving this template. Check back for updates! +{{< /hint >}} + +{{< hint type=note title="How to Use this Template" >}} +To use this template, click **Edit Page** above or locate the Markdown file at [/Contributing/Applications/AppArticleTemplate.md](https://github.com/truenas/documentation/blob/master/content/Contributing/Applications/AppArticleTemplate.md) on the documentation [Github Repository](https://github.com/truenas/documentation). +Copy the template content to your target app tutorial to begin writing. -Template instructions are commented out of the rendered copy of this template but show in the Markdown file. +Detailed template instructions are commented out of the rendered copy of this template but show in the Markdown file. {{< /hint >}} + + + +--- + + + + + + +{{< include file="/static/includes/apps/CommunityApp.md" >}} + + + + + *AppName* is a community-maintained application. +For example: +*AppName* provides a [Quickstart Setup Guide](https://docs.appName/setup) with step-by-step instructions to help users create a *AppName* node. --> ## Before You Begin -Prepare TrueNAS before installing the app by: +Prepare TrueNAS before installing the app by: {{< include file="/static/includes/apps/BeforeYouBeginStableApps.md" >}} - -

}} + +

Create a parent dataset, such as appName, and then the storage datasets (config and data) under it. + Select apps as the Dataset Preset for these datasets. You can modify the dataset ACLs at the time of creation, or modify them later when adding them in the app.

+ + - +

Adding a certificate is optional but if you want to use a certificate for this application, either create a new self-signed CA and certificate or import an existing CA and create the certificate for Nextcloud. A certificate is not required to deploy the application.

--> + + {{< include file="/static/includes/apps/BeforeYouBeginAddNewAppUser.md" >}} - + ## Installing the Application + {{< hint info >}} This basic procedure covers the required *appName* app settings. For optional settings, see [Understanding App Installation Wizard Settings](#understanding-app-installation-wizard-settings). {{< /hint >}} -{{< include file="/static/includes/apps/AddMultipleAppInstancesAndNaming.md" >}} +{{< include file="static/includes/apps/MultipleAppInstancesAndNaming.md" >}} {{< include file="/static/includes/apps/LocateAndOpenInstallWizard.md" >}} - -{{\< trueimage src="/images/SCALE/Apps/AppNameDetailsScreen.png" alt="*AppName* Information Screen" id="*AppName* Information Screen" >}} + -{{< include file="/static/includes/apps/AppsWizardAppNameAndVersion.md" >}} +{{< include file="/static/includes/apps/InstallWizardAppNameAndVersion.md" >}} The TrueNAS app is configured with all the required environment variables, but if you want to further customize the container, click **Add** to the right of **Additional Environment Variables** for each to enter the variable(s) and values(s). - Set **Host Path (Path that already exists on the system)** in **Type** for ***Data Storage***. Select **Enable ACL**, and then enter or browse to and select the **data** dataset to populate the **Host Path** field. - Select **Add** to the right of **ACL Entries** for each user or group entry you want to add. @@ -132,7 +160,9 @@ Click **Web Portal** on the **Application Info** widget to open the *AppName* we + ## Understanding App Installation Wizard Settings + The following section provides more detailed explanations of the settings in each section of the **Install *Appname*** installation wizard. *AppName* configuration settings include setting up credentials, *APT packages* (previously referred to as the commands), the *host IP and port, data directory path, upload limits, execution times, memory limits and cache memory consumption, adding a cron job with schedule, and adding additional environment variables*. -If you have an existing *AppName* account add the credentials for that account in the **Admin User** and **Admin Password** fields. -If you do not have an existing account enter the name and password you want to use to create the *AppName* login credentials. +If you have an existing *AppName* account, add the credentials for that account in the **Admin User** and **Admin Password** fields. +If you do not have an existing account, enter the name and password you want to use to create the *AppName* login credentials. #### Adding Environment Variables -{{< include file="/static/includes/apps/AppInstallWizardEnvironVariablesSettings.md" >}} + +{{< include file="/static/includes/apps/InstallWizardEnvironVariablesSettings.md" >}} Refer to [*AppName* documentation](URL for environment variables documentation provided in the app provider) for more information on environment variables. ### User and Group Configuration - -{{< include file="/static/includes/apps/AppInstallWizardUserAndGroupConfig.md" >}} +{{< include file="/static/includes/apps/InstallWizardUserAndGroupConfig.md" >}} The run-as user information is found on the *AppName* app details screen in the **Run-As Content** widget. +--> ### Network Configuration + The default web port for *AppName* is ***30027***. -{{< include file="/static/includes/apps/AppInstallWizardNetworkConfig.md" >}} -{{< include file="/static/includes/apps/AppsInstallWizardDefaultPorts.md" >}} -{{< include file="/static/includes/apps/AppsInstallWizardAdvancedDNSSettings.md" >}} -{{< include file="/static/includes/apps/AppInstallWizardCertificateSettings.md" >}} +{{< include file="static/includes/apps/InstallWizardHostNetworkSettings.md" >}} +{{< include file="/static/includes/apps/InstallWizardDefaultPorts.md" >}} +{{< include file="/static/includes/apps/InstallWizardAdvancedDNSSettings.md" >}} +{{< include file="/static/includes/apps/InstallWizardCertificateSettings.md" >}} ### Storage Configuration + TrueNAS provides two options for storage volumes: ixVolumes and host paths. {{< include file="/static/includes/apps/InstallAppsStorageConfig.md" >}} @@ -215,16 +248,18 @@ When finished you should have the ***AppName*** parent dataset with *three* chil * */mnt/tank/appname/****config*** * */mnt/tank/appname/****data*** * */mnt/tank/appname/****postgresdata*** - +--> +{{< /expand >}} #### ACL and ACE Settings -{{< include file="/static/includes/apps/InstallWizardACLConfiguration.md" >}} +{{< include file="/static/includes/apps/InstallWizardStorageACLConfig.md" >}} #### Mounting an SMB Share + TrueNAS **Additional Storage** options include the ability to mount an SMB share inside the container pod. {{< include file="/static/includes/apps/InstallWizardStorageSMBOption.md" >}} @@ -236,4 +271,7 @@ TrueNAS **Additional Storage** options include the ability to mount an SMB share {{< include file="/static/includes/apps/InstallWizardResourceConfig.md" >}} {{< include file="/static/includes/apps/InstallWizardGPUPassthrough.md" >}} -## Troubleshooting Tips \ No newline at end of file +## Troubleshooting Tips + + + \ No newline at end of file From feb9983995bbe774a455fa652e0b8ea70c4c13a2 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Tue, 3 Dec 2024 08:53:37 -0500 Subject: [PATCH 05/20] Update AppArticleTemplate.md --- .../Applications/AppArticleTemplate.md | 28 ++++++++++++++++--- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index aa59d41e17..d04a95e900 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -13,12 +13,13 @@ We are actively developing and improving this template. Check back for updates! {{< /hint >}} -{{< hint type=note title="How to Use this Template" >}} -To use this template, click **Edit Page** above or locate the Markdown file at [/Contributing/Applications/AppArticleTemplate.md](https://github.com/truenas/documentation/blob/master/content/Contributing/Applications/AppArticleTemplate.md) on the documentation [Github Repository](https://github.com/truenas/documentation). -Copy the template content to your target app tutorial to begin writing. +## How to Use this Template + +Click **Edit Page** above or locate the Markdown file at [/Contributing/Applications/AppArticleTemplate.md](https://github.com/truenas/documentation/blob/master/content/Contributing/Applications/AppArticleTemplate.md) on the documentation [Github Repository](https://github.com/truenas/documentation). + +Copy the template content to an existing [Community Apps]({{< relref "communityapps.md" >}}) placeholder article or create a new one if needed to begin writing. Detailed template instructions are commented out of the rendered copy of this template but show in the Markdown file. -{{< /hint >}} + + + + + From 8d5d99ac431b3298cdd2268c656d01d3535a5e10 Mon Sep 17 00:00:00 2001 From: MicJ <92740932+micjohnson777@users.noreply.github.com> Date: Tue, 3 Dec 2024 11:19:06 -0500 Subject: [PATCH 06/20] Update AppArticleTemplate.md fix copy/paste error in line 160 --- content/Contributing/Applications/AppArticleTemplate.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index d04a95e900..20f48fbb7e 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -157,7 +157,7 @@ See [User and Group Configuration](#user-and-group-configuration) and [Network C Leave **Host Network** unselected.--> - *AppName* app.Add your **Storage Configuration** settings. +Add your **Storage Configuration** settings. Set **Host Path (Path that already exists on the system)** in **Type** for ***Data Storage***. Select **Enable ACL**, and then enter or browse to and select the **data** dataset to populate the **Host Path** field. @@ -294,4 +294,4 @@ TrueNAS **Additional Storage** options include the ability to mount an SMB share ## Troubleshooting Tips - \ No newline at end of file + From 9df00c5064566838ea9f1430b48692db43175b31 Mon Sep 17 00:00:00 2001 From: MicJ <92740932+micjohnson777@users.noreply.github.com> Date: Tue, 3 Dec 2024 11:25:18 -0500 Subject: [PATCH 07/20] Update _index.md Modified the description for the BeforeYouBeginStableApps.md snippet, removing the new user and add dataset bullet points, and added the new snippet BeforeYouBeginAddAppDatasets.md to the list. This snippet is created in another PR, PD-1626 that modifies the Nextcloud tutorial. --- content/Contributing/Applications/_index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/Contributing/Applications/_index.md b/content/Contributing/Applications/_index.md index 7961152e51..1d39c67b99 100644 --- a/content/Contributing/Applications/_index.md +++ b/content/Contributing/Applications/_index.md @@ -121,7 +121,8 @@ Open and read snippet files to determine where to use them in your tutorial. {{< truetable >}} | File Name | Snippet Use and Content | |-----------|-------------------------| -| BeforeYouBeginStableApps.md | Bullet point for adding the apps pool, adding a new user for the app administrator, and adding datasets. Does does not include details on adding datasets as these vary by app. | +| BeforeYouBeginStableApps.md | Bullet point for adding the apps pool. | +| BeforeYouBegigAddAppDatasets.md | Bullet point for adding datasets for the app. Does does not include details on adding datasets as these vary by app. | BeforeYouBeginAddAppCertificate.md | Bullet point for adding a certificate if required for the app. Also include the AddingAppCertificate.md snippet with detailed instructions on adding a self-signed certificate. | | AddingAppCertificate.md | Detailed set procedure on adding a self-signed certificate authority (CA) and certificate. | | BeforeYouBeginAddNewUser.md | Single bullet point and procedure for adding a new user as a TrueNAS app administrator. | From 136aebd8d24872899899967144f0e5a065a497d8 Mon Sep 17 00:00:00 2001 From: MicJ Date: Fri, 6 Dec 2024 09:30:43 -0500 Subject: [PATCH 08/20] PD-1556 Update Contributin and Template This commit updates the Contributing section _index.md content with the new snippets. It updates the template with new/improved content --- .../Applications/AppArticleTemplate.md | 83 +++++++++---------- 1 file changed, 37 insertions(+), 46 deletions(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index 20f48fbb7e..4c3bd8b03c 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -62,9 +62,11 @@ Refer to the [Contributing to Apps]({{< relref "/content/contributing/applicatio - + + +{{< include file="/static/includes/apps/BeforeYouBeginAddAppDatasets.md" >}} - +

Create a parent dataset, such as appName, and then the storage datasets (config and data) under it. Select apps as the Dataset Preset for these datasets. You can modify the dataset ACLs at the time of creation, or modify them later when adding them in the app.

+ +
{{< include file="/static/includes/apps/BeforeYouBeginAddAppDatasetsProcedure.md" >}}
+ + {{< include file="/static/includes/apps/InstallWizardAppNameAndVersion.md" >}} @@ -205,32 +217,26 @@ If you do not have an existing account, enter the name and password you want to Refer to [*AppName* documentation](URL for environment variables documentation provided in the app provider) for more information on environment variables. -### User and Group Configuration +### User and Group Configuration {{< include file="/static/includes/apps/InstallWizardUserAndGroupConfig.md" >}} -The run-as user information is found on the *AppName* app details screen in the **Run-As Content** widget. - - ### Network Configuration - The default web port for *AppName* is ***30027***. {{< include file="static/includes/apps/InstallWizardHostNetworkSettings.md" >}} {{< include file="/static/includes/apps/InstallWizardDefaultPorts.md" >}} {{< include file="/static/includes/apps/InstallWizardAdvancedDNSSettings.md" >}} + {{< include file="/static/includes/apps/InstallWizardCertificateSettings.md" >}} ### Storage Configuration - TrueNAS provides two options for storage volumes: ixVolumes and host paths. {{< include file="/static/includes/apps/InstallAppsStorageConfig.md" >}} - +You can add extra storage volumes at the time of installation or edit the application after it deploys. Stop the app before editing settings. +{{< include file="/static/includes/apps/InstallAppStorageConfig2.md" >}} -{{< include file="/static/includes/apps/InstallAppsStorageConfig2.md" >}} - -See **Mounting an SMB Share** below for details. - -{{< expand "Creating App Datasets" "v" >}} -To create the *AppName* app datasets, go to **Datasets**, select the dataset you want to use as the parent dataset, then click **Add Dataset** to [add a dataset]({{< relref "DatasetsScale.md" >}}). -In this example, we create the *AppName* datasets under the root parent dataset ***tank***. - -Enter ***AppName*** in **Name**, and select **Apps** as the **Dataset Preset**. -Click **Advanced Options** if you want to make any other setting changes. Click **Save**. -When prompted, select **Return to Pool List** to configure permissions later after adding the other three datasets, or open the ACL editor to edit ACL permissions immediately after adding the dataset. - -Next, select the ***AppName*** dataset, and click **Add Dataset** to add the first child dataset. -Enter ***config*** in **Name** and select **Apps** as the **Dataset Preset**. -Click **Advanced Options** if you want to make any other setting changes. Click **Save**. - -Repeat this to add the other child datasets to the ***AppName*** parent dataset. -When finished you should have the ***AppName*** parent dataset with *three* child datasets under it. Our example paths are: -* */mnt/tank/appname/****config*** -* */mnt/tank/appname/****data*** -* */mnt/tank/appname/****postgresdata*** - -{{< /expand >}} - -#### ACL and ACE Settings +#### Setting Dataset ACL Permissions +You can configure ACL permissions for the required dataset in the **Install Netdata** wizard, or from the **Datasets** screen any time after adding the datasets. {{< include file="/static/includes/apps/InstallWizardStorageACLConfig.md" >}} + +{{< expand "Adding ACL Permissions from the Datasets Screen" "v">}} +First select the dataset row, and scroll down to the **Permissions** widget, and then click **Edit** to open the **Edit ACL** screen. +Change the **@owner** and **@group** values from **root** to the administrative user for your TrueNAS system, and click apply for each. +Next, add an ACL entry for the run-as user. +For Netdata, the run-as users is **0** for **root**. Add a user entry for this user. +Save the ACL before leaving the screen. -#### Mounting an SMB Share +#### Mounting an SMB Share Storage Volume TrueNAS **Additional Storage** options include the ability to mount an SMB share inside the container pod. +{{< include file="/static/includes/apps/InstallAppsStorageConfig2.md" >}} {{< include file="/static/includes/apps/InstallWizardStorageSMBOption.md" >}} -### Resource Configuration +### Resources Configuration {{< include file="/static/includes/apps/InstallWizardResourceConfig.md" >}} + {{< include file="/static/includes/apps/InstallWizardGPUPassthrough.md" >}} ## Troubleshooting Tips - + \ No newline at end of file From 191fb7dbf07679b3af68da807489732eacfb5b33 Mon Sep 17 00:00:00 2001 From: MicJ Date: Fri, 6 Dec 2024 09:31:42 -0500 Subject: [PATCH 09/20] PD-1556 Updates to the Contributin _index.md file --- content/Contributing/Applications/_index.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/content/Contributing/Applications/_index.md b/content/Contributing/Applications/_index.md index 1d39c67b99..21c504b996 100644 --- a/content/Contributing/Applications/_index.md +++ b/content/Contributing/Applications/_index.md @@ -117,12 +117,23 @@ Not all snippet files in this folder apply to tutorial content. Refer to the tables below for a list of snippet files with content about tutorial sections. Open and read snippet files to determine where to use them in your tutorial. +**Community Apps General Snippets** +{{< truetable >}} +| File Name | Snippet Use and Content | +|-----------|-------------------------| +| CommunityApp.md | Introduces Community Apps section tutorials, and contributing content. | +| CommunityPleaseExpand.md | States the tutorial is incomplete or a placeholder needing further development. Use if you are proposing a partial expansion of the content, but further work is needed. | +| CommunityPleaseImprove.md | States the tutorial content is suspected to be out of date or inaccurate. Use if you suspect the Community app documentation is out of date, inaccurate, or needs further improvement. | +{{< /truetable >}} + **Before You Begin Snippets** {{< truetable >}} | File Name | Snippet Use and Content | |-----------|-------------------------| -| BeforeYouBeginStableApps.md | Bullet point for adding the apps pool. | -| BeforeYouBegigAddAppDatasets.md | Bullet point for adding datasets for the app. Does does not include details on adding datasets as these vary by app. +| BeforeYouBeginStableApps.md | Bullet point for adding the apps pool. Includes warning about choosing an encrypted pool for apps. | +| BeforeYouBeginRunAsUser.md | Bullet point describing where to find the run as user information, and includes a screenshot of the app information screen for the app being documented. | +| BeforeYouBegigAddAppDatasets.md | Bullet point for adding datasets for the app. Does does not include details on adding datasets as these vary by app. | +| BeforeYouBeginAddAppDatasetsProcedure.md | Procedure for correctly creating datasets for apps in an expand/collapse area. | | BeforeYouBeginAddAppCertificate.md | Bullet point for adding a certificate if required for the app. Also include the AddingAppCertificate.md snippet with detailed instructions on adding a self-signed certificate. | | AddingAppCertificate.md | Detailed set procedure on adding a self-signed certificate authority (CA) and certificate. | | BeforeYouBeginAddNewUser.md | Single bullet point and procedure for adding a new user as a TrueNAS app administrator. | @@ -163,4 +174,4 @@ Open and read snippet files to determine where to use them in your tutorial. ### Suggesting Edits to Existing Articles Click **Edit Article** at the top of the Documentation Hub article to suggest changes to an existing article. -Refer to the [Content Updates]({{< relref "/Contributing/Documentation/ContentUpdate.md" >}}) article for more details. +Refer to the [Content Updates]({{< relref "/Contributing/Documentation/ContentUpdate.md" >}}) article for more details. \ No newline at end of file From 19a9c40e911de516e5e79710792d2a93c19cf523 Mon Sep 17 00:00:00 2001 From: MicJ <92740932+micjohnson777@users.noreply.github.com> Date: Fri, 6 Dec 2024 14:55:51 -0500 Subject: [PATCH 10/20] Update AppArticleTemplate.md Add missing /expand tag to line 263 --- content/Contributing/Applications/AppArticleTemplate.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index 4c3bd8b03c..8ec67a145a 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -266,6 +266,7 @@ Change the **@owner** and **@group** values from **root** to the administrative Next, add an ACL entry for the run-as user. For Netdata, the run-as users is **0** for **root**. Add a user entry for this user. Save the ACL before leaving the screen. +{{< /expand >}} #### Mounting an SMB Share Storage Volume @@ -285,4 +286,4 @@ TrueNAS **Additional Storage** options include the ability to mount an SMB share ## Troubleshooting Tips - \ No newline at end of file + From 524a5d7454e15f8f590e7a32c8671da85d176b3e Mon Sep 17 00:00:00 2001 From: MicJ <92740932+micjohnson777@users.noreply.github.com> Date: Tue, 10 Dec 2024 16:16:28 -0500 Subject: [PATCH 11/20] Update AppArticleTemplate.md A few changes made to the template. Added internal link to storage configuration settings and added new commented-out text related to the InstallWizardStorageConfig2.md snippet. --- content/Contributing/Applications/AppArticleTemplate.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index 8ec67a145a..51565b1a5a 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -181,7 +181,7 @@ For example, add the **568** user and **0**, and give each **FULL_CONTROL Access Select **Force Flag**. -Repeat the storage steps above each additional storage volume. +Repeat the storage steps above each additional storage volume. See [Storage Configuration Settings](#storage-configuration-settings) below for more information. Accept the defaults in **Resources Configuration**, and select the GPU option if applicable. @@ -253,6 +253,8 @@ If you have a postgres dataset, also include information in the Before You Begin See the instructions in the [Before You Begin](#before-you-begin) section for more on creating both the parent and postgres_data datasets and configuring the ACL permissions for each.--> You can add extra storage volumes at the time of installation or edit the application after it deploys. Stop the app before editing settings. + + {{< include file="/static/includes/apps/InstallAppStorageConfig2.md" >}} #### Setting Dataset ACL Permissions From 8ab6e6ca222d4748eda2870e52ebcdc5dd71e1f7 Mon Sep 17 00:00:00 2001 From: MicJ Date: Thu, 12 Dec 2024 09:54:54 -0500 Subject: [PATCH 12/20] PD-1556 Add new InstallWizardLabelsConfiguration.md Snippet --- .../apps/InstallWizardLabelsConfiguration.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 static/includes/apps/InstallWizardLabelsConfiguration.md diff --git a/static/includes/apps/InstallWizardLabelsConfiguration.md b/static/includes/apps/InstallWizardLabelsConfiguration.md new file mode 100644 index 0000000000..2ff55e4ca2 --- /dev/null +++ b/static/includes/apps/InstallWizardLabelsConfiguration.md @@ -0,0 +1,22 @@ + + +The **Labels Configuration** settings allow administrative users to create and add [labels](https://docs.docker.com/reference/compose-file/services/#labels) to add metadata to containers. +Label-based configuration can define anything and varies based on the environment. +For example, in cloud infrastructure (e.g., AWS, Kubernetes) where labels apply metadata, in infrastructure as code (e.g., Terraform, Ansible) where labels group resources, in software configuration (e.g., feature flags, deployment profiles ) where labels allow setting feature flags, and in CI/CD pipelines (e.g., Jenkins, GitLab CI) where labels can set when to execute specific pipeline jobs and under what conditions. + +Use **Key** to define the object (pods, nodes, services, feature flag, pipeline build, development cycle, metrics, etc.) that categorizes and filters resources. +Use **Value** to enter the category or filter name for the object. + +Select the container (*appname*) from the **Containers** dropdown list to apply the label(s). + +Benefits of label-based configurations: +* Flexibility, where you can apply the same configuration to multiple resources and reduce the need for repetitive configurations. +* Scalability, where you can scale configurations to multiple resources without manually updating each resource. +* Automation, where tools can target labeled resources for changes or deployments. +* Environment separation, where you can create distinct environments and configurations for production, staging, etc. +* Management, where you can search resources based on attributes. + +Tips for Labels: +* Use a consistent naming convention for labels applied across all systems, for example, *dev=prod*, *env=dev*, *role=web*, *role=db*. +* Use in groupings, for example, when applying configuration changes where labels define or group related resources in a database (*role=db*). +* Combine labels for more granular control, for example, using *env=prod* and *tier=frontend* to distinguish frontend from backend services in production environments. \ No newline at end of file From f6bd2032b52a12109617fcfe18a986586fac1bc0 Mon Sep 17 00:00:00 2001 From: MicJ Date: Thu, 12 Dec 2024 10:03:35 -0500 Subject: [PATCH 13/20] PS-1556 Add new Labels Configuration Information to the index and tempalte files This commit updates the _index.md file table of snippets to include the new labels configuration snippet. Updates the template with the section for Labels Configuration and the content for that section. --- content/Contributing/Applications/AppArticleTemplate.md | 8 ++++++++ content/Contributing/Applications/_index.md | 1 + 2 files changed, 9 insertions(+) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index 51565b1a5a..34f1eb266e 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -277,6 +277,14 @@ TrueNAS **Additional Storage** options include the ability to mount an SMB share {{< include file="/static/includes/apps/InstallWizardStorageSMBOption.md" >}} +### Labels Configuration +*Emby* uses metadata to add information to media files, such as where media files are saved, the language used, and parental controls. +*Emby* uses tags to add identification information to media files. + +{{< include file="/static/includes/apps/InstallWizardLabelsConfiguration.md" >}} + + ### Resources Configuration diff --git a/content/Contributing/Applications/_index.md b/content/Contributing/Applications/_index.md index 21c504b996..693efe86a0 100644 --- a/content/Contributing/Applications/_index.md +++ b/content/Contributing/Applications/_index.md @@ -166,6 +166,7 @@ Open and read snippet files to determine where to use them in your tutorial. | Additional Storage SMB Option | InstallWizardStorageSMBOption.md | Details on the Additional Storage volume SMB share option. | | Storage Temporary and tmpfs directories | InstallWizardStorageTemporaryAndTmpfs.md | Details on the **Temporary** and **Tmpfs** directory storage options that are available as primary and/or additional storage volume types, and when to use each. | | Users and Groups | InstallWizardUserAndGroupConfig.md | Details user and group setting options. | +| Labels Configuration | InstallWizardLabelsConfiguration.md | Details on using label-based configuration. | | Resource Configuration | InstallWizardResourceConfig.md | Details CPU and memory setting options for all apps. If the app includes GPU passthrough, use with the InstallWizardGPUPassthrough.md snippet. | | GPU Passthrough | InstallWizardGPUPassthrough.md | Details information on GPU settings if the app includes the GPU passthrough settings. Not present if the app does not detect a GPU device. | {{< /truetable >}} From 49b960792c46b8845b5cba07343bc6d6887c3e7e Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Mon, 16 Dec 2024 14:03:39 -0500 Subject: [PATCH 14/20] Update AppArticleTemplate.md fix missing quotation mark --- content/Contributing/Applications/AppArticleTemplate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index 34f1eb266e..46acdb4296 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -118,7 +118,7 @@ Prepare TrueNAS before installing the app by: {{< include file="/static/includes/apps/BeforeYouBeginStableApps.md" >}} {{< include file="/static/includes/apps/BeforeYouBeginRunAsUser.md" >}} {{< include file="/static/includes/apps/BeforeYouBeginAddAppDatasets.md" >}} From ccd1ae369c99da9e1bc4813c87a72398757723f2 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Mon, 16 Dec 2024 16:55:20 -0500 Subject: [PATCH 15/20] Update AppArticleTemplate.md --- content/Contributing/Applications/AppArticleTemplate.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index 46acdb4296..613a66b2c4 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -117,6 +117,8 @@ Prepare TrueNAS before installing the app by: {{< include file="/static/includes/apps/BeforeYouBeginStableApps.md" >}} {{< include file="/static/includes/apps/BeforeYouBeginRunAsUser.md" >}} + + @@ -128,7 +130,6 @@ NOTE: Include the HTML styling to align the indented paragraph with the bullet l

Create a parent dataset, such as appName, and then the storage datasets (config and data) under it. Select apps as the Dataset Preset for these datasets. You can modify the dataset ACLs at the time of creation, or modify them later when adding them in the app.

-
{{< include file="/static/includes/apps/BeforeYouBeginAddAppDatasetsProcedure.md" >}}
The TrueNAS app is configured with all the required environment variables, but if you want to further customize the container, click **Add** to the right of **Additional Environment Variables** for each to enter the variable(s) and values(s). -*Emby* uses metadata to add information to media files, such as where media files are saved, the language used, and parental controls. -*Emby* uses tags to add identification information to media files. +### Labels Configuration {{< include file="/static/includes/apps/InstallWizardLabelsConfiguration.md" >}} - ### Resources Configuration + {{< include file="/static/includes/apps/InstallWizardCertificateSettings.md" >}} ### Storage Configuration From f491092a444f17e42bf0f835bb8685923f077fc0 Mon Sep 17 00:00:00 2001 From: DjP-iX <133042991+DjP-iX@users.noreply.github.com> Date: Thu, 19 Dec 2024 15:51:42 -0500 Subject: [PATCH 19/20] Update AppArticleTemplate.md --- content/Contributing/Applications/AppArticleTemplate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index e7c5ea1048..8e79585a6b 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -256,7 +256,7 @@ See the instructions in the [Before You Begin](#before-you-begin) section for mo You can add extra storage volumes at the time of installation or edit the application after it deploys. Stop the app before editing settings. -{{< include file="/static/includes/apps/InstallAppStorageConfig2.md" >}} +{{< include file="/static/includes/apps/InstallAppsStorageConfig2.md" >}} #### Setting Dataset ACL Permissions You can configure ACL permissions for the required dataset in the **Install Netdata** wizard, or from the **Datasets** screen any time after adding the datasets. From 03ec0f76b30fe00165013d4ebcf63c4ec3535c73 Mon Sep 17 00:00:00 2001 From: MicJ Date: Fri, 20 Dec 2024 13:51:46 -0500 Subject: [PATCH 20/20] PD-1556 Adjustments and Style Fixes --- .../Applications/AppArticleTemplate.md | 22 ++++++++++--------- content/Contributing/Applications/_index.md | 2 +- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/content/Contributing/Applications/AppArticleTemplate.md b/content/Contributing/Applications/AppArticleTemplate.md index 8e79585a6b..6f15982801 100644 --- a/content/Contributing/Applications/AppArticleTemplate.md +++ b/content/Contributing/Applications/AppArticleTemplate.md @@ -118,7 +118,8 @@ Prepare TrueNAS before installing the app by: {{< include file="/static/includes/apps/BeforeYouBeginStableApps.md" >}} {{< include file="/static/includes/apps/BeforeYouBeginRunAsUser.md" >}} - + @@ -132,10 +133,11 @@ NOTE: Include the HTML styling to align the indented paragraph with the bullet l
{{< include file="/static/includes/apps/BeforeYouBeginAddAppDatasetsProcedure.md" >}}
- {{< include file="/static/includes/apps/BeforeYouBeginAddAppCertificate.md" >}} -

Adding a certificate is optional but if you want to use a certificate for this application, either create a new self-signed CA and certificate or import an existing CA and create the certificate for Nextcloud. A certificate is not required to deploy the application.

--> +

Adding a certificate is optional but if you want to use a certificate for this application, either create a new self-signed CA and certificate or import an existing CA and create the certificate for Nextcloud. A certificate is not required to deploy the application.

{{< include file="/static/includes/apps/BeforeYouBeginAddNewAppUser.md" >}} @@ -168,16 +170,16 @@ Accept the default values in both **User and Group Configuration** and **Network (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](#user-and-group-configuration) and [Network Configuration](#network-configuration) for more details. -Leave **Host Network** unselected.--> +Do not select **Host Network** if it is not selected. If checkmarked, select to clear it.--> Add your **Storage Configuration** settings. Set **Host Path (Path that already exists on the system)** in **Type** for ***Data Storage***. -Select **Enable ACL**, and then enter or browse to and select the **data** dataset to populate the **Host Path** field. +Select **Enable ACL**, and then enter or browse to select the ***data*** dataset to populate the **Host Path** field. -Select **Add** to the right of **ACL Entries** for each user or group entry you want to add. +Click **Add** to the right of **ACL Entries** for each user or group entry you want to add. For example, add the **568** user and **0**, and give each **FULL_CONTROL Access**. Select **Force Flag**. @@ -262,12 +264,12 @@ You can add extra storage volumes at the time of installation or edit the applic You can configure ACL permissions for the required dataset in the **Install Netdata** wizard, or from the **Datasets** screen any time after adding the datasets. {{< include file="/static/includes/apps/InstallWizardStorageACLConfig.md" >}} - + {{< expand "Adding ACL Permissions from the Datasets Screen" "v">}} -First select the dataset row, and scroll down to the **Permissions** widget, and then click **Edit** to open the **Edit ACL** screen. +First, select the dataset row, then scroll down to the **Permissions** widget, and then click **Edit** to open the **Edit ACL** screen. Change the **@owner** and **@group** values from **root** to the administrative user for your TrueNAS system, and click apply for each. Next, add an ACL entry for the run-as user. -For Netdata, the run-as users is **0** for **root**. Add a user entry for this user. +For *Netdata*, the run-as users is **0** for **root**. Add a user entry for this user. Save the ACL before leaving the screen. {{< /expand >}} @@ -293,4 +295,4 @@ TrueNAS **Additional Storage** options include the ability to mount an SMB share ## Troubleshooting Tips - + \ No newline at end of file diff --git a/content/Contributing/Applications/_index.md b/content/Contributing/Applications/_index.md index 693efe86a0..0b7d04160a 100644 --- a/content/Contributing/Applications/_index.md +++ b/content/Contributing/Applications/_index.md @@ -166,7 +166,7 @@ Open and read snippet files to determine where to use them in your tutorial. | Additional Storage SMB Option | InstallWizardStorageSMBOption.md | Details on the Additional Storage volume SMB share option. | | Storage Temporary and tmpfs directories | InstallWizardStorageTemporaryAndTmpfs.md | Details on the **Temporary** and **Tmpfs** directory storage options that are available as primary and/or additional storage volume types, and when to use each. | | Users and Groups | InstallWizardUserAndGroupConfig.md | Details user and group setting options. | -| Labels Configuration | InstallWizardLabelsConfiguration.md | Details on using label-based configuration. | +| Labels Configuration | InstallWizardLabelsConfiguration.md | Details on using Docker label-based configuration. | | Resource Configuration | InstallWizardResourceConfig.md | Details CPU and memory setting options for all apps. If the app includes GPU passthrough, use with the InstallWizardGPUPassthrough.md snippet. | | GPU Passthrough | InstallWizardGPUPassthrough.md | Details information on GPU settings if the app includes the GPU passthrough settings. Not present if the app does not detect a GPU device. | {{< /truetable >}}