intro-branch-install-doc.mdx

title	metaDescription	redirects
Get started with the branched install component

import styleGuideSimpleYamlFile from 'images/style-guide_diagram_simple-yaml-file.webp'

import styleGuideComplexYamlFile from 'images/style-guide_diagram_complex-yaml-file.webp'

Our branched install component for the docs site allows our users to select one or more options, which then displays content based on those choices.

Overview of creation process [#overview]

Before you start working with the branch install component, some things to consider:

• Ensure you definitely want to use the branched install. Consider if your problem can be solved with another solution (for example, the tab component).
• Browse the branched install docs we've made and see what's possible. Select one you'd like to clone to use as a template.
• Finalize the logical flow of what your options will be and what content will be displayed. Ideally you want to be near-final in your content plans before creating a branch. For this reason, you might break the work into two or more Jiras.

You can build the branched install component in many ways, and it may take you a good amount of effort to get it working, especially the more complex your structure is. But, that said, here's a high-level view of what a creation process will often look like:

1. Review the branched install docs, especially our example YAML files. Get to know the structure and logic of this component.
2. When you're ready to start, copy the YAML file and associated folders of an install component you want to emulate, and use those as a basis for your project.
3. Change the top-level folder name to match your project, and change the agentName in the YAML file to match. The agentName is what tells the YAML file which folder to pull its content from. (See our example YAML files.)
4. To make sure things are working, do a local build.
5. Start adding your .mdx files and editing the yaml file. Depending on how closely your plans match the existing logic, it may be easier to strip out most of the content from the YAML file, and add in a little bit at a time.
6. As you work, build frequently to test out if things are working. Doing small chunks of work and then checking if it's building will help you avoid wasted time troubleshooting. Use the YAML verify script to check for errors.

If you get stuck, ask for help from someone who's built one of these.

Important decision points [#decision-points]

There are a few different approaches you can take with the branched install. Here are some major decision points:

This decision is about: What does the customer see when they first show up on the doc? Does it make sense to show them some instructions even before they've selected an option? If there's a single path that the majority of customers will take, it can make sense to show them some content that then will adjust and change depending on their option selections. Details on this:

• The "default content" approach relies on using the override and skip components. It displays a file and then says: skip or override this file when x options are chosen. (Install doc that uses this: the Java install.)

• If you don't want to display any content before options are selected, you'd use the isCondition=true approach. That component says simply: "display this file if these options are selected." (Install doc that uses this: the .NET install.)

  <Collapser id="display-all-options-decision" title="Should I display all options? Or nest them?"

This decision is about whether you want to initially display all the option choices, or if you'd rather nest them (for example, choosing one option results in another option selection box).

If your option selection logic is fairly simple, it can make sense to simply expose all the options to customers at once. However, if your option selection logic is rather complex (for example, three or more selections, and some selections affecting later selections), it can make sense to nest them.

For an example of a fully exposed set of option selection boxes, see the [Network security prerequisites doc]. For an example of a nested set of selection boxes, see [the .NET install].

<Collapser id="guided-install-decision" title="Do I need the guided install?"

This decision point is about whether you will need to display information about our guided install path. For some agents, we want to display some content about the guided install path (for example, you can see the guided install content in the Java agent install if you select "app server" and "Jetty").

We have a couple options for adding the guided install content:

• We have a recommendedGuided: true component that you can place on specific options where you want the guided install content to show up. What this essentially does is displays the content of the .mdx file that contains that option selection box. You can see an example of this in the Java install, where the guided install content is located in the appInfo-2 file. This implementation isn't actually specific to guided install content: you could use this logic to display any arbitrary content you might want to use.

• Alternatively, you could just add guided install as a regular .mdx file and display it as you would any other file. The .NET install takes this approach. With this approach it will appear as a numbered step like other files.

  <Collapser id="config-file-decision" title="Do I need a config file?"

Some agents make use of a config file component that lets our users input user-specific values directly from the install doc. For an example of this, see the Java install doc.

Use of this file is not necessary. Use of this will depend on your specific install workflow. (For example, the .NET install doc does not use this.)

Our branched install uses [#uses]

Here are our implementations of the branched install with summaries of the choices made for them. We recommend picking one that matches the approach you want to take and adjust it as needed. Please try to keep this list up to date as we add new uses.

• Vulnerability management: Import dependabot data. See a labeled image of this YAML file. Details:
  • A very simple implementation. A single option selection box, which lets you choose between two files.
  • No default-displayed content.
  • Note that this is so simple, the tab component might have been a better choice.
• MySQL integration install. Details:
  • A simple implementation with only a single option selection box.
  • It takes a default-content-displayed approach.
• Java install. Details:
  • It takes a default-content approach. This is because there's one install path that most customers take.
  • It has only two option selection sections: depending on what's selected in the first option, a second option box is displayed.
  • It uses the recommendedGuided component to display the guided install (contained in the appInfo-2 file).
  • It uses the config file component.
• .NET install. See a labeled image of this YAML file. Details:
  • This doesn't display any default content. It relies entirely on the isConditionalStep: true approach. This is because there's quite a few paths and no one path the majority of customers take (although theoretically we could have chosen one).
  • This has only two option selection sections: depending on what's selected in the first option, a second option box is displayed.
  • It uses the recommendedGuided component (contained in the appInfo-2 file).
  • It does not use the config file component: this is because most customers edit the configuration via environment variables or other options and not through direct use of the file.
• Python install. Details:
  • It does not display default content. It relies entirely on the isConditionalStep: true approach. This is because there is no one major path.
  • This has quite a few option selection boxes: up to four, depending on what gets selected.
  • It does not use the config file component.
  • It makes use of comments, which helps understanding of the code and improved maintenance.
• network monitoring endpoints. Details:
  • A pretty simple implementation. Three option selection boxes that control which of several tables are shown. A default-displayed file with replace overrides that determine which table to show.

YAML file examples [#yaml-examples]

The YAML files contain all the logic about how the branched install will work. We have two examples below.

A simple YAML file example [#simple-yaml-example]

This is our simplest YAML file, the one for vulnerability management, with some explanatory labels.

A complex YAML file example [#complex-yaml-example]

Below is a section of a more complex YAML file, the one for .NET install, with some explanatory labels. Things to note about this:

• Note the more complex and/or logic that's possible by using multiple options under a single isConditionalStep clause (AND logic), or using multiple isConditionalStep clauses under a single overrides section (OR logic).
• This puts the guided install content in an .mdx file, instead of using the recommendedGuided component.