JarCastinglocalstack-spring-boot-starter
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.
Motivation
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 :-)
Requirements
- JDK 8+
- Tested with SpringBoot 2.3.3.RELEASE, should work fine with any SpringBoot 2.x versions
How to use?
Add dependencies
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'
Enable LocalStack AutoConfiguration
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);
}
}
How to use only for Integration Tests?
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() {
}
}
Configuration
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 |
Examples
Want to Contribute?
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
Credits
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.
License
Developer Notes
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 -Prelease
Deploy release version to Maven Central
localstack-spring-boot-starter> ./mvnw release:clean release:prepare -Prelease
localstack-spring-boot-starter> ./mvnw release:perform -Prelease
Search for release artifacts on https://oss.sonatype.org/#nexus-search;quick~sivalabs
