revamp sam docs + add vs code launch config

content/en/user-guide/integrations/aws-sam/index.md

@@ -5,35 +5,87 @@ description: >
  Use the AWS SAM (Serverless Application Model) with LocalStack
 ---
 
-![AWS SAM](aws-sam-logo.jpg)
+## Introduction
 
-## Overview
+The AWS Serverless Application Model (SAM) is an open-source framework for developing serverless applications. It uses a simplified syntax to define functions, APIs, databases, and event source mappings. When you deploy, SAM converts its syntax into AWS CloudFormation syntax, helping you create serverless applications more quickly.
 
-The AWS Serverless Application Model (SAM) is a framework on top of CloudFormation to quickly develop Cloud Applications with a focus on serverless services such as S3, Lambda, API Gateway, Step Functions and more.
+LocalStack can work with SAM using the AWS SAM CLI for LocalStack. This CLI comes in the form of a `samlocal` wrapper script, which lets you deploy SAM applications on LocalStack. This guide explains how to set up local AWS resources using the `samlocal` wrapper script.
 
-## AWS SAM CLI for LocalStack
 
-To deploy SAM applications on [LocalStack](https://github.com/localstack/localstack) you can use [samlocal](https://github.com/localstack/aws-sam-cli-local), a wrapper for the [AWS SAM CLI](https://github.com/aws/aws-sam-cli).
+## `samlocal` wrapper script
 
-### Installation
+`samlocal` is a wrapper for the `sam` command line interface, facilitating the use of SAM framework with LocalStack. When executing deployment commands like `samlocal ["build", "deploy", "validate", "package"]`, the script configures the SAM settings for LocalStack and runs the specified SAM command.
 
-Simply use `pip` to install `samlocal` as a Python library on your machine:
+### Install the `samlocal` wrapper script
+
+You can install the `samlocal` wrapper script by running the following command:
 
 {{< command >}}
 $ pip install aws-sam-cli-local
 {{< / command >}}
 
-### Usage
+### Create a new Pulumi project
 
-The `samlocal` command has the exact same usage as the underlying `sam` command. The main difference is that for commands like `samlocal deploy` the operations will be executed against the LocalStack endpoints (`http://localhost:4566` by default) instead of real AWS endpoints.
+You can initialize a new SAM project using the following command:
 
 {{< command >}}
-$ samlocal --help
+$ samlocal init
 {{< / command >}}
 
-Start using `samlocal` by deploying a [Hello World Application](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started-hello-world.html).
-Please make sure to replace all `sam` calls with `samlocal` when following the AWS tutorial.
+Select `1` to create a new SAM application using an AWS Quick Start template. The SAM CLI will ask you for the project name and the runtime for the Lambda function.
+
+For this example, select `1` for the Hello World example. Choose the Python runtime and `zip` for the packaging type. Optionally, you can enable X-Ray tracing, monitoring, and structured JSON logging. Then, enter the project name and press `Enter`.
+
+### Deploy the SAM application
+
+After initializing the SAM project, enter the project directory and deploy the application using the following command:
+
+{{< command >}}
+$ samlocal deploy --guided
+{{< / command >}}
+
+Enter the default values for the deployment, such as the stack name, region, and confirm the changes. The `samlocal` wrapper will package and deploy the application to LocalStack.
 
 ### Configuration
 
-* `AWS_ENDPOINT_URL`: The endpoint URL (i.e., protocol, host, and port) to connect to LocalStack (default: `http://localhost:4566`)
+| Environment Variable | Default value | Description |
+|------------------------|--------------------------------------------------|-------------------------------------------------------------------------|
+| AWS_ENDPOINT_URL | `http://localhost.localstack.cloud:4566` | URL at which the `boto3` client can reach LocalStack |
+| EDGE_PORT | `4566` (Deprecated) | Port number under which the LocalStack edge service is available |
+| LOCALSTACK_HOSTNAME | `localhost` (Deprecated) | Host under which the LocalStack edge service is available
+
+## Debugging on VS Code
+
+To debug your Lambda functions in VS Code while using the SAM CLI with LocalStack, set up a launch configuration in the `.vscode/launch.json` file. Insert the following settings into the file:
+
+
+```json
+{
+ "type": "aws-sam",
+ "request": "direct-invoke",
+ "name": "Job dispatcher lambda",
+ "invokeTarget": {
+ "target": "code",
+ "projectRoot": "${workspaceFolder}",
+ "lambdaHandler": "lambda/lambda.handler"
+ },
+ "lambda": {
+ "runtime": "python3.8",
+ "payload": {},
+ "environmentVariables": {
+ "ENDPOINT_URL": "http://localstack:4566/",
+ "S3_ENDPOINT_URL": "http://s3.localhost.localstack.cloud:4566/",
+ "AWS_ACCESS_KEY_ID": "test",
+ "AWS_SECRET_ACCESS_KEY": "test",
+ "AWS_SESSION_TOKEN": "test",
+ "AWS_REGION": "us-east-1",
+ "MAIN_DOCKER_NETWORK": "localstack-network"
+ }
+ },
+ "sam": {
+ "dockerNetwork": "localstack-network"
+ }
+ }
+```
+
+The `dockerNetwork` property is essential as it allows the LocalStack container to use the `samlocal invoke` commands within the same network as the LocalStack container itself. Adjust the Lambda function handler and environment variables as needed.