• S3Mock
• Quick Start
• Changelog
• Version Compatibility
• Migration Guides
  • 4.x to 5.x (Current)
  • 3.x to 4.x
• Supported S3 Operations
• Usage
  • Docker (Recommended)
  • Testcontainers
  • JUnit 5 Extension
  • TestNG Listener
  • AWS CLI
  • cURL
• Configuration
• Important Limitations
• Troubleshooting
• File System Structure
• Performance & Resources
• Architecture & Development
• Build & Run
• Contributing
• License

S3Mock is a lightweight server implementing parts of the Amazon S3 API for local integration testing. It eliminates the need for actual AWS infrastructure during development and testing.

Recommended usage: Run S3Mock as a Docker container or with Testcontainers to avoid classpath conflicts.

Get up and running in 30 seconds:

# 1. Start S3Mock
docker run -p 9090:9090 adobe/s3mock

# 2. Create a bucket
aws s3api create-bucket --bucket my-bucket --endpoint-url http://localhost:9090

# 3. Upload a file
aws s3api put-object --bucket my-bucket --key my-file --body ./my-file --endpoint-url http://localhost:9090

# 4. Download the file
aws s3api get-object --bucket my-bucket --key my-file --endpoint-url http://localhost:9090 output-file

For programmatic testing, see Testcontainers or JUnit 5 Extension below.

• GitHub Releases
• Detailed Changelog

• Jackson 3: XML annotations updated to Jackson 3 (tools.jackson packages)
• AWS SDK v1 removed: All v1 client support has been dropped
• JUnit 4 removed: The s3mock-junit4 module no longer exists
• Controller package moved: com.adobe.testing.s3mock to com.adobe.testing.s3mock.controller
• Legacy properties removed: Old-style configuration properties have been removed
• Apache Commons removed: commons-compress, commons-codec, commons-lang3 replaced by Kotlin/Java stdlib
• Owner DisplayName removed: AWS APIs stopped returning DisplayName - this is a file system breaking change for existing data

• Tomcat replaces Jetty: Application container changed from Jetty to Tomcat
• Versioning API: Basic support for S3 versioning added
• If-(Un)modified-Since: Conditional request handling implemented

For full details, see the Changelog.

See the complete operations table in AWS documentation.

The Docker image is available on Docker Hub and is the recommended way to run S3Mock.

Basic usage:

docker run -p 9090:9090 -p 9191:9191 adobe/s3mock

Ports: 9090 (HTTP), 9191 (HTTPS)

With configuration:

docker run -p 9090:9090 -p 9191:9191 \
  -e COM_ADOBE_TESTING_S3MOCK_STORE_INITIAL_BUCKETS=test-bucket \
  -e debug=true \
  adobe/s3mock

Docker Compose:

services:
  s3mock:
    image: adobe/s3mock:latest
    environment:
      - COM_ADOBE_TESTING_S3MOCK_STORE_INITIAL_BUCKETS=bucket1,bucket2
    ports:
      - 9090:9090
      - 9191:9191

With persistent storage:

services:
  s3mock:
    image: adobe/s3mock:latest
    environment:
      - COM_ADOBE_TESTING_S3MOCK_STORE_ROOT=containers3root
      - COM_ADOBE_TESTING_S3MOCK_STORE_RETAIN_FILES_ON_EXIT=true
    ports:
      - 9090:9090
    volumes:
      - ./locals3root:/containers3root

The S3MockContainer provides a pre-configured Testcontainers implementation.

Maven dependency:

<dependency>
  <groupId>com.adobe.testing</groupId>
  <artifactId>s3mock-testcontainers</artifactId>
  <version>...</version>
  <scope>test</scope>
</dependency>

Usage example:

@Testcontainers
class MyTest {
  @Container
  val s3Mock = S3MockContainer("latest")
    .withInitialBuckets("test-bucket")

  @Test
  fun test() {
    val s3Client = S3Client.builder()
      .endpointOverride(URI.create(s3Mock.httpEndpoint))
      .region(Region.US_EAST_1)
      .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create("foo", "bar")
      ))
      .build()

    s3Client.createBucket { it.bucket("my-bucket") }
  }
}

Note: This module may be removed in S3Mock 6.x. Consider using Testcontainers instead.

Maven dependency:

<dependency>
  <groupId>com.adobe.testing</groupId>
  <artifactId>s3mock-junit5</artifactId>
  <version>...</version>
  <scope>test</scope>
</dependency>

Usage:

