Skip to content

Conversation

rodgtr1
Copy link
Contributor

@rodgtr1 rodgtr1 commented Aug 14, 2025

Closes #55490

Revamps the Getting Started experience into a concise, four-step guide:

  1. Deploy a Teleport cluster
  2. Connect infrastructure
  3. Set up access controls
  4. Configure audit logging

This guide is designed as a multi-page, flowing overview that links to more in-depth documentation (if needed), rather than a long one-page tutorial.

Replaces:

  • Existing single-page Getting Started guide (Teleport Enterprise Cloud)
  • Linux Demo guide (Teleport Community Edition). This is actually repurposed in this guide.

Links in other pages have been updated to point to these new locations and sidebar has been updated as well.

Copy link

github-actions bot commented Aug 14, 2025

Amplify deployment status

Branch Commit Job ID Status Preview Updated (UTC)
travis.rodgers/getting-started-guide-revamp d1dcdd9 45 ✅SUCCEED travis-rodgers-getting-started-guide-revamp 2025-10-16 23:14:49

@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 182e126 to a9e1c78 Compare August 15, 2025 01:13
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from a9e1c78 to d525d06 Compare August 15, 2025 01:20
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from d525d06 to 70a4a8d Compare August 15, 2025 01:27
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 70a4a8d to 9a90c12 Compare August 15, 2025 15:24
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 9a90c12 to 21f6c2d Compare August 26, 2025 17:15
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 66c69fd to 9d29522 Compare August 26, 2025 18:59
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 9d29522 to a184399 Compare August 26, 2025 19:15
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from a184399 to 65fd8ef Compare August 26, 2025 19:39
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 65fd8ef to bbe38ac Compare August 26, 2025 21:00
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from bbe38ac to 6e69092 Compare August 28, 2025 19:33
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 6e69092 to 1e49e47 Compare September 2, 2025 23:19
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch 2 times, most recently from 1005388 to b4c5a24 Compare September 5, 2025 14:54
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from b4c5a24 to ea47b32 Compare September 5, 2025 16:20
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from f8e97d0 to 07208fc Compare October 1, 2025 14:32
github-merge-queue bot pushed a commit that referenced this pull request Oct 9, 2025
* Clarify self-hosted Enterprise starter guidance

Closes #8547

Make it more explicit in the self-hosted Teleport Enterprise index page
that self-hosted deployents start with outreach to the Teleport team,
and that the HA guide and multi-region blueprint are outlines to help a
team plan a deployment that a customer designs in conversation with the
Teleport team.

Otherwise, the implication is that the guides listed on the self-hosted
Teleport Enterprise index page are sufficient for deploying a
self-hosted cluster. There has been a longstanding request for Oracle
Cloud guidance, and rather than expect these users to be self
sufficient, explain that the recommended approach is to reach out to
Teleport and model a deployment based on our architectural outlines.

Some new text in the self-hosted Enterprise index page is based
on #57931.

* Edit the self-hosted Teleport Enterprise intro

Respond to internal feedback by **pschisa**. The multi-region blueprint
is recommended only for a select group of organizations with specific
needs. For the general introduction, link only to the single-region HA
guide.
@ptgott
Copy link
Contributor

ptgott commented Oct 9, 2025

With the exception of the Linux demo guide, each page of the Get Started flow is pretty short. I think it would make sense to fold all of these pages into a single page.
For the Linux Demo guide, I think we could keep it in its current place (/docs/linux-demo), but link to it just as we do other pages outside the Get Started flow, e.g., the links to Enroll Resources guides.
One advantage of this is that it provides more substantial content to help make this page more "interesting and useful" for Google search results. This also will help distinguish individual pages of the flow from related pages, e.g., the RBAC getting started guide. Short index pages in our docs have often had poor viewership, and I think the fact that they're so light on content is a big reason—most readers arrive from Google rather than other docs pages.
For links to other pages in the Get Started guide, we could consider adding a _blank target so the page opens in a separate tab.

@ptgott Yeah that makes sense. Let me try to tweak it separate from this PR/branch and provide a one page alternative to compare.

@ptgott I had a discussion with Kenny today in 1-1 and I think we're going to go with this 4 page guide. I'm going to go ahead and close out the 1 page version.

👍 Let's plan to review the pageviews for the Getting Started series in a month or so and see if it would benefit from SEO improvements.

github-merge-queue bot pushed a commit that referenced this pull request Oct 9, 2025
* Clarify self-hosted Enterprise starter guidance

Closes #8547

