Describe how to use Localstack to improve the development experience with AWS

menu/menu.yaml

@@ -1113,6 +1113,8 @@
       Title: Native Integration
     - Url: transports/sqs/operations-scripting
       Title: Scripting
+    - Url: nservicebus/aws/local-development
+      Title: Local development
     - Url: transports/sqs/troubleshooting
       Title: Troubleshooting
 
@@ -1360,6 +1362,8 @@
       Title: Outbox
     - Url: persistence/dynamodb/transactions
       Title: Transactions
+    - Url: nservicebus/aws/local-development
+      Title: Local development
 
 - Name: ServiceInsight
   Topics:

nservicebus/aws/index.md

@@ -0,0 +1,5 @@
+---
+title: AWS local development
+summary: Guidance on local development when using AWS
+reviewed: 2024-10-29
+---

nservicebus/aws/local-development.md

@@ -0,0 +1,36 @@
+---
+title: AWS local development using LocalStack
+summary: How to use LocalStack for your development needs when using Amazon SQS Transport and DynamoDB Persistence
+reviewed: 2024-10-29
+---
+
+[LocalStack](https://www.localstack.cloud/) is a tool to develop and test your AWS applications locally, reducing development time and increasing productivity.
+
+> [!NOTE]
+> Refer to the [official LocalStack documentation](https://docs.localstack.cloud/getting-started/installation/) to learn how to install and run it locally.
+
+To configure an NServiceBus endpoint to connect to LocalStack instead of AWS, the AWS endpoint URL must be set to the address of the LocalStack instance. The simplest way is by defining the `AWS_ENDPOINT_URL` environment variable and setting its value to the LocalStack URL:
+
+```
+AWS_ENDPOINT_URL=http://localhost.localstack.cloud:4566
+```
+
+Alternatively, configure the AWS SDK `ServiceURL` configuration property, like in the following example programmatically:
+
+
+```csharp
+var amazonSqsConfig = new AmazonSQSConfig();
+amazonSqsConfig.ServiceURL = "http://localhost.localstack.cloud:4566";
+var amazonSqsClient = new AmazonSQSClient(amazonSqsConfig);
+```
+
+
+> [!NOTE]
+> Remember that, even if you are not connecting to AWS cloud services, it is still required to specify access credentials and region.
+> From the LocalStack perspective they could be fake values, like the following:
+>
+> ```bash
+> AWS_ACCESS_KEY_ID=demo
+> AWS_SECRET_ACCESS_KEY=demo
+> AWS_REGION=us-east-1
+> ```

servicecontrol/transports.md

@@ -1,6 +1,6 @@
 ---
 title: Transport configuration
-summary: ServiceControl can be configured to use one of the supported message transports which are configured for each instance type 
+summary: ServiceControl can be configured to use one of the supported message transports which are configured for each instance type
 reviewed: 2024-07-19
 component: ServiceControl
 ---
@@ -99,6 +99,10 @@ The following ServiceControl connection string options are available:
 * `S3KeyPrefix=<value>` - S3 key prefix [option](/transports/sqs/configuration-options.md#offload-large-messages-to-s3-key-prefix).
 * `DoNotWrapOutgoingMessages=true` - Do not wrap outgoing messages [option](/transports/sqs/configuration-options.md#do-not-wrap-message-payload-in-a-transport-envelope).
 
+> [!NOTE]
+> When using SQS as a transport, for local development purposes it is possible to set up ServiceControl to connect to a LocalStack instance.
+> Refer to the [documentation](/nservicebus/aws/local-development.md) about how to configure the environment to use LocalStack.
+
 ## MSMQ
 
 To configure MSMQ as the transport, ensure the MSMQ service has been installed and configured as outlined in [MSMQ configuration](/transports/msmq/#msmq-configuration).