adobe/S3Mock

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

S3Mock

S3Mock is a lightweight server that implements a subset of the Amazon S3 API for local integration testing. It removes the need for real AWS infrastructure during development and testing.

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

Quick Start

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.

Changelog

• GitHub Releases
• Detailed Changelog

Version Compatibility

Migration Guides

4.x to 5.x (Current)

• Filesystem changes: The internal file structure changed; existing data may be incompatible with the new version.
• Jackson 3: XML annotations migrated to Jackson 3 (tools.jackson packages)
• AWS SDK v1 removed: All v1 client support dropped
• JUnit 4 removed: The s3mock-junit4 module has been removed
• Controller package moved: com.adobe.testing.s3mock → com.adobe.testing.s3mock.controller
• Legacy environment variables removed: Replaced by new environment variables — see Configuration.
• Legacy properties removed: Replaced by new configuration properties — see Configuration.
• Apache Commons removed: commons-compress, commons-codec, commons-lang3 replaced by Kotlin/Java stdlib
• Owner DisplayName removed: AWS APIs no longer return DisplayName — this is a breaking change for persisted data

3.x to 4.x

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

For full details, see the Changelog.

Supported S3 Operations

See the complete operations table in the AWS documentation.

S3 Vectors Support

S3Mock includes experimental support for the Amazon S3 Vectors API — a separate AWS API for storing and querying high-dimensional vector embeddings.

Enable with the vectors Spring profile. The Vectors API runs on dedicated ports (9092 HTTP, 9193 HTTPS) separate from the standard S3 ports.

Docker:

docker run -p 9090:9090 -p 9191:9191 -p 9092:9092 -p 9193:9193 \
  -e SPRING_PROFILES_ACTIVE=vectors \
  adobe/s3mock

AWS SDK v2 (Kotlin):

val vectorsClient = S3VectorsClient.builder()
  .endpointOverride(URI.create("http://localhost:9092"))
  .region(Region.US_EAST_1)
  .credentialsProvider(StaticCredentialsProvider.create(
    AwsBasicCredentials.create("foo", "bar")
  ))
  .build()

vectorsClient.createVectorBucket { it.vectorBucketName("my-vectors") }

Vector-specific configuration:

Usage

Docker (Recommended)

Available on Docker Hub, the Docker image 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 SPRING_PROFILES_ACTIVE=debug \
  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

Testcontainers

The S3MockContainer provides a ready-to-use 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") }
  }
}

To test the S3 Vectors API, call withVectors() to activate the vectors Spring profile and connect via s3Mock.vectorsHttpEndpoint / s3Mock.vectorsHttpsEndpoint (container ports 9092 / 9193):

@Container
val s3Mock = S3MockContainer("latest").withVectors()

JUnit 5 Extension

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

TestNG Listener

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.

AWS CLI

Pass --endpoint-url to point the CLI at S3Mock, and add --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

cURL

# 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

Configuration

Configure S3Mock using environment variables:

Spring Profiles

Activate profiles via the SPRING_PROFILES_ACTIVE environment variable:

Actuator endpoints are disabled by default. To enable them:

# Via debug or trace profile (also enables verbose logging)
docker run -p 9090:9090 -p 9191:9191 -e SPRING_PROFILES_ACTIVE=debug adobe/s3mock

# Via actuator profile only (no extra logging)
docker run -p 9090:9090 -p 9191:9191 -e SPRING_PROFILES_ACTIVE=actuator adobe/s3mock

# Via individual environment variables (without any profile)
docker run -p 9090:9090 -p 9191:9191 \
  -e MANAGEMENT_ENDPOINTS_ACCESS_DEFAULT=unrestricted \
  -e MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE='*' \
  adobe/s3mock

Health Check

S3Mock exposes two readiness endpoints:

/favicon.ico (always available)

Returns HTTP 200 OK with an empty body. This endpoint is always active, requires no configuration, and is used by Testcontainers and the integration test suite to detect readiness:

curl -sf http://localhost:9090/favicon.ico

/actuator/health (requires actuator profile)

The standard Spring Boot health endpoint. Only available when the actuator profile (or debug/trace) is active:

# Start with actuator enabled
docker run -p 9090:9090 -p 9191:9191 -e SPRING_PROFILES_ACTIVE=actuator adobe/s3mock

# Check health
curl -sf http://localhost:9090/actuator/health

Docker Compose health check example:

services:
  s3mock:
    image: adobe/s3mock:latest
    ports:
      - 9090:9090
      - 9191:9191
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:9090/favicon.ico"]
      interval: 5s
      retries: 3

Important Limitations

• 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: The bundled certificate requires clients to trust it or disable SSL verification
• KMS: Key ARNs are validated, but no actual encryption is performed
• Not for production: S3Mock is a testing tool and lacks the security features required for production use

Troubleshooting

File System Structure

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
        <part-number>.partmeta.json # per-part checksum + size; removed after CompleteMultipartUpload

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.

Performance & Resources

S3Mock is designed for testing, not production workloads:

• Disk: All objects are stored on the local filesystem — disk usage grows proportionally with stored data
• Memory: Consumption scales with concurrent multipart uploads and in-flight requests
• CI environments: Consider setting Docker resource limits (e.g., --memory=256m) to avoid contention with other services
• Cleanup: By default, S3Mock deletes all stored data on shutdown. Set COM_ADOBE_TESTING_S3MOCK_STORE_RETAIN_FILES_ON_EXIT=true only when you need data to survive restarts

Architecture & Development

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
• Agent Skills - implement, test, review, lint, refactor, document

Build & Run

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

Build:

make install       # Full build with Docker
make skip-docker   # Skip Docker build

Run from source:

make run           # As Spring Boot application

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

Run integration tests:

make integration-tests

Technology:

• S3Mock is written in Kotlin 2.3+ (language/API compatibility: 2.2) with Spring Boot 4.0
• All tests are written in Kotlin
• JVM bytecode target: 17; building and running from source requires JDK 25 (per Spring Boot 4.x guidance), while the packaged artifacts run on Java 17+.

Contributing

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 generation and vulnerability scanning.

License

Licensed under the Apache License 2.0 - see LICENSE.