local-web-services.github.io/getting-started.html at main · local-web-services/local-web-services.github.io · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
<!DOCTYPE html>
<html lang="en">
<head>
  <!-- Google tag (gtag.js) -->
  <script async src="https://www.googletagmanager.com/gtag/js?id=G-5C3LL34WWW"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());

    gtag('config', 'G-5C3LL34WWW');
  </script>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Getting Started - Local Web Services</title>
  <meta name="description" content="Install Local Web Services and get running with AWS CDK or HCL in under five minutes.">
  <link rel="stylesheet" href="style.css">
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css">
</head>
<body>

  <nav class="nav">
    <div class="container nav-inner">
      <a href="index.html" class="nav-logo">Local Web Services</a>
      <ul class="nav-links">
        <li><a href="getting-started.html" class="nav-active">Get Started</a></li>
        <li><a href="sdks.html">SDKs</a></li>
        <li><a href="services.html">Cloud Emulation</a></li>
        <li><a href="faking.html">Faking Services</a></li>
        <li><a href="chaos.html">Chaos Engineering</a></li>
        <li><a href="cli.html">CLI</a></li>
        <li><a href="https://github.com/local-web-services/local-web-services" class="nav-github">GitHub</a></li>
      </ul>
    </div>
  </nav>

  <header class="page-header">
    <div class="container">
      <h1>Getting Started</h1>
      <p class="section-lead">Get Local Web Services running with a sample project in under five minutes. Choose your IaC tool below.</p>
    </div>
  </header>

  <section class="section">
    <div class="container">
      <h2>Prerequisites</h2>
      <p class="section-lead">These are required for both CDK and HCL workflows.</p>

      <div class="getting-started-steps">
        <div class="gs-step">
          <ul>
            <li><a href="https://docs.astral.sh/uv/getting-started/installation/">uv</a> &mdash; Python package runner</li>
            <li><a href="https://docs.docker.com/get-docker/">Docker</a> &mdash; required for Lambda runtime emulation</li>
            <li>Node.js 18+ &mdash; required for CDK projects and Node.js Lambda handlers</li>
          </ul>
        </div>
      </div>
    </div>
  </section>

  <section class="section section-alt">
    <div class="container">
      <h2>CDK Quick Start</h2>
      <p class="section-lead">Clone a sample CDK project and run it locally in five steps.</p>

      <div class="getting-started-steps">
        <div class="gs-step">
          <h3>Additional Prerequisite</h3>
          <ul>
            <li>AWS CDK CLI (<code>npm install -g aws-cdk</code>)</li>
          </ul>
        </div>

        <div class="gs-step">
          <h3>1. Clone the sample project</h3>
          <div class="code-block"><code>git clone https://github.com/local-web-services/local-web-services.git
cd local-web-services/sample-project/cdk
npm install</code></div>
        </div>

        <div class="gs-step">
          <h3>2. Synthesize the CDK app</h3>
          <div class="code-block"><code>cdk synth</code></div>
        </div>

        <div class="gs-step">
          <h3>3. Pull Lambda runtime images (one-time)</h3>
          <div class="code-block"><code>uvx --from local-web-services ldk setup lambda</code></div>
          <p>This pulls the official AWS Lambda base images from ECR Public, which include the AWS SDK pre-installed. You only need to do this once.</p>
        </div>

        <div class="gs-step">
          <h3>4. Start the local environment</h3>
          <div class="code-block"><code>uvx --from local-web-services ldk dev</code></div>
          <p>The <code>ldk dev</code> command reads the cloud assembly and starts local providers for every resource in the stack &mdash; DynamoDB tables, SQS queues, S3 buckets, Lambda functions, API Gateway, SSM parameters, and Secrets Manager secrets &mdash; all wired together.</p>
          <p>Once started, open <strong>http://localhost:3000/_ldk/gui</strong> to access the web dashboard with real-time logs, resource explorer, and system status.</p>
        </div>

        <div class="gs-step">
          <h3>5. Make requests</h3>
          <div class="code-block"><code># Create an order via API Gateway
curl -X POST http://localhost:3000/orders \
  -H "Content-Type: application/json" \
  -d '{"customerName": "Jane", "items": ["Widget"], "total": 29.99}'

# Get the order
curl http://localhost:3000/orders/{orderId}

# Inspect data with lws
uvx --from local-web-services lws dynamodb scan --table-name OrdersTable
uvx --from local-web-services lws sqs receive-message --queue-name OrderQueue
uvx --from local-web-services lws s3api list-objects-v2 --bucket order-documents</code></div>
          <p>The sample project is an order processing system with API Gateway, Lambda, DynamoDB, SQS, SNS, S3, and Step Functions &mdash; all running on your machine. Use <code>lws</code> commands to inspect the data your application creates.</p>
        </div>
      </div>
    </div>
  </section>

  <section class="section">
    <div class="container">
      <h2>HCL Quick Start</h2>
      <p class="section-lead">Clone a sample HCL project and run it locally in six steps.</p>

      <div class="getting-started-steps">
        <div class="gs-step">
          <h3>Additional Prerequisite</h3>
          <ul>
            <li><a href="https://opentofu.org/">OpenTofu</a> or <a href="https://www.terraform.io/">Terraform</a> >= 1.0</li>
          </ul>
        </div>

        <div class="gs-step">
          <h3>1. Clone the HCL sample project</h3>
          <div class="code-block"><code>git clone https://github.com/local-web-services/local-web-services.git
