Everything a test expects from S3
90+ S3 operations
Objects, multipart uploads, versioning, tagging, ACLs, CORS, policies, browser form uploads and paginated listings, with SigV4 verification and path-style or virtual-hosted-style requests.
Faithful semantics
Conditional reads, writes and deletes that are atomic per key, Amazon S3 entity tags for multipart uploads, and the validation of Amazon S3 for bucket names and part sizes.
Iceberg REST catalog & S3 Tables
A built-in Iceberg REST catalog and Amazon S3 Tables on the same port, so a lakehouse test needs one process. Delta Lake, DuckDB, DuckLake, Paimon and Hudi work too.
S3 Vectors
Vector buckets, indexes and similarity search, reached with the AWS SDK's S3VectorsClient.
Embed it anywhere
A Java API, a JUnit 5 extension, a Spring Boot 3 and 4 starter, a Testcontainers module, a Docker image (JVM or GraalVM native) or an executable jar.
JetBrains plugin
An S3 service that starts with IntelliJ IDEA, PyCharm or DataGrip, with project buckets and seed data from .locals3.json, and connection settings copied for DuckDB, boto3, Spark or the AWS CLI.
Memory or disk
In-memory and persistent modes, and in-memory services that start from a fixture directory. Data directories of hundreds of thousands of objects open without loading all their metadata.
STS, KMS & S3 Express
Stateless STS and KMS endpoints, and S3 Express One Zone directory buckets, so credential-vending catalogs and encryption clients run unchanged.
Console, website & MCP
A built-in console at /_admin/ui, static website hosting, and an MCP server at /_mcp so AI agents can keep their artifacts in LocalS3.
Quick start
- JUnit 5
- Spring Boot + Testcontainers
- Java
- Docker
<dependency>
<groupId>org.mvnsearch</groupId>
<artifactId>local-s3-jupiter</artifactId>
<version>last_version</version>
<scope>test</scope>
</dependency>
@LocalS3
class AppTest {
@Test
void test(S3Client s3) {
s3.createBucket(b -> b.bucket("my-bucket"));
}
}
@SpringBootTest
class UploadTest {
@TestConfiguration(proxyBeanMethods = false)
static class LocalS3Config {
@Bean
@ServiceConnection
LocalS3Container localS3() {
return new LocalS3Container("latest").withBuckets("uploads");
}
}
@Autowired
S3Template s3;
@Test
void uploads() {
s3.upload("uploads", "hello.txt", new ByteArrayInputStream("Hello".getBytes()));
}
}
See Embedding for the dependencies, Docker Compose and the Spring Boot starter.
try (LocalS3 localS3 = LocalS3.builder().port(29090).build()) {
localS3.start();
// point an S3 client at http://localhost:29090, with path-style access
}
docker run -d -p 29090:29090 -e AWS_BUCKETS=my-bucket linuxchina/local-s3
See Deployment for the configuration variables, persistence, HTTPS and the executable jar.
Built for
Tests without an AWS account
Run the S3 code of a service against a real HTTP endpoint with JUnit 5, Testcontainers or Spring Boot.
An S3 server inside your app or IDE
Embed LocalS3 in a Java application or a JetBrains IDE, e.g. as the default S3 of DuckDB.
Lakehouse tests in one process
Point Iceberg, Delta Lake or DuckLake at a fast local S3 with its own catalog built in.
Artifact storage for AI agents
Let an agent keep files and intermediate results through the S3 API or the built-in MCP server.