Localstack-spring-boot-starter is a SpringBoot starter for LocalStack auto-configuration.
This starter will spin up the Localstack docker container using Testcontainers
and auto-configure beans such as AmazonS3, AmazonSQSAsync, etc.
LocalStack provides an easy-to-use test/mocking framework for developing AWS based Cloud applications.
We can use Testcontainers to spin up a Localstack docker container,
but we need to configure Amazon service clients like AmazonS3, AmazonSQSAsync which is typical boilerplate that we copy-paste from project to project.
Instead of copy-pasting the code snippets, creating a SpringBoot starter which autoconfigures the Amazon service clients is a better approach and less error prone.
Hence, the birth of localstack-spring-boot-starter :-)
- JDK 8+
- Tested with SpringBoot 2.3.3.RELEASE, should work fine with any SpringBoot 2.x versions
Maven
<dependencies>
<dependency>
<groupId>io.github.sivalabs</groupId>
<artifactId>localstack-spring-boot-starter</artifactId>
<version>0.0.1</version>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>localstack</artifactId>
<version>1.14.3</version>
</dependency>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-java-sdk</artifactId>
<version>1.11.852</version>
</dependency>
</dependencies>Gradle
implementation 'io.github.sivalabs:localstack-spring-boot-starter:0.0.1'
implementation 'org.testcontainers:localstack:1.14.3'
implementation 'com.amazonaws:aws-java-sdk:1.11.852'You can enable LocalStack AutoConfiguration by adding @EnableLocalStack annotation to either main entrypoint class or
any @Configuration class.
package com.sivalabs.demo;
import io.github.sivalabs.localstack.EnableLocalStack;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.sqs.AmazonSQSAsync;
import org.springframework.beans.factory.annotation.Autowired;
@SpringBootApplication
@EnableLocalStack
public class LocalStackStarterDemoApplication {
@Autowired
private AmazonS3 amazonS3;
@Autowired
private AmazonSQSAsync amazonSQS;
public static void main(String[] args) {
SpringApplication.run(LocalStackStarterDemoApplication.class, args);
}
}You may want to use localstack-spring-boot-starter only for testing.
In that case, you can add @EnableLocalStack annotation combined with @Profile("integration-test") annotation
so that the Localstack AutoConfiguration is only activated while running integration tests.
@Configuration
@EnableLocalStack
@Profile("integration-test")
public class TestConfig {
}You can activate integration-test profile using @ActiveProfiles as follows:
@SpringBootTest
@ActiveProfiles("integration-test")
class SomeIntegrationTest {
@Autowired
private AmazonS3 amazonS3;
@Autowired
private AmazonSQSAsync amazonSQS;
@Test
void someTest() {
}
} The following configuration properties are available to customize the default behaviour.
| Property | Required | Default Value |
|---|---|---|
localstack.enabled |
no | true |
localstack.edgePort |
no | 4566 |
localstack.defaultRegion |
no | us-east-1 |
localstack.hostname |
no | localhost |
localstack.hostnameExternal |
no | localhost |
localstack.dockerImage |
no | localstack/localstack:0.11.2 |
localstack.useSsl |
no | false |
localstack.services |
no | "" |
You can customize which AWS services to enable/disable as follows:
| Property | Value | Default Value |
|---|---|---|
localstack.services |
SQS, S3, SNS, DYNAMODB, DYNAMODBSTREAMS, KINESIS, IAM, LAMBDA, CLOUDWATCH, SECRETSMANAGER |
"" |
localstack.s3.enabled |
false |
true |
localstack.sqs.enabled |
true |
true |
localstack.sns.enabled |
false |
true |
localstack.dynamodb.enabled |
true |
true |
localstack.dynamodbstreams.enabled |
false |
true |
localstack.kinesis.enabled |
true |
true |
localstack.iam.enabled |
false |
true |
localstack.secretsmanager.enabled |
true |
true |
localstack.lambda.enabled |
false |
true |
localstack.cloudwatch.enabled |
true |
true |
You can contribute to localstack-spring-boot-starter project in many ways:
- Use the starter and report if there are any bugs by opening an issue
- Add support for auto-configuration of more services
- Add more example applications
The implementation of localstack-spring-boot-starter is inspired by testcontainers-spring-boot.
The testcontainers-spring-boot also provides localstack support, but it only spins up the docker container, and
you will have to configure the beans like AmazonS3, AmazonSQSAsync etc by yourself.
Procedure for deploying to Maven Central https://central.sonatype.org/pages/apache-maven.html
Set version to SNAPSHOT (ex: 1.0.0-SNAPSHOT)
Deploy SNAPSHOT version to https://oss.sonatype.org/content/repositories/snapshots/
localstack-spring-boot-starter> ./mvnw clean deploy -PreleaseDeploy release version to Maven Central
localstack-spring-boot-starter> ./mvnw release:clean release:prepare -Prelease
localstack-spring-boot-starter> ./mvnw release:perform -PreleaseSearch for release artifacts on https://oss.sonatype.org/#nexus-search;quick~sivalabs
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent