Initial draft for revising getting started by remotesynth · Pull Request #606 · localstack/localstack-docs

remotesynth · 2026-04-24T18:07:25Z

This PR is still in early draft form.

The concepts behind this draft:

Design paths for the main LocalStack use cases
Simplify the quickstart to get them to success faster
Have both an awslocal and a terraform quickstart
Bring AI and agent use cases up front

The concepts behind this draft: 1. Design paths for the main LocalStack use cases 2. Simplify the quickstart to get them to success faster 3. Have both an awslocal and a terraform quickstart 4. Bring AI and agent use cases up front [DOC-12](https://linear.app/localstack/issue/DOC-12/docs-quickstart-v2)

cloudflare-workers-and-pages · 2026-04-24T18:47:45Z

Deploying localstack-docs with Cloudflare Pages

Latest commit:	`bb1cc26`
Status:	✅ Deploy successful!
Preview URL:	https://8b0c35de.localstack-docs.pages.dev
Branch Preview URL:	https://revise-getting-started.localstack-docs.pages.dev

View logs

quetzalliwrites · 2026-04-27T12:18:18Z

added do not merge label + made it a draft to avoid any accidental merges @remotesynth 😸

Fixed some issues on the quick start and reordered the pages to make a more logical order

This was per the suggestion of Colin

peter-smith-phd

Thanks for sharing this PR. It's really nice to see the focus of Local, CI, and AI, and the working example is the perfect size to get something up and running in 10 minutes.

But, I think there's more trimming to be done. There's still a lot of complexity in these pages that go beyond "Getting Started". It'd suggest you document the happy path for the common case, and just hyperlink to the more advanced pages for more detail. If we can't get the happy path working well, then we need to fix the software to make it work better.

peter-smith-phd · 2026-05-06T22:35:32Z

+- **Validate IaC before applying** — Deploy your Terraform, CDK, or CloudFormation to LocalStack first. Confirm it works the way you expect before applying to a real AWS environment.
+- **Safe experimentation** — Explore new AWS services and architectures freely, with no risk to production systems.
+
+LocalStack for AWS also includes advanced capabilities for teams: [Cloud Pods](/aws/capabilities/state-management/cloud-pods/) for sharing and restoring state, [IAM policy enforcement](/aws/capabilities/security-testing/iam-policy-enforcement/), [Chaos Engineering](/aws/capabilities/chaos-engineering/), and more.


Given that IAM Policy enforcement is just a standard part of AWS's IAM service, this doesn't feel like it's something to brag about. Can we instead mention the ability to disable enforcement, and instead detect policy violations with tools like App Inspector?

peter-smith-phd · 2026-05-06T22:37:23Z

+    {
+      title: 'AI & Agent Workflows',
+      description:
+        'Connect LocalStack to your AI coding assistant via the MCP server, or deploy infrastructure automatically using LocalStack Skills.',


So has the MCP server been officially bless by PM as part of our product offering? (I feel it should be, but I many folks probably see it as a DevRel thing).

peter-smith-phd · 2026-05-06T22:40:24Z

+
+### lstk
+
+`lstk` is a lightweight, Go-based CLI that handles the full startup sequence in one command: browser-based login, image pull, and container launch.


Why is the "Go-based" part relevant to users? I know it was an internal switch from Python -> Go, and that's a big deal within LocalStack, but why would customers care?

peter-smith-phd · 2026-05-06T22:42:37Z


-The quickest way get started with LocalStack is by using the LocalStack CLI.
-It allows you to start LocalStack from your command line.
+There are two CLI options for running LocalStack on your laptop. Start with `lstk` if you want the fastest path to a running instance, or use the LocalStack CLI if you need full feature support.


I'm hoping that by end of June, we should recommend lstk as the only path forward. Of course, if this PR gets merged sooner than that, you need both versions.

peter-smith-phd · 2026-05-06T22:43:07Z

+### LocalStack CLI
+
+The full-featured LocalStack CLI gives you access to all LocalStack capabilities.
 Please make sure that you have a working [Docker installation](https://docs.docker.com/get-docker/) on your machine before moving on.


I'm pretty sure lstk also requires Docker.

peter-smith-phd · 2026-05-06T23:12:26Z

+
+## Overview
+
+LocalStack works great in CI environments, allowing your integration tests to run incredibly fast and with no cloud costs.


When I read this section, I struggled a bit with the complexity. This all great information, but it doesn't feel like a "Getting Started" type of topic. I would suspect that customers will only start using LocalStack in CI once they've already got familiar with LocalStack's "local development" model.

I don't think it hurts to keep the "Key differences from local development" information, but the effort to get LocalStack running in CI is more of an advanced topic for later in the docs. It doesn't feel like 5-10 minutes to get a meaningful experience.

peter-smith-phd · 2026-05-06T23:18:26Z

+
+## Overview
+
+AI-assisted development workflows need a fast and secure environment to develop and test in.


I really love this page! It definitely feels like a quick start type of introduction, although I'm missing the actual example to run.

Perhaps you could provide a sequence of prompts for each of the main steps? For example, "Build a Terraform-based application to do blah blah blah", then "deploy this application to LocalStack", then "test this application with..."

That would be great to take it beyond a list of facts, to get an actual running example.

peter-smith-phd · 2026-05-06T23:22:18Z

+## Choose your path
+
+<SectionCards
+  sections={[


Everyone of these paths skips me over the "Installation" section, was that intentional? I also don't get much information about the "Auth Token" unless I explicitly click on the navigation bar.

I guess it depends on whether you're nudging the user toward getting up and running ("Local Development") or whether you just want to provide them with fact ("CI/CD" and "AI & Agent").

peter-smith-phd · 2026-05-06T23:25:32Z


-The Auth Token is required to activate the LocalStack for AWS core cloud emulator. It identifies and authenticates users outside the LocalStack Web Application.
-It primarily accesses your workspace and advanced services & features.
+The Auth Token activates LocalStack for AWS. It ties the running instance to your workspace and license and is required whenever you use LocalStack for AWS.


On the Installation page, there's no reference to Auth token, which is a basic requirement to get LocalStack started. Could we add a half-page summary of what's required to get your auth token configured on that page, instead of going into a lot of detail on this page?

In general, this "Auth Token" page goes into a lot of complex detail (e.g. CI, Docker Compose) that seems to be beyond "Getting Started". Should it be moved into a later section, and perhaps just link those page from here?

peter-smith-phd · 2026-05-06T23:29:22Z

-  order: 5
+  order: 7
 ---



This FAQ is long, and I'd bet that most of it isn't "Getting Started" material. If the user finds themselves getting stuck during the Getting Started process, then we need to fix the software, rather than trying to document-around the complexity.

These FAQs are all very important, but just out of place in this section.

remotesynth requested review from HarshCasper and quetzalliwrites as code owners April 24, 2026 18:07

Update quickstart.mdx

6ea3ae4

quetzalliwrites added the DO NOT MERGE label Apr 27, 2026

quetzalliwrites marked this pull request as draft April 27, 2026 12:17

quetzalliwrites requested a review from blkgrlcto April 27, 2026 13:33

quetzalliwrites assigned remotesynth Apr 27, 2026

remotesynth added 8 commits April 28, 2026 07:46

Clean up the ordering

71369d6

Fixed some issues on the quick start and reordered the pages to make a more logical order

Clean up CI-CD landing page

c778969

Improvements to the AI page

9ed0787

Minor improvement to the AI page

0b1b0dd

Merge branch 'main' into revise-getting-started

b08fba1

Some reworking of the intro and removal of outdated content

b73231c

Added kubernetes as a secondary path

72d35ca

This was per the suggestion of Colin

Modify to note lstk for CI

bb1cc26

peter-smith-phd reviewed May 6, 2026

View reviewed changes


		### lstk

		`lstk` is a lightweight, Go-based CLI that handles the full startup sequence in one command: browser-based login, image pull, and container launch.


		## Overview

		LocalStack works great in CI environments, allowing your integration tests to run incredibly fast and with no cloud costs.


		## Overview

		AI-assisted development workflows need a fast and secure environment to develop and test in.

Conversation

remotesynth commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cloudflare-workers-and-pages Bot commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying localstack-docs with Cloudflare Pages

Uh oh!

quetzalliwrites commented Apr 27, 2026

Uh oh!

peter-smith-phd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

remotesynth commented Apr 24, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Apr 24, 2026 •

edited

Loading