v2 Getting Started (AWS) 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:	`df7a4ec`
Status:	✅ Deploy successful!
Preview URL:	https://f6265903.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.

blkgrlcto · 2026-05-18T19:37:20Z

+  title="LocalStack on Kubernetes (Enterprise)"
+  href="/aws/enterprise/kubernetes/"
+  client:load
+>


The Kubernetes card falling into a full-width row below the 2-column grid looks a bit accidental. Since it's Enterprise-only anyway, might be worth giving it a distinct visual treatment (badge, different border,etc) so it looks intentional.

blkgrlcto · 2026-05-18T19:38:33Z

+    {
+      title: 'Local Development',
+      description:
+        'Set up LocalStack on your laptop and get a serverless app running in under 10 minutes. Deploy Lambda functions, DynamoDB tables, and more — no AWS account needed.',


Almost every new user should start with Local Development, but the page doesn't tell them that. Worth adding something like "New to LocalStack? Start here →" on that card so first-timers aren't left guessing.

quetzalliwrites · 2026-05-26T19:40:40Z

PR Audit Summary

Status: Needs Significant Rework

This PR introduces several critical technical inaccuracies, broken code snippets, and information architectural redundancies. To maintain our technical integrity and avoid introducing "docs debt," the following must be addressed before merging.

Technical & Architectural Requirements

1) Technical Accuracy (High Priority)

Incorrect Resource Labeling: Describing LocalStack as "real Lambda" or "real DynamoDB" is technically incorrect. We are an emulation layer. We must accurately state these are "LocalStack-hosted" or "emulated" resources to ensure technical accuracy.
Incorrect Tool Categorization: Docker, Docker Compose, and Helm are CLI/Orchestration tools, not GUIs. They must be removed from the /installation GUI section.
Incorrect CI Providers: The CI/CD tabs include Docker/Compose options which are not CI providers. These must be scoped strictly to CI-specific tools (e.g., GitHub Actions, Jenkins).

2) Code Integrity (Blockers):

All code blocks must be validated and "copy-paste ready" before deployment.

Python Script Fails Upon Execution: The indentation in each line of this Python script is incorrect, thus #step-2 is currently invalid and fails upon execution.
CLI Syntax: The cleanup command in #step-5 incorrectly includes bash within the executable block.

3) Documentation Information Architecture (DRY Principles):

Single Source of Truth (SSOT): The /ai-workflows/ doc currently duplicates content from the MCP documentation. To prevent maintenance overhead, we are removing the duplicate text and replacing it with a note block directing users to the primary MCP doc as the source of truth.
Structure: The "Summary" section in /ai-workflows/ lacks a narrative conclusion and contains a use-case table. This table is being moved to the Introduction for better high-level visibility.

4) Editorial Standards:

Voice & Tone: The current draft uses informal, "blog-style" phrasing (e.g., "That's the win"). We are reverting this to a proffesional, technical documentation voice to maintain authority.
Punctuation: Consistent with our style guide, we are replacing the over use of em-dashes with colons or period breaks to remove AI-generated markers + improve readability.

Redundancy: The /auth-token/ introduction currently repeats the same information from the body content. This must be tightened to a high-signal summary.

Why this is necessary:

We are holding this PR to ensure the "Getting Started" experience (the most high-traffic area of our site) is technically accurate and the information architecture is consistent. Merging in the current state would introduce immediate technical debt and user friction.

quetzalliwrites · 2026-05-28T20:01:31Z

Information Architecture Realignment: Removing Quickstart Anti-Pattern

As part of the v2 Getting Started experience, I am realigning our information architecture (and sidebar hierarchy) to resolve a long-standing architectural anti-pattern: housing a specific Quickstart tutorial within the general "Getting Started" folder.

Rationale for the Restructure:

