{"id":25394098,"url":"https://github.com/sivalabs/localstack-spring-boot-starter","last_synced_at":"2025-10-30T19:31:37.356Z","repository":{"id":40504439,"uuid":"292189104","full_name":"sivalabs/localstack-spring-boot-starter","owner":"sivalabs","description":"SpringBoot Starter for Localstack","archived":false,"fork":false,"pushed_at":"2023-09-21T04:50:22.000Z","size":165,"stargazers_count":50,"open_issues_count":6,"forks_count":17,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-15T10:57:59.187Z","etag":null,"topics":["aws","localstack","spring-boot","spring-boot-starter","testcontainers"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sivalabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-02T05:37:43.000Z","updated_at":"2024-11-02T07:46:04.000Z","dependencies_parsed_at":"2024-11-15T10:58:05.681Z","dependency_job_id":"46982a08-24fe-44cb-8b72-6a8e762f2c1f","html_url":"https://github.com/sivalabs/localstack-spring-boot-starter","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivalabs%2Flocalstack-spring-boot-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivalabs%2Flocalstack-spring-boot-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivalabs%2Flocalstack-spring-boot-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivalabs%2Flocalstack-spring-boot-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sivalabs","download_url":"https://codeload.github.com/sivalabs/localstack-spring-boot-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239040689,"owners_count":19572032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","localstack","spring-boot","spring-boot-starter","testcontainers"],"created_at":"2025-02-15T18:58:36.278Z","updated_at":"2025-10-30T19:31:32.013Z","avatar_url":"https://github.com/sivalabs.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# localstack-spring-boot-starter \n\n![Build](https://github.com/sivalabs/localstack-spring-boot-starter/workflows/Build/badge.svg)\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.sivalabs/localstack-spring-boot-starter)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.github.sivalabs%22)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/sivalabs/localstack-spring-boot-starter/master/LICENSE)\n\n`Localstack-spring-boot-starter` is a [SpringBoot](https://spring.io/projects/spring-boot) starter for [LocalStack](https://github.com/localstack/localstack) auto-configuration.\nThis starter will spin up the *Localstack* docker container using [Testcontainers](https://www.testcontainers.org/) \nand auto-configure beans such as `AmazonS3`, `AmazonSQSAsync`, etc.\n\n## Motivation\n[LocalStack](https://github.com/localstack/localstack) provides an easy-to-use test/mocking framework for developing AWS based Cloud applications.\nWe can use [Testcontainers](https://www.testcontainers.org/modules/localstack/) to spin up a *Localstack* docker container, \nbut we need to configure Amazon service clients like `AmazonS3`, `AmazonSQSAsync` which is typical boilerplate that we copy-paste from project to project.\nInstead of copy-pasting the code snippets, creating a SpringBoot starter which autoconfigures the Amazon service clients is a better approach and less error prone.\nHence, the birth of `localstack-spring-boot-starter` :-)\n\n## Requirements\n* JDK 8+\n* Tested with SpringBoot 2.3.3.RELEASE, should work fine with any SpringBoot 2.x versions\n\n## How to use?\n\n### Add dependencies\n\n**Maven** \n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.github.sivalabs\u003c/groupId\u003e\n        \u003cartifactId\u003elocalstack-spring-boot-starter\u003c/artifactId\u003e\n        \u003cversion\u003e0.0.1\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.testcontainers\u003c/groupId\u003e\n        \u003cartifactId\u003elocalstack\u003c/artifactId\u003e\n        \u003cversion\u003e1.14.3\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.amazonaws\u003c/groupId\u003e\n        \u003cartifactId\u003eaws-java-sdk\u003c/artifactId\u003e\n        \u003cversion\u003e1.11.852\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n**Gradle**\n\n```groovy\nimplementation 'io.github.sivalabs:localstack-spring-boot-starter:0.0.1'\nimplementation 'org.testcontainers:localstack:1.14.3'\nimplementation 'com.amazonaws:aws-java-sdk:1.11.852'\n```\n\n### Enable LocalStack AutoConfiguration\nYou can enable LocalStack AutoConfiguration by adding `@EnableLocalStack` annotation to either main entrypoint class or \nany `@Configuration` class.\n\n```java\npackage com.sivalabs.demo;\n\nimport io.github.sivalabs.localstack.EnableLocalStack;\nimport org.springframework.boot.SpringApplication;\nimport org.springframework.boot.autoconfigure.SpringBootApplication;\nimport com.amazonaws.services.s3.AmazonS3;\nimport com.amazonaws.services.sqs.AmazonSQSAsync;\nimport org.springframework.beans.factory.annotation.Autowired;\n\n@SpringBootApplication\n@EnableLocalStack\npublic class LocalStackStarterDemoApplication {\n    \n    @Autowired\n    private AmazonS3 amazonS3;\n\n    @Autowired\n    private AmazonSQSAsync amazonSQS;\n\n    public static void main(String[] args) {\n        SpringApplication.run(LocalStackStarterDemoApplication.class, args);\n    }\n}\n```\n\n#### How to use only for Integration Tests?\nYou may want to use `localstack-spring-boot-starter` only for testing. \nIn that case, you can add `@EnableLocalStack` annotation combined with `@Profile(\"integration-test\")` annotation \nso that the Localstack AutoConfiguration is only activated while running integration tests.\n\n```java\n@Configuration\n@EnableLocalStack\n@Profile(\"integration-test\")\npublic class TestConfig {\n}\n```\n\nYou can activate `integration-test` profile using `@ActiveProfiles` as follows:\n\n```java\n@SpringBootTest\n@ActiveProfiles(\"integration-test\")\nclass SomeIntegrationTest {\n    @Autowired\n    private AmazonS3 amazonS3;\n    \n    @Autowired\n    private AmazonSQSAsync amazonSQS;\n\n    @Test\n    void someTest() {\n\n    }\n} \n```\n\n### Configuration\n\nThe following configuration properties are available to customize the default behaviour.\n\n| Property                      | Required | Default Value                  |\n|-------------------------------|----------|--------------------------------|\n| `localstack.enabled`          | no       | `true`                         |\n| `localstack.edgePort`         | no       | `4566`                         |\n| `localstack.defaultRegion`    | no       | `us-east-1`                    |\n| `localstack.hostname`         | no       | `localhost`                    |\n| `localstack.hostnameExternal` | no       | `localhost`                    |\n| `localstack.dockerImage`      | no       | `localstack/localstack:0.11.2` |\n| `localstack.useSsl`           | no       | `false`                        |\n| `localstack.services`         | no       | `\"\"`                           |\n\nYou can customize which AWS services to enable/disable as follows:\n\n| Property                             | Value                                                                                       | Default Value |\n|--------------------------------------|---------------------------------------------------------------------------------------------|---------------|\n| `localstack.services`                | `SQS, S3, SNS, DYNAMODB, DYNAMODBSTREAMS, KINESIS, IAM, LAMBDA, CLOUDWATCH, SECRETSMANAGER` | `\"\"`          |\n| `localstack.s3.enabled`              | `false`                                                                                     | `true`        |\n| `localstack.sqs.enabled`             | `true`                                                                                      | `true`        |\n| `localstack.sns.enabled`             | `false`                                                                                     | `true`        |\n| `localstack.dynamodb.enabled`        | `true`                                                                                      | `true`        |\n| `localstack.dynamodbstreams.enabled` | `false`                                                                                     | `true`        |\n| `localstack.kinesis.enabled`         | `true`                                                                                      | `true`        |\n| `localstack.iam.enabled`             | `false`                                                                                     | `true`        |\n| `localstack.secretsmanager.enabled`  | `true`                                                                                      | `true`        |\n| `localstack.lambda.enabled`          | `false`                                                                                     | `true`        |\n| `localstack.cloudwatch.enabled`      | `true`                                                                                      | `true`        |\n\n## Examples\n* [Minimal SpringBoot application](https://github.com/sivalabs/localstack-spring-boot-starter/tree/master/examples/localstack-spring-boot-sample)\n\n## Want to Contribute?\n\nYou can contribute to `localstack-spring-boot-starter` project in many ways:\n* Use the starter and report if there are any bugs by [opening an issue](https://github.com/sivalabs/localstack-spring-boot-starter/issues/new)\n* Add support for auto-configuration of [more services](https://github.com/localstack/localstack#overview)\n* Add more [example applications](https://github.com/sivalabs/localstack-spring-boot-starter/tree/v0.0.2/examples)\n\n## Credits\nThe implementation of `localstack-spring-boot-starter` is inspired by [testcontainers-spring-boot](https://github.com/testcontainers/testcontainers-spring-boot).\nThe `testcontainers-spring-boot` also provides localstack support, but it only spins up the docker container, and \nyou will have to configure the beans like `AmazonS3`, `AmazonSQSAsync` etc by yourself.\n\n## License\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/sivalabs/localstack-spring-boot-starter/master/LICENSE)\n\n## Developer Notes\n\nProcedure for deploying to Maven Central https://central.sonatype.org/pages/apache-maven.html\n\nSet version to SNAPSHOT (ex: 1.0.0-SNAPSHOT)\n\nDeploy SNAPSHOT version to https://oss.sonatype.org/content/repositories/snapshots/\n\n```shell script\nlocalstack-spring-boot-starter\u003e ./mvnw clean deploy -Prelease\n```\n\nDeploy release version to Maven Central\n\n```shell script\nlocalstack-spring-boot-starter\u003e ./mvnw release:clean release:prepare -Prelease\nlocalstack-spring-boot-starter\u003e ./mvnw release:perform -Prelease\n```\n\nSearch for release artifacts on https://oss.sonatype.org/#nexus-search;quick~sivalabs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsivalabs%2Flocalstack-spring-boot-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsivalabs%2Flocalstack-spring-boot-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsivalabs%2Flocalstack-spring-boot-starter/lists"}