diff --git a/docs/vendor/enterprise-portal-configure.mdx b/docs/vendor/enterprise-portal-configure.mdx index 7438b1d61d..3b891b2c3e 100644 --- a/docs/vendor/enterprise-portal-configure.mdx +++ b/docs/vendor/enterprise-portal-configure.mdx @@ -82,13 +82,11 @@ To configure customer emails: [View a larger version of this image](/images/enterprise-portal-customer-emails-edit.png) -## Customize Documentation +## Add a Link to Documentation -The install instructions available in the Enterprise Portal are automatically generated based on the install types and options enabled in the customer's license. For more information about managing the installation types and options, see [Manage Install Types for a License](/vendor/licenses-install-types). +For each of your supported install types, you can add a link your installation documentation. The link you provide is displayed on the Enterprise Portal **Install** page. -You can also customize the documentation that is displayed in the Enterprise Portal by including a link to your installation instructions or by adding your own pre- and post-installation instructions. - -To customize documentation: +To add a link to your documentation in the Enterprise Portal: 1. In the Vendor Portal, go to **Enterprise Portal > Knowledge Base**. @@ -98,12 +96,587 @@ To customize documentation: 1. In the panel on the left, select the installation type. -1. Customize the documentation for the selected installation type as desired: - 1. In the documentation links section, add a link to your installation documentation. The link is displayed on the Enterprise Portal **Install** page. - 1. In the documentation content section, add pre- and post-installation instructions in markdown format. Click **Preview** to see a preview of your changes. +1. In the documentation links section, add a link to your application install documentation. + +1. Click **Save changes**. + +## Add Pre- and Post-Install Instructions - :::note - By default, these same instructions are shown for all release channels. To add channel-specific instructions, go to the **Channel customizations** section. - ::: +For each of your supported install types, you can add custom pre- and post-install instructions for users. This is useful if there are additional prerequisites or follow-up steps that users need to complete in addition to the primary installation instructions. + +:::note +The same pre- and post- instructions are shown for all your release channels. To add channel-specific instructions, see [Customize Channel-Specific Install Instructions](#customize-channel-install-instructions). +::: + +To customize the pre- and post-install instructions for your application: + +1. In the Vendor Portal, go to **Enterprise Portal > Knowledge Base**. + + ![Enterprise Portal knowledge base page](/images/enterprise-portal-knowledge-base.png) + + [View a larger version of this image](/images/enterprise-portal-knowledge-base.png) + +1. In the panel on the left, select the installation type. + +1. In the documentation content section, add pre- and post-installation instructions in markdown format. Click **Preview** to see a preview of your changes. 1. Click **Save changes**. + +## Customize Channel-Specific Install Instructions (Alpha) {#customize-channel-install-instructions} + +:::note +Custom install instructions are Alpha and subject to change. To access this feature, a feature flag must be enabled for your team. For more information, reach out to your Replicated account representative. +::: + +By default, the installation instructions available in the Enterprise Portal are automatically generated based on the install types and options enabled in the customer's license. These default installation instructions are the same across all release channels. For more information about managing the install types and options, see [Manage Install Types for a License](/vendor/licenses-install-types). + +You can also write custom, channel-specific instructions. This is useful if you need to provide unique installation steps for any of your release channels. For example, you can add custom steps, rename steps or sections to match your documentation, include videos or diagrams, and more. + +These custom installation instructions support MDX. MDX is a format that combines Markdown with JSX, allowing you to use components and template variables in your instructions. MDX templates support the following: + +- **Template variables**: Access dynamic data like application name, release version, registry settings, and customer inputs +- **Built-in UI components**: Use UI components like code blocks, alerts, tabs, and progress indicators +- **Conditional rendering**: Conditionally show or hide content. For example, show or hide certain steps based on the installation options supported by the customer's license + +### Customize Channel-Specific Instructions + +To customize channel-specific installation instructions: + +1. In the Vendor Portal, go to **Enterprise Portal > Knowledge Base**. + +1. Scroll to the **Channel customizations** section. + +1. For the channel where you want to customize instructions, click **Enable**. + + ![Enable button](/images/vendor-portal-custom-instructions-enable.png) + + [View a larger version of this image](/images/vendor-portal-custom-instructions-enable.png) + +1. In the MDX template editor, write your custom installation instructions using Markdown, template variables, and MDX components. + + The editor provides autocomplete for available template variables and components. Start typing `{` for template variables or `<` for MDX components to see suggestions. For more information about the available variables and components, see [Supported MDX Template Variables](#vars) and [Supported MDX Components](#components) below. + + ![MDX template editor](/images/vendor-portal-custom-instructions-editing.png) + + [View a larger version of this image](/images/vendor-portal-custom-instructions-editing.png) + +1. Click **Save changes** to save your custom installation instructions. + +### Revert to Default Instructions + +To disable custom instructions for a channel and revert to the default automatically-generated instructions: + +1. In the **Channel customizations** section, select the channel. + +1. For the target channel, click **Disable**. When channel customizations are disabled, the Enterprise Portal shows the default installation instructions for the channel. + + :::note + Your custom documentation is saved in the **Channel customizations** MDX template editor. You can enable the custom instructions again by clicking **Enable** for the channel. + ::: + +### Supported MDX Template Variables {#vars} + +:::note +For a complete list of available variables, use the autocomplete feature in the editor. +::: + +The following describes some of the supported MDX template variables: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableDescriptionExample
{`{app.name}`}Application name`My Application`
{`{app.slug}`}Application slug (identifier)`my-app`
{`{channel.name}`}Channel name`Stable`
{`{channel.slug}`}Channel slug`stable`
{`{release.versionLabel}`}Release version number`1.2.3`
{`{release.sequence}`}Release sequence number`42`
{`{installOptions.adminConsoleUrl}`}Admin Console URL (user input, dynamic)`https://admin.example.com`
{`{installOptions.proxyUrl}`}HTTP/HTTPS proxy URL (user input, dynamic)`https://proxy.example.com:8080`
{`{installOptions.privateRegistryUrl}`}Private registry hostname (user input, dynamic)`registry.example.com:5000`
{`{branding?.title}`}Enterprise Portal title (optional)`MyApp Enterprise Portal`
{`{branding?.primaryColor}`}Primary brand color (optional)`#4a53b0`
{`{branding?.supportPortalLink}`}Support portal URL (optional)`https://support.example.com`
{`{installation.licenseId}`}Customer license ID`2cHXb1RCttzpR0xvnNWyaZCgDBP`
{`{installation.serviceAccountId}`}Service account identifier`2cHXb1RCttzpR0xvnNWyaZCgDBP`
{`{images.raw}`}Array of image names without registry (Helm only)`["nginx:1.19", "postgres:13"]`
{`{images.full}`}Array of complete image references (Helm only)`["registry.replicated.com/..."]`
+ +### Supported MDX Components {#components} + +The following components are available in MDX templates. For examples of each component, see [Example](#example) below. + +#### Text and Formatting + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionProps
``, ``, ``, `` + Display callout boxes with different styles. + `icon` (boolean, optional): Show or hide the icon in the callout.
`` + General purpose alert with customizable type + +
    +
  • `kind` ("info" | "warning" | "error" | "success", optional)
    • +
  • `icon` (boolean, optional): Show or hide the icon in the callout.
    • +
