rfd/0246-install-docs.md
When users get started with Teleport, they often look for pages of documentation related to downloading and installing a Teleport component that they need to use.
This RFD proposes that we reorganize our documentation to make it easier to find these pages.
Currently, it is difficult for users to find installation documentation because it lives in different places depending on the component, target OS/platform, and other factors. Teleport includes multiple components that are interesting to different users, and each component has many different installation options depending on an individual user's environment.
A company using Teleport may have:
For example, a common user workflow is installing a Teleport agent on an EC2 instance and connecting it to the cluster. Users who do not read the documentation and follow the instructions in the Teleport Web UI have an easy path forward that involves executing a single command.
However, a user who attempts to read the documentation might follow a path that looks like this:
This RFD proposes that we add one new top-level "Install Teleport" section, with subsections that are organized by use case:
These sections would cover all Teleport components. Installation sections will cover setup for Managed Updates and link to more detailed Upgrading docs where appropriate.
Notably, the "Install Teleport" section differs from the marketing-branded categories for our product features because it is cross-cutting, operational, and (in general) does not focus on in-product UX workflows. Users install Teleport, ensure they have a way to upgrade it, ensure they have day-two operations like backups configured, and then they (or different end-users) dive into the product itself via the category sections.
A complete user story for a Teleport installation workflow may need to involve in-product configuration. For example, it is common to configure roles after installing a self-hosted cluster. As we cannot repeat these instructions for every combination of component and target platform, we can rely on cross-linking to ensure that the user is guided to the correct page regardless of their starting point.
This organizational structure will be especially useful when the installation portion of a workflow may vary significantly on different cloud platforms, Linux distributions, etc.
Teleport includes a large number of independently installable components that require dedicated installation instructions for an even larger number of target platforms.
This is an enumeration of all possible installation targets (not a suggested organization, see further below):
Users will generally know which target platform they need to perform the installation on, but they may not know which Teleport component they need to install.
A Teleport user may need to mix and match instructions for their use case. For example, they may need to install a self-hosted cluster on GKE, deploy an agent into EKS, and then configure the agent to allow App access.
To address this complexity, the top-level subsections divide users into categories to ensure any incorrect navigation happens early and is obvious to users. The top-level subsection names will be verbose to avoid incorrect navigation.
The following organization is proposed as an ideal, long-term plan. These sections would be nested under a top-level "Install Teleport" section. (See further below for a short-term plan using existing content.)
However, we do not currently have content to fill most of these sections, and many of our existing pages are reused across platforms.
To account for this, we can start by re-organizing existing content to match the general organizational principle proposed.
For example, the following organization could be an actionable short-term solution until additional content is added:
(Note that this is not a committed action plan and may change as we make progress.)
The Installing and Upgrading sections in Introduction would be removed entirely.
Notably, cluster operations that are not handled by Cloud should be included in the marketing-branded sections (like Zero Trust Access), not in Install Teleport.
For example, a guide to configuring a cluster to support AWS KMS would be included in Install Teleport -> Installing Self-Hosted Teleport Clusters -> KMS, while
a guide for getting started with Teleport roles would be included in the "Zero Trust Access" section.
The only exception to this rule is global, shared configuration that is directly related to platform operations and does not
fit into the marketing-branded sections. For example, some of the cluster_* or autoupdate_* resources may be described in Install Teleport.
These are generally optional for Cloud users to configure.
Installation instructions should not be complete user guides that include in-product configuration. Installation instructions should link to user guides when they are more appropriate, and user guides should link to (or import) installation instructions where needed.
This list is an incomplete collection of various flows we need to fix. See the Action Plan above for additional examples.
teleport is supported on macOS, but provides no guidance for configuring or using it.