[v17] Improve readability in Linux installation guide#64582
[v17] Improve readability in Linux installation guide#64582ptgott wants to merge 1 commit intobranch/v17from
Conversation
Backports #64524 * Improve readability in Linux installation guide Edit the Linux installation guide to improve the clarify of the structure by: 1. Ensuring more general information arrives before more specific information, giving readers the right context when they need it. 2. Ensuring there is a clear hierarchy of headings. Installing the Auth Service and Proxy Service ============================================= This change modifies the H2-level section on installing the Auth Service and Proxy Service to: - Explain the one-line installation script before we ask users to execute it. - Only include tabs for self-hosted editions, since this section only applies to these. Only include information that varies between editions in tabs. - Use "control plane component" instead of "cluster" for precision. - Ensure all H3s use the same grammatical structure. Installing Teleport Agents ========================== In the H2-level section on installing Teleport agents, this change: - Explains the one-line installation script and include a warning at the top of the section to provide context for users. - Move general statement re: the Terraform guide to a place where it makes more sense, in the intro section. - Ensure all H3s in "Installing Teleport as an agent" have the same grammatical structure Other install methods ===================== In the "Other install methods" section, this change: - Provides a more complete summary of the contents in the section, e.g., mentioning the Web UI. - Restores the missing "Package repositories" heading and steps. The current Linux installation guide launches straight from the "Other install methods" heading to an instruction to source `/etc/os-release`, without providing any context as to why. - Fix the "Downloading" H3. Make this an H3, since it belongs in "Other install methods". Add more context about Teleport archives and package downloads. - Remove a potentially misleading `Checkpoint`. There is a `Checkpoint` that asks the reader to confirm that a download matches their system architecture before they are asked to actually perform the download. General changes =============== - Remove headings that are indented below list items. These either render incorrectly, without acting visually as headings, or incorrectly break up the flow of numbered lists. - Fix indentation in Admonitions, Checkpoints, and other block-level components in order to preserve numbered lists. * Simplify snippet for running one-line install script --------- Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com>
ptgott
added
no-changelog
|
Note that there were merge conflicts, and I turned a version warning in |
|
Amplify deployment status
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: acecc14050
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| see [Deploy Agents with | ||
| Terraform](../zero-trust-access/infrastructure-as-code/terraform-provider/terraform-getting-started.mdx). |
There was a problem hiding this comment.
The new "Deploy Agents with Terraform" link points to ../zero-trust-access/infrastructure-as-code/terraform-provider/terraform-getting-started.mdx, but that target does not exist (repo-wide check: rg --files docs/pages | rg 'terraform-getting-started\\.mdx$' returns no matches). This introduces a broken docs path, so users following this installation flow cannot reach the referenced Terraform setup guide.
Useful? React with 👍 / 👎.
| 1. Assign version and architecture variables: | ||
|
|
||
| ### Download and install | ||
| ```code | ||
| $ TELEPORT_VERSION=(=teleport.version=) |
There was a problem hiding this comment.
This duplicated step reassigns SYSTEM_ARCH="" right before the download commands; if readers set SYSTEM_ARCH from the architecture table and then follow this step, the variable is cleared and the subsequent package URLs/filenames are malformed (for example ...linux--bin.tar.gz), causing download/install failures.
Useful? React with 👍 / 👎.
1 participant
Backports #64524
Edit the Linux installation guide to improve the clarify of the structure by:
Installing the Auth Service and Proxy Service
This change modifies the H2-level section on installing the Auth Service and Proxy Service to:
Installing Teleport Agents
In the H2-level section on installing Teleport agents, this change:
Other install methods
In the "Other install methods" section, this change:
/etc/os-release, without providing any context as to why.Checkpoint. There is aCheckpointthat asks the reader to confirm that a download matches their system architecture before they are asked to actually perform the download.General changes