@ExtendWith(S3MockExtension::class)
class MyTest {
  @Test
  fun test(s3Client: S3Client) {
    s3Client.createBucket { it.bucket("test-bucket") }
  }
}

See examples: Declarative | Programmatic

Note: This module may be removed in S3Mock 6.x. Consider using Testcontainers instead.

Maven dependency:

<dependency>
  <groupId>com.adobe.testing</groupId>
  <artifactId>s3mock-testng</artifactId>
  <version>...</version>
  <scope>test</scope>
</dependency>

Configure in testng.xml - see example configuration.

Use with --endpoint-url and --no-verify-ssl (for HTTPS):

# Create bucket
aws s3api create-bucket --bucket my-bucket --endpoint-url http://localhost:9090

# Upload object
aws s3api put-object --bucket my-bucket --key my-file --body ./my-file --endpoint-url http://localhost:9090

# Download object
aws s3api get-object --bucket my-bucket --key my-file --endpoint-url http://localhost:9090 output-file

# HTTPS
aws s3api get-object --bucket my-bucket --key my-file --no-verify-ssl --endpoint-url https://localhost:9191 output-file

# Create bucket
curl -X PUT http://localhost:9090/my-bucket/

# Upload object
curl -X PUT --upload-file ./my-file http://localhost:9090/my-bucket/my-file

# Download object
curl http://localhost:9090/my-bucket/my-file -O

# HTTPS (with self-signed certificate)
curl --insecure https://localhost:9191/my-bucket/my-file -O

Configure S3Mock using environment variables:

• Path-style access only: S3Mock supports http://localhost:9090/bucket/key, not http://bucket.localhost:9090/key
• Presigned URLs: Accepted but not validated (expiration, signature, HTTP verb not checked)
• Self-signed SSL: Included certificate requires clients to trust it or ignore SSL errors
• KMS: Key validation only - no actual encryption performed
• Not for production: S3Mock is a testing tool and lacks security features required for production use

S3Mock stores data on disk with the following structure:

<root>/
  <bucket-name>/
    bucketMetadata.json              # Bucket metadata
    <object-uuid>/
      binaryData                     # Object content
      objectMetadata.json            # Object metadata
      <version-id>-binaryData        # Versioned object (if versioning enabled)
      <version-id>-objectMetadata.json
    multiparts/
      <upload-id>/
        multipartMetadata.json
        <part-number>.part

Note: The file system structure is an implementation detail and may change between releases. While files can be inspected during runtime, reusing persisted data across restarts is not officially supported.

S3Mock is designed for testing, not production workloads. Keep the following in mind:

• Disk: All objects are stored on the local filesystem — disk usage grows with stored data
• Memory: Scales with concurrent multipart uploads and in-flight requests
• CI environments: Consider setting Docker resource limits (e.g., --memory=512m) to avoid contention with other services
• Cleanup: By default, S3Mock deletes all stored data on shutdown. Use RETAIN_FILES_ON_EXIT=true only when needed

graph LR
    Client["AWS SDK / CLI / cURL"] -->|HTTP :9090 / HTTPS :9191| Controller
    subgraph S3Mock
        Controller["Controller<br/>(REST endpoints)"] -->|delegates| Service["Service<br/>(business logic)"]
        Service -->|coordinates| Store["Store<br/>(persistence)"]
        Store -->|read/write| FS["Filesystem"]
    end

Module Documentation:

• Project Overview - Architecture, code style, DO/DON'T guardrails
• Server Module - Core implementation (Controller→Service→Store layers)
• Integration Tests - Testing with AWS SDK v2 clients
• Test Support - Testcontainers, JUnit 5, TestNG integrations

Requirements: Java 17+, Maven 3.9+, Docker (for Docker build and integration tests)

Build:

# Full build with Docker
./mvnw clean install

# Skip Docker build
./mvnw clean install -DskipDocker

Run from source:

# As Spring Boot application
./mvnw spring-boot:run -pl server

# As Docker container
./mvnw clean package -pl server -am -DskipTests
docker run -p 9090:9090 -p 9191:9191 adobe/s3mock:latest

Run integration tests:

./mvnw verify -pl integration-tests

Technology:

• Built with Kotlin 2.3.0 and Spring Boot 4.0
• Tests written in Kotlin
• Target JVM: 17

Contributions are welcome! See Contributing Guide.

Governance: Project leads make final decisions - see developers in pom.xml.

Security: See Security Policy for reporting vulnerabilities. S3Mock uses GitHub Actions for SBOM and vulnerability scanning.

Licensed under the Apache License 2.0 - see LICENSE.