S3Mock

<!-- TOC -->

• 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

<!-- TOC -->

S3Mock

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.

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

| S3Mock | Status | Spring Boot | Kotlin | Java (target) | Java (compile) | AWS SDK v2 | Testcontainers | |--------|-------------|-------------|---------|---------------|----------------|------------|----------------| | 5.x | Active | 4.0.x | 2.3 | 17 | 25 | 2.x | 2.x | | 4.x | Deprecated | 3.x | 2.1-2.2 | 17 | 17 | 2.x | 1.x | | 3.x | Deprecated | 2.x | 1.x-2.0 | 17 | 17 | 2.x | 1.x | | 2.x | End of Life | 2.x | - | 11 | 11 | 1.x/2.x | - |

Migration Guides

4.x to 5.x (Current)

• 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

3.x to 4.x

• 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.

Supported S3 Operations

See the complete operations table in AWS documentation.

<details> <summary><b>Click to expand operations table</b> (operations marked :white_check_mark: are supported)</summary>

| Operation | Support | Comment | |-----------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|------------------------| | AbortMultipartUpload | :white_check_mark: | | | CompleteMultipartUpload | :white_check_mark: | | | CopyObject | :white_check_mark: | | | CreateBucket | :white_check_mark: | | | CreateMultipartUpload | :white_check_mark: | | | DeleteBucket | :white_check_mark: | | | DeleteBucketAnalyticsConfiguration | :x: | | | DeleteBucketCors | :x: | | | DeleteBucketEncryption | :x: | | | DeleteBucketIntelligentTieringConfiguration | :x: | | | DeleteBucketInventoryConfiguration | :x: | | | DeleteBucketLifecycle | :white_check_mark: | | | DeleteBucketMetricsConfiguration | :x: | | | DeleteBucketOwnershipControls | :x: | | | DeleteBucketPolicy | :x: | | | DeleteBucketReplication | :x: | | | DeleteBucketTagging | :x: | | | DeleteBucketWebsite | :x: | | | DeleteObject | :white_check_mark: | | | DeleteObjects | :white_check_mark: | | | DeleteObjectTagging | :white_check_mark: | | | DeletePublicAccessBlock | :x: | | | [GetBucketAccelerateConfiguration](https://docs.aws.amazon.c