v2 Getting Started (AWS)

[remotesynth]

This PR is still in early draft form.

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

[cloudflare-workers-and-pages]

Deploying localstack-docs with    Cloudflare Pages

Latest commit:	a9e233a
Status:	✅  Deploy successful!
Preview URL:	https://b688f1c6.localstack-docs.pages.dev
Branch Preview URL:	https://revise-getting-started.localstack-docs.pages.dev

View logs

[quetzalliwrites]

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

[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.

[quetzalliwrites]

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]

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.

[quetzalliwrites]

Adding the do-not-merge label because while we approve this PR, it has a dependency on the new, separate Quickstart docs ticket that's currently a WIP.

[remotesynth]

Updated from main and resolved merge conflicts:

Files resolved

File	Resolution
astro.config.mjs	Kept main's consolidated Developer Tools sidebar; removed duplicate Tooling/Integrations sections
public/_redirects	Used main's new paths, kept branch redirects for quickstart → local-development
custom-tls-certificates.mdx	Updated links to new installation/customization paths
auth-token.mdx	Kept branch's streamlined rewrite; dropped duplicate main content
installation.mdx	Kept lstk-first install flow; updated doc links to new paths; kept CLI troubleshooting
localstack-cli.md	Kept full deprecated CLI reference at developer-tools/running-localstack/; merged lstk note
index.md	Deleted — branch uses index.mdx with SectionCards
quickstart.mdx	Deleted — replaced by local-development.mdx (redirects preserved)
tooling/localstack-cli.mdx	Deleted — canonical page is under developer-tools (redirect exists)

Additional fixes

• Updated stale links in index.mdx (Cloud Pods, IAM, Chaos, Kubernetes)
• Updated lstk doc links from /aws/tooling/lstk/ to /aws/developer-tools/running-localstack/lstk/