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 -Go to **Apps**, and click on **Discover Apps**. -Either scroll down to the ***AppNName*** widget or begin typing the name into the search field to locate the widget. +{{< 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/MultipleAppInstancesAndNaming.md" >}} + +{{< include file="/static/includes/apps/LocateAndOpenInstallWizard.md" >}} + + +{{< include file="/static/includes/apps/InstallWizardAppNameAndVersion.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). + + +Add your **Storage Configuration** settings. + +Set **Type** to **Host Path (Path that already exists on the system)** for ***Data Storage***. +Select **Enable ACL**, and then enter or browse to select the ***data*** dataset to populate the **Host Path** field. + + +Click **Add** to the right of **ACL Entries** for each user or group entry you want to add. +Set **ID Type** to **Entry is for a USER**, enter the ***0*** in **ID**, and give it full control permissions. +For example, add the ***0*** user, and give each **FULL_CONTROL Access**. + + +## Understanding App Installation Wizard Settings -{{\< trueimage src="/images/SCALE/Apps/LocateImageNameWidget.png" alt="Locate *AppName* Widget" id="Locate *AppName* Widget" >}} +The following section provides more detailed explanations of the settings in each section of the **Install *Appname*** installation wizard. + -Click on the widget to open the ***AppNName*** information screen. +### Application Name Settings -{{\< trueimage src="/images/SCALE/Apps/AppNameDetailsScreen.png" alt="*AppName* Information Screen" id="*AppName* Information Screen" >}} +{{< include file="/static/includes/apps/InstallWizardAppNameAndVersion.md" >}} -Click **Install** to open the **Install *AppNName*** configuration wizard. +### 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*. -{{\< trueimage src="/images/SCALE/Apps/InstallAppNameScreen.png" alt="Install *AppName* Screen" id="Install *AppName* Screen" >}} +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. -Scroll down to each section or click the navigation menu item on the right of the screen to jump to that section. +#### Adding Environment Variables -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-*. +{{< 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. -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. + +### User and Group Configuration + -1. Enter the ***AppName* Configuration** settings: +{{< include file="/static/includes/apps/InstallWizardUserAndGroupConfig.md" >}} - a. Enter each required configuration setting in this section. +### 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" >}} - b. Click **Add** to show **Additional Environmental Variables** fields. These are optional settings. Describe any environment variables to enter. +### 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. -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. + +{{< include file="/static/includes/apps/InstallAppsStorageConfig2.md" >}} - {{\< trueimage src="/images/SCALE/Apps/InstallAppNameStorage.png" alt="Add Datasets" id="Add Datasets" >}} +#### 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. - 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. +{{< include file="/static/includes/apps/InstallWizardStorageACLConfig.md" >}} + +{{< expand "Adding ACL Permissions from the Datasets Screen" "v">}} +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. +Save the ACL before leaving the screen. +{{< /expand >}} - 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. +#### Mounting an SMB Share Storage Volume - If you created and want to add more datasets for additional storage, click **Add** to the right of **Additional Storage Volumes** to show another set of storage options. - The additional storage options include the **ixVolume** and **Host Path** options, and the option to create an **SMB share** volume. +TrueNAS **Additional Storage** options include the ability to mount an SMB share inside the container pod. +{{< include file="/static/includes/apps/InstallAppsStorageConfig2.md" >}} - Setting up an SMB share option to set up data sharing using SMB. +{{< include file="/static/includes/apps/InstallWizardStorageSMBOption.md" >}} -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. +### Labels Configuration - 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. +{{< include file="/static/includes/apps/InstallWizardLabelsConfiguration.md" >}} - Accept the default value of 4096 MB allocated memory or enter a new limit in megabytes. - Enter a plain integer. For example, 8192. +### Resources Configuration + -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**. +{{< include file="/static/includes/apps/InstallWizardResourceConfig.md" >}} + +{{< include file="/static/includes/apps/InstallWizardGPUPassthrough.md" >}} -### Using the Web Portal -Click **Web Portal** on the **Application Info** widget to open the application web interface. +## Troubleshooting Tips + -The time required to install the app varies depending on your hardware and network configuration. -``` -``` + diff --git a/content/Contributing/Applications/_index.md b/content/Contributing/Applications/_index.md index 6a21bb627b..0b7d04160a 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,130 @@ 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\\ ) when entering a path to a file or file name, for example \iso\ , which renders as \\) 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, for example \`string\` or \string\, which render as string.
+
+* 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 {{\}} , 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