cd local-web-services/sample-project/hcl
cd lambda/create-order && npm install && cd ../..
cd lambda/get-order && npm install && cd ../..
cd lambda/process-order && npm install && cd ../..
cd lambda/generate-receipt && npm install && cd ../..</code></div>
        </div>

        <div class="gs-step">
          <h3>2. Initialize HCL project</h3>
          <div class="code-block"><code>tofu init</code></div>
        </div>

        <div class="gs-step">
          <h3>3. Pull Lambda runtime images (one-time)</h3>
          <div class="code-block"><code>uvx --from local-web-services ldk setup lambda</code></div>
          <p>This pulls the official AWS Lambda base images from ECR Public, which include the AWS SDK pre-installed. You only need to do this once.</p>
        </div>

        <div class="gs-step">
          <h3>4. Start the local environment</h3>
          <div class="code-block"><code>uvx --from local-web-services ldk dev</code></div>
          <p>The <code>ldk dev</code> command auto-detects your HCL project, starts all AWS service providers in always-on mode, and generates a <code>_lws_override.tf</code> file that redirects Terraform's AWS provider to your local endpoints.</p>
        </div>

        <div class="gs-step">
          <h3>5. Apply HCL</h3>
          <p>In another terminal, apply your HCL configuration against the local services:</p>
          <div class="code-block"><code>tofu apply -auto-approve</code></div>
          <p>Your HCL tool creates all resources (DynamoDB tables, SQS queues, Lambda functions, API Gateway routes, etc.) against your local endpoints. No AWS account needed.</p>
        </div>

        <div class="gs-step">
          <h3>6. Test the application</h3>
          <div class="code-block"><code># Run the end-to-end test script
bash test-orders.sh

# Or test manually with lws commands
uvx --from local-web-services lws dynamodb scan --table-name Orders
uvx --from local-web-services lws stepfunctions start-execution \
  --name OrderWorkflow \
  --input '{"orderId": "test-123", "items": ["widget"], "total": 29.99}'</code></div>
        </div>
      </div>
    </div>
  </section>

  <section class="section section-alt">
    <div class="container">
      <h2>Claude Code Integration</h2>
      <p class="section-lead">Set up slash commands and context for AI code editors so Claude can manage your local AWS fakes and chaos testing.</p>

      <div class="getting-started-steps">
        <div class="gs-step">
          <h3>Initialize</h3>
          <div class="code-block"><code>uvx --from local-web-services lws init</code></div>
          <p>This creates three files in your project:</p>
          <ul>
            <li><code>CLAUDE.md</code> &mdash; LWS quick reference and CLI commands that Claude reads automatically</li>
            <li><code>.claude/commands/lws/fake.md</code> &mdash; The <code>/lws:fake</code> slash command</li>
            <li><code>.claude/commands/lws/chaos.md</code> &mdash; The <code>/lws:chaos</code> slash command</li>
          </ul>
          <p>The command is idempotent &mdash; running it again updates existing files without duplicating content.</p>
        </div>

        <div class="gs-step">
          <h3>Slash Commands</h3>
          <p>Once initialized, two slash commands are available in Claude Code:</p>
        </div>
      </div>

      <div class="feature-grid" style="grid-template-columns: 1fr 1fr; max-width: 900px; margin: 0 auto;">
        <div class="feature-card">
          <div class="feature-icon">/</div>
          <h3>/lws:fake</h3>
          <p>Guides Claude through creating and configuring AWS operation fakes. Supports file-based fakes (persist across restarts) and runtime fakes (configured on the fly). Includes service-aware helpers for DynamoDB JSON, S3 XML, SQS messages, and more.</p>
        </div>
        <div class="feature-card">
          <div class="feature-icon">/</div>
          <h3>/lws:chaos</h3>
          <p>Guides Claude through enabling chaos engineering on AWS services. Configure error rates, latency injection, timeouts, and connection resets. Includes common scenarios for testing retry logic, circuit breakers, and timeout handling.</p>
        </div>
      </div>

      <div class="getting-started-steps" style="margin-top: 48px;">
        <div class="gs-step">
          <h3>What Gets Added to CLAUDE.md</h3>
          <p>The <code>CLAUDE.md</code> snippet gives Claude context about your LWS environment, including how to start the dev server, check status, and use fake and chaos commands. This context is read automatically by Claude Code when working in your project.</p>
        </div>
      </div>
    </div>
  </section>

  <footer class="footer">
    <div class="container">
      <div class="footer-inner">
        <div class="footer-brand">
          <a href="index.html" class="nav-logo">Local Web Services</a>
          <p>The fastest feedback loop for cloud-native development, for humans and AI alike</p>
        </div>
        <div class="footer-links">
          <a href="https://github.com/local-web-services/local-web-services">GitHub</a>
          <a href="https://github.com/local-web-services/local-web-services/tree/main/sample-project/cdk">CDK Sample</a>
          <a href="https://github.com/local-web-services/local-web-services/tree/main/sample-project/hcl">Terraform Sample</a>
          <a href="https://github.com/local-web-services/local-web-services/issues">Issues</a>
        </div>
      </div>
      <p class="footer-copy">Open source under the MIT License.</p>
    </div>
  </footer>


  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-core.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-clike.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-bash.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-python.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-yaml.min.js"></script>
  <script src="lws.js"></script>
</body>
</html>