Eliminating Cognitive Load: Titling a page "Local Development" while the internal content refers to it as a "Quickstart" creates a significant disconnect for the user. Users expect "Local Development" to cover core operational concepts (persistence, networking, dev loops); finding a specific Lambda/DynamoDB tutorial instead is a misleading user experience.
Getting Started as a Journey: Industry standard dictates that "Getting Started" is a high-level journey. Covering the Overview, Installation, and initial Configuration. It is the foundation, not the specific implementation.
Decoupling Content Types: A Quickstart is a specific functional recipe, whereas Getting Started is system onboarding. To scale effectively, we must decouple these. This realignment is the first step toward our Quickstart Library (currently tracked in this Linear DOCS Project), mirroring the successful developer experiences of enterprise leaders like Stripe and HashiCorp.

Action Taken: I am stripping the "Quickstart" branding from the "Local Development" page and reframing it as a declarative guide for deploying your first local serverless API. This ensures the folder remains a cohesive onboarding path, while the upcoming Quickstart Library will serve as the dedicated home for specialized, multi-language recipes.

The reference to the k8 tutorial has been moved into a standard Note component. This file is now dead code.

Removed redundant "Next Steps" clutter and relocated Docker, Compose, and Helm to a dedicated orchestration section. Standardized tone and corrected tool categorizations.

Consolidated use cases, removed duplicated MCP configuration, and deleted non-functional validation content. Standardized the tone and improved technical context throughout the guide.

Eliminated redundant introduction slop and consolidated configuration methods by execution type. Simplified token comparisons, optimized verification snippets, and unified security warnings for better technical clarity.

HarshCasper

First Round of Review

HarshCasper · 2026-05-26T12:59:02Z

-Start LocalStack with `SMTP_HOST=host.docker.internal:1025`, pointing to the mock SMTP server.
+<Tabs>
+  <TabItem label="lstk">```bash lstk stop ```</TabItem>
+  <TabItem label="LocalStack CLI">```bash localstack stop ```</TabItem>


I think putting it in a new line should fix the issue.

HarshCasper · 2026-05-29T12:25:55Z

+       ```bash
+       mkdir -p /tmp/localstack-demo
+       cat > /tmp/localstack-demo/handler.py << 'EOF'
+       import json, boto3, os, uuid
+
+       def handler(event, context):
+           table = boto3.resource('dynamodb').Table(os.environ['TABLE_NAME'])
+           method = event.get('requestContext', {}).get('http', {}).get('method', 'GET')
+           if method == 'POST':
+               item = {'id': str(uuid.uuid4()), **json.loads(event.get('body', '{}'))}
+               table.put_item(Item=item)
+               return {'statusCode': 200, 'body': json.dumps(item)}
+           result = table.scan()
+           return {'statusCode': 200, 'body': json.dumps(result['Items'])}
+       EOF
+       cd /tmp/localstack-demo && zip handler.zip handler.py
+       ```


The Python handler heredoc will fail. Because it's << 'EOF' (quoted, not <<-) and the whole block is nested inside <Steps> → ordered list → <TabItem> → <Tabs>, the leading indentation is captured into handler.py. The first line import ... ends up indented, which Python rejects and will always lead to an error when a user copy pastes the command into the terminal.

HarshCasper · 2026-05-29T12:27:03Z

-
-### Helm
+```bash
+helm repo add localstack-repo [https://helm.localstack.cloud](https://helm.localstack.cloud)


There is no way this command runs 😅 Markdown link syntax isn't processed inside a fenced code block, so this command is literally uncopyable.

HarshCasper · 2026-05-29T12:35:54Z

+{/* prettier-ignore-start */}
+
+<Tabs>
+  <TabItem label="lstk">```bash lstk stop ```</TabItem>


This is still wrong. A single-line bash lstk stop makes bash lstk stop the info-string, not a code block with lstk stop as content.

HarshCasper · 2026-05-29T12:39:40Z

+
+          - name: Run tests
+            run: |
+            # Your test commands here, e.g.:


This might cause the CI to basically fail. The # comment is indented to the same level as the run: key, while the commands below it are indented further.

HarshCasper · 2026-05-29T13:01:06Z


-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.
+## Token Types


Not exactly a comment per se on this, but just noticing that most of these new docs are using title case when most of the docs we have now uses sentence case.

HarshCasper · 2026-05-29T13:01:30Z

@@ -0,0 +1,153 @@
+---
+title: CI/CD Integration
+description: implementation guides for LocalStack in automated pipelines, including GitHub Actions, Docker Compose, and state management.


Let's not start with lowercase over here:

Suggested change

description: implementation guides for LocalStack in automated pipelines, including GitHub Actions, Docker Compose, and state management.

description: Implementation guides for LocalStack in automated pipelines, including GitHub Actions, Docker Compose, and state management.

HarshCasper · 2026-05-29T13:02:13Z

+
+```bash
+rm -rf /tmp/localstack-demo
+