+
`` +

Display inline code.

+

To use template variables inside CodeBlock, wrap them in template literals using curly braces: `{`...`}`. For example, ```{`${app.slug}`}```.

+

Limitation: Dynamic user input variables (like `installOptions.privateRegistryUrl`, `installOptions.proxyUrl`, `installOptions.adminConsoleUrl`) are not supported in code components. Use placeholders like `` instead.

+ 		None
`` +

Display multi-line code blocks with syntax highlighting.

+

To use template variables inside CodeBlock, wrap them in template literals using curly braces: `{`...`}`. For examples of this, see [Example](#example).

+

Limitation: Dynamic user input variables (like `installOptions.privateRegistryUrl`, `installOptions.proxyUrl`, `installOptions.adminConsoleUrl`) are not supported in code components. Use placeholders like `` instead.

+ 		+
    +
  • `language` (string, optional)
    • +
  • `maxHeight` (number | string, optional)
    • +
  • `showCopyButton` (boolean, optional)
    • +
  • `disabled` (boolean, optional)
    • +
+
`` +

Display shell commands with copy functionality.

+

To use template variables inside CommandBlock, wrap them in template literals using curly braces: `{`...`}`. For examples of this, see [Example](#example).

+

Limitation: Dynamic user input variables (like `installOptions.privateRegistryUrl`, `installOptions.proxyUrl`, `installOptions.adminConsoleUrl`) are not supported in code components. Use placeholders like `` instead.

+ 		+
    +
  • `language` (string, optional)
    • +
  • `maxHeight` (number | string, optional)
    • +
  • `showCopyButton` (boolean, optional)
    • +
  • `disabled` (boolean, optional)
    • +
+
+ +#### Layout + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionProps
``Create tabbed content sections`defaultActiveTab` (number, optional): Index of initially active tab
``Individual tab within a Tabs container`title` (string, required): Tab label text
``Create collapsible content sections`title` (string, required), `defaultOpen` (boolean, optional)
``Show or hide content based on conditions`when` (string, required): JavaScript expression to evaluate
+ + +#### Installation Components + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionProps
``Numbered installation step +
    +
  • `title` (string, required)
    • +
  • `stepNumber` (number, optional)
    • +
  • `completed` (boolean, optional)
    • +
  • `optional` (boolean, optional)
    • +
+
``Display prerequisites section`title` (string, optional): Custom title for the section
``Display troubleshooting section`title` (string, optional): Custom title for the section
+ + +#### Input Components + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionProps
``Collect proxy URL from user +
    +
  • `placeholder` (string, optional)
    • +
  • `disabled` (boolean, optional)
    • +
+
``Collect registry credentials +
    +
  • `placeholder` (string, optional)
    • +
  • `disabled` (boolean, optional)
    • +
+
``Collect Admin Console URL +
    +
  • `placeholder` (string, optional)
    • +
  • `disabled` (boolean, optional)
    • +
+
+ + +#### Display Components + + + + + + + + + + + + + + + + +
NameDescriptionProps
``Link to support resources +
    +
  • `href` (string, optional): Link URL. If not set, uses `branding.supportPortalLink`.
    • +
  • `showIcon` (boolean, optional, default: true)
    • +
  • `target` ("_blank" | "_self", optional, default: "_blank")
    • +
+
+ +### MDX Templates Restrictions + +MDX templates are validated for security before being saved. The following restrictions apply: + +- Only approved MDX components can be used +- JavaScript code execution is not allowed +- External script imports are blocked +- Dangerous HTML elements (script, iframe, embed) are not allowed +- Template size is limited to 1MB + +### Example + +The following is an example of custom installation instructions that use MDX with conditional rendering based on installation type: + +
+ MDX Example + +```mdx +# Install \{app.name\} + + + ## Helm Installation + + + - Kubernetes cluster version 1.24 or later + - Helm 3.8 or later installed + - kubectl configured to access your cluster + + + + + + + Save your registry credentials to a Kubernetes secret: + + + + {`kubectl create secret docker-registry ${app.slug}-registry \\ + --docker-server= \\ + --docker-username= \\ + --docker-password= \\ + --namespace default`} + + + + + + {`helm install ${app.slug} oci:///${app.slug} \\ + --version ${release.versionLabel} \\ + --namespace default`} + + + + + + {`kubectl get pods -n default`} + +

+ + All pods should be in the Running state within 5 minutes. + + + + + ### Pods are not starting + + If your pods are not starting, check the pod logs: + + + {`kubectl logs -n default -l app=${app.slug}`} + +

+ ### Need help? + + Contact our support team: Get Support + + + + + ## Embedded Cluster Installation + + + - Linux server (Ubuntu 20.04+, RHEL 8+, or equivalent) + - Root or sudo access + - Minimum 4 CPU cores and 8GB RAM + + + + + + Download the air gap bundle to your server: + + + {`curl -f "https://replicated.app/embedded/${app.slug}/${channel.channelSlug}/${release.versionLabel}?airgap=true" \\ + -H "Authorization: YOUR_LICENSE" \\ + -o ${app.slug}-${channel.channelSlug}.tgz`} + + + + + + Download the installation assets via proxy: + + + + {`curl -f "https://replicated.app/embedded/${app.slug}/${channel.channelSlug}/${release.versionLabel}" \\ + -H "Authorization: YOUR_LICENSE" \\ + --proxy \\ + -o ${app.slug}-${channel.channelSlug}.tgz`} + + + + + + Download the installation assets: + + + {`curl -f "https://replicated.app/embedded/${app.slug}/${channel.channelSlug}/${release.versionLabel}" \\ + -H "Authorization: YOUR_LICENSE" \\ + -o ${app.slug}-${channel.channelSlug}.tgz`} + + + + + + + {`tar -xvzf ${app.slug}-${channel.channelSlug}.tgz`} + + + + + + + {`sudo ./${app.slug} install --license license.yaml --airgap-bundle ${app.slug}.airgap`} + + + + + + {`sudo ./${app.slug} install --license license.yaml --https-proxy=`} + + + + + + {`sudo ./${app.slug} install --license license.yaml`} + + +

+ + The installer will provision a Kubernetes cluster and deploy \{app.name\}. + + + + + ### Installation fails + + Check the installation logs: + + + {`sudo journalctl -u ${app.slug}`} + +

+ ### Need help? + + Visit our support portal or email support@example.com. + + +``` +
+ +Given the MDX example above, the following show previews of how the Helm online install and Linux (Embedded Cluster) online install instructions would appear in the Enterprise Portal: + +
+ Helm Online Install Preview + +![Helm online install instructions example](/images/enterprise-portal-custom-instructions-helm-online.png) + +[View a larger version of this image](/images/enterprise-portal-custom-instructions-helm-online.png) + +
+ +
+ Linux (Embedded Cluster) Online Install Preview + +![Linux online install instructions example](/images/enterprise-portal-custom-instructions-linux-online.png) + +[View a larger version of this image](/images/enterprise-portal-custom-instructions-linux-online.png) + +
\ No newline at end of file diff --git a/static/images/enterprise-portal-custom-instructions-helm-online.png b/static/images/enterprise-portal-custom-instructions-helm-online.png new file mode 100644 index 0000000000..a5141956a1 Binary files /dev/null and b/static/images/enterprise-portal-custom-instructions-helm-online.png differ diff --git a/static/images/enterprise-portal-custom-instructions-linux-online.png b/static/images/enterprise-portal-custom-instructions-linux-online.png new file mode 100644 index 0000000000..216232b854 Binary files /dev/null and b/static/images/enterprise-portal-custom-instructions-linux-online.png differ diff --git a/static/images/vendor-portal-custom-instructions-editing.png b/static/images/vendor-portal-custom-instructions-editing.png new file mode 100644 index 0000000000..1ae1ecc8a1 Binary files /dev/null and b/static/images/vendor-portal-custom-instructions-editing.png differ diff --git a/static/images/vendor-portal-custom-instructions-enable.png b/static/images/vendor-portal-custom-instructions-enable.png new file mode 100644 index 0000000000..be14800a59 Binary files /dev/null and b/static/images/vendor-portal-custom-instructions-enable.png differ