Make it more explicit in the self-hosted Teleport Enterprise index page
that self-hosted deployents start with outreach to the Teleport team,
and that the HA guide and multi-region blueprint are outlines to help a
team plan a deployment that a customer designs in conversation with the
Teleport team.

Otherwise, the implication is that the guides listed on the self-hosted
Teleport Enterprise index page are sufficient for deploying a
self-hosted cluster. There has been a longstanding request for Oracle
Cloud guidance, and rather than expect these users to be self
sufficient, explain that the recommended approach is to reach out to
Teleport and model a deployment based on our architectural outlines.

Some new text in the self-hosted Enterprise index page is based
on #57931.

* Edit the self-hosted Teleport Enterprise intro

Respond to internal feedback by **pschisa**. The multi-region blueprint
is recommended only for a select group of organizations with specific
needs. For the general introduction, link only to the single-region HA
guide.
github-merge-queue bot pushed a commit that referenced this pull request Oct 9, 2025
* Clarify self-hosted Enterprise starter guidance

Closes #8547

Make it more explicit in the self-hosted Teleport Enterprise index page
that self-hosted deployents start with outreach to the Teleport team,
and that the HA guide and multi-region blueprint are outlines to help a
team plan a deployment that a customer designs in conversation with the
Teleport team.

Otherwise, the implication is that the guides listed on the self-hosted
Teleport Enterprise index page are sufficient for deploying a
self-hosted cluster. There has been a longstanding request for Oracle
Cloud guidance, and rather than expect these users to be self
sufficient, explain that the recommended approach is to reach out to
Teleport and model a deployment based on our architectural outlines.

Some new text in the self-hosted Enterprise index page is based
on #57931.

* Edit the self-hosted Teleport Enterprise intro

Respond to internal feedback by **pschisa**. The multi-region blueprint
is recommended only for a select group of organizations with specific
needs. For the general introduction, link only to the single-region HA
guide.
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 07208fc to 6c0f68c Compare October 14, 2025 17:19
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 6c0f68c to e051581 Compare October 14, 2025 19:01
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from e051581 to f1c7bc2 Compare October 14, 2025 22:44
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from f1c7bc2 to 51164c1 Compare October 14, 2025 22:49
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 51164c1 to 33835cf Compare October 14, 2025 22:54
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 33835cf to f992692 Compare October 14, 2025 22:58
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from f992692 to 98b267d Compare October 14, 2025 23:02
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 98b267d to a5648cd Compare October 14, 2025 23:15

There are several editions of Teleport that differ in their feature sets, deployment options, and support.

Before choosing one, ask yourself:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have to block on this, but I still think we can simplify the UX here. Currently, the user needs to:

  • Read a bullet
  • Figure out that they need to read the information boxes
  • Click an information box that corresponds to a bullet

Would it make sense to include the link and description for each edition within the same component so the reader doesn't need to connect so many dots? We could remove the edition boxes and add a short (< 1 sentence) description of each edition to the bullets that precede them, along with a link to each edition page.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could get rid of the bullet points entirely and just have the three edition boxes maybe?


You'll need one of the following:

- An Ubuntu Linux server that you can SSH into (physical server, VM or cloud instance like EC2, or homelab server)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right now, it seems like the Prerequisites section includes requirements for the whole guide, and that the guide is for connecting infrastructure in general. In other words, it seems like the user needs an Ubuntu Linux server and Docker to connect infrastructure in general.

I would make it clearer that there's a demo/getting started workflow that the user can follow as a quick example.

Also, for a new user, there's only guidance for enrolling this Ubuntu server. We should add some more explicit mention of the fact that there are other resources a user can add through the Web UI.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great feedback, I've updated the page based on it.

@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from a5648cd to 0fa3f4f Compare October 15, 2025 20:55
Revamps the Getting Started experience into a concise, four-step guide:

1. Deploy a Teleport cluster
2. Connect infrastructure
3. Set up access controls
4. Configure audit logging

This guide is designed as a multi-page, flowing overview that links to more in-depth documentation (if needed), rather than a long one-page tutorial.

Replaces:
- Existing single-page Getting Started guide (Teleport Enterprise Cloud)
- Linux Demo guide (Teleport Community Edition)

Links in other pages have been updated to point to these new locations and sidebar has been updated as well.
@rodgtr1 rodgtr1 force-pushed the travis.rodgers/getting-started-guide-revamp branch from 0fa3f4f to d1dcdd9 Compare October 16, 2025 23:08
@rodgtr1 rodgtr1 requested a review from tigrato October 16, 2025 23:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation no-changelog Indicates that a PR does not require a changelog entry size/sm

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt a more flexible getting started journey in the docs

5 participants