Empty lines here. Can we double check if there are no empty lines anywhere else in the command block since they serve no purpose?

HarshCasper · 2026-05-29T13:03:01Z


 To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal:

 <Code code={`localstack --version\n${LOCALSTACK_VERSION}`} lang="bash" />


This renders the literal string ${LOCALSTACK_VERSION} rather than a version so it needs to be fixed before merge.

HarshCasper · 2026-05-29T13:04:41Z

+        image: localstack/localstack-pro
+        ports:
+          - "127.0.0.1:4566:4566"
+          - "127.0.0.1:4510-4559:4510-4559"


Why have we removed the :443 HTTPS gateway port reference? This is fine for a simple example, but this is going to break many customer samples that depend on port 443 being exposed. FWIW, even lstk itself binds :443 by default 😄

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

blkgrlcto reviewed May 18, 2026

View reviewed changes

quetzalliwrites changed the title ~~Initial draft for revising getting started~~ v2 Getting Started (AWS) May 28, 2026

quetzalliwrites added 7 commits May 28, 2026 22:21

Update and rename quickstart.mdx to local-development.mdx

6ef84e4

Draft 2: rewrite index.mdx

b7ebb19

Delete dead code: src/components/SecondaryPathCard.tsx

fb4ec71

The reference to the k8 tutorial has been moved into a standard Note component. This file is now dead code.

Draft 2: installation.mdx

deede21

Removed redundant "Next Steps" clutter and relocated Docker, Compose, and Helm to a dedicated orchestration section. Standardized tone and corrected tool categorizations.

Draft 2: local-development.mdx

525c3fb

Draft 2: Rewrite ci-cd.mdx

9ebdb73

Draft 2: rewrite ai-workflows.mdx

4ca4a39

Consolidated use cases, removed duplicated MCP configuration, and deleted non-functional validation content. Standardized the tone and improved technical context throughout the guide.

quetzalliwrites and others added 6 commits May 29, 2026 00:43

Draft 2: rewrite auth-token.mdx

5bfe4a9

Eliminated redundant introduction slop and consolidated configuration methods by execution type. Simplified token comparisons, optimized verification snippets, and unified security warnings for better technical clarity.

Add Troubleshooting section to auth-token.mdx

e38c155

remove dead code from global.css

3a9ce05

add install options + fix missing closing </LinkButton> tags

51aa017

update anchor links

f17c2b9

update more anchor links

df7a4ec

HarshCasper requested changes May 29, 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.

	description: implementation guides for LocalStack in automated pipelines, including GitHub Actions, Docker Compose, and state management.
	description: Implementation guides for LocalStack in automated pipelines, including GitHub Actions, Docker Compose, and state management.


		To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal:

		<Code code={`localstack --version\n${LOCALSTACK_VERSION}`} lang="bash" />

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quetzalliwrites commented May 26, 2026

PR Audit Summary

Status: Needs Significant Rework

Technical & Architectural Requirements

1) Technical Accuracy (High Priority)

2) Code Integrity (Blockers):

3) Documentation Information Architecture (DRY Principles):

4) Editorial Standards:

Why this is necessary:

Uh oh!

quetzalliwrites commented May 28, 2026

Information Architecture Realignment: Removing Quickstart Anti-Pattern

Rationale for the Restructure:

Uh oh!

HarshCasper 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

remotesynth commented Apr 24, 2026 •

edited

Loading

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

edited

Loading