Spring Boot + AWS S3 + LocalStack

Production-style example for uploading files to S3 using Spring Boot 3, with:

• unit tests
• controller tests
• integration test using Testcontainers + LocalStack
• Docker Compose for local manual testing

Stack

• Java 21
• Spring Boot 3.3.x
• AWS SDK v2
• JUnit 5 + Mockito
• Testcontainers + LocalStack
• Docker Compose

Run unit + controller tests

mvn test

Run integration tests as well

mvn verify

Run with Docker Compose

docker compose up --build

Upload a file

curl -X POST http://localhost:8080/api/files/upload \
  -F "file=@/absolute/path/to/sample.txt"

Config

Environment variables:

• APP_S3_BUCKET
• APP_AWS_REGION
• APP_S3_ENDPOINT
• APP_AWS_ACCESS_KEY
• APP_AWS_SECRET_KEY
• APP_S3_PATH_STYLE
• APP_S3_AUTO_CREATE_BUCKET

Notes

• In AWS, keep APP_S3_ENDPOINT empty and do not set static credentials if the app runs with IAM role / default credential chain.
• For LocalStack, use endpoint http://localhost:4566 or http://localstack:4566 inside Docker Compose.
• Bucket auto-creation is enabled only when APP_S3_AUTO_CREATE_BUCKET=true.

curl -X POST http://localhost:8080/api/files/upload
-F "file=@/Users/vinodkumar/Documents/Technologies/AWS/springboot-s3-localstack/transactions.csv"