Contributing to Apps

← Getting Started

We welcome community user contributions, issue reporting, and suggestions for new features and apps to create the best possible TrueNAS app user experience!

App Updates and Releases

Application maintenance is independent of TrueNAS version release cycles. App version information, features, configuration options, and installation behavior during access might vary from those in documented tutorials.

TrueNAS apps show the Update badge and button on any deployed application instance on the Installed application screen when a new version is available. Users can apply the update(s) individually or collectively and at a convenient time based on needs.

To see currently available apps, go to Apps and click Discover Apps or visit the TrueNAS Apps repository on GitHub.

Contributing to TrueNAS Application Catalogs

Users can submit changes to an existing application catalogs through:

Contributing Applications

The Apps catalog is open for contributions! For instructions on how to locally develop and test new applications, see the contributors guide on GitHub.

Participating in Github Discussions

Questions on the development of applications? Please head over to the discussions page to ask questions and collaborate with other App Developers.

Community Forum Feature Requests

To request an application or general Apps service feature change, go to the TrueNAS Community Forum, 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 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. TrueNAS team members actively monitor this channel and discusses the feasibility of each request both internally and in the forum posts.

If approved and requested to submit a PR to add the new application, submit a PR against the TrueNAS/Community repository. Include the relevant files in the PR, including a ReadMe.txt file with any installation notes for TrueNAS developers.

Contributing to TrueNAS Application Documentation

Community members can now submit content directly to the TrueNAS Apps Market site repository.

For more information about submitting a pull request on GitHub, see the Updating Content at the TrueNAS Contributions Guide.

Proposing Content Changes

To submit new content or request changes to existing application documentation:

Fork the truenas/apps-web repository.
To edit an existing application article, open the related .md file in the content/catalog/ directory of your forked copy. Here, you can make edits and commit them to your PR.
To submit a new tutorial or create application content, add a new .md file to the content/resources/ directory. Follow the front matter format used in existing examples for consistency.
Update the link related to the content/catalog/ path and .md file to the new tutorial if the new tutorial is associated with a catalog application entry,
Embed images as needed by saving them in the static/images/ directory. Follow standard Markdown image referencing procedures in your PR to ensure consistency with other articles.
(Optional) Embed YouTube videos or TrueNAS Community Forum direct links in the Resources section. These become visibly accessible on the Resources section of the app article.
Submit a PR against the main branch of the repository.

From the Resources section of an existing article page, contributors can edit pages directly from the TrueNAS Apps website using the Edit page button in the upper right corner. Some articles related to Enterprise applications might not offer this option.

Browse the content/ and static/ folders in the repository for examples of complete application entries and resource tutorials.

Formatting Front Matter

To correctly format the front matter of a new .md file, use the following example as a guide:

---
title: "APP_NAME Deployment"
description: "Provides installation instructions for the APP_NAME application in TrueNAS."
related_app: "/catalog/APP_NAME"
GeekdocShowEdit: true
geekdocEditPath: "edit/main/content/resources/FILE-NAME.md"
tags:
- apps
---

Including a title, short description, and tag(s) ensures consistency and visibility across all apps content.

Embedding Resources

You can embed outside resources, such as YouTube videos, within the Resources section of an app page. To do this, use shortcode containing the resource ID from the original source.

For example, to embed a YouTube video located at https://www.youtube.com/watch?v=abcd_1234, enter the shortcode {{ youtube abcd_1234 }}. In this scenario, youtube is the shortcode name, and abcd_1234 is the original resource ID from the YouTube video.

Using the App Tutorial Template

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

Foundations

Community App Tutorial Template

Provides an app tutorial template to customize for new community-maintained app tutorials.

Formatting Tips for Content Development

Standard text emphasis:

Apply Bold to UI elements seen on the screen, including field, button, and navigation option names. Use double asterisks preceding and following the name or text string to make it bold. Do not use bold in code strings.
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 (<i></i>) and not the Markdown tags.
Apply HTML file tags (<file></file>) when entering a path to a file or file name, for example <file>iso</file>, which renders as iso.
Apply HTML keyboard tags (<kbd></kbd>) to keys on a keyboard, for example <kbd>Enter</kbd>, which renders as Enter.

When entering commands, command strings, or code blocks:

Apply backticks(``) or HTML <code></code> tags to format command strings or output, for example `string` or <code>string</code>, which render as string.
Apply HTML <code></code> 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. The Technical Documentation team maintains these snippets, 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.

App Tutorial Snippet Files

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.

Community Apps General Snippets

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.

Before You Begin Snippets

File Name	Snippet Use and Content
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.
InstallWizardPostgresStorageAutomaticPermissions.md	Information on configuring postgres and parent dataset permissions, added in the Before You Begin section but can also be added in the Understanding Application Wizard Settings.
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.

Installing the App

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

Understanding App Install Wizard Settings

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