Mini S3

Mini S3 is a server implementing a subset of the S3 REST API. It is aimed at scenarios where a simple, easy to configure and use S3-compatible service is needed, without the overhead and complexity of a full-fledged object storage system.

Mini S3 stores objects directly in the filesystem, one configured directory per bucket. It supports AWS Signature Version 4 authentication with per-bucket, per-key credentials, but has no ACLs, no encryption at rest, no clustering, and no built-in redundancy.

What Mini S3 is not

Mini S3 is deliberately small. It does not implement:

  • Bucket ACLs, bucket policies, or object ownership controls
  • Server-side encryption
  • Object versioning (beyond reporting a single "null" version per object, for ListObjectVersions compatibility)
  • Replication, lifecycle rules, or storage classes
  • Multi-node clustering or redundancy

See API Coverage for the exact list of S3 operations Mini S3 implements versus rejects with AccessDenied.

Quick start

  1. Generate (or obtain) a TLS certificate and key — by default Mini S3 terminates TLS itself and serves HTTPS. For local testing:

    openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj "/CN=localhost"

    (Skip this if you'll run Mini S3 behind a reverse proxy instead — see Deployment & Signals.)

  2. Copy examples/minis3.toml and edit the [network.tls], [network.listen], and [[bucket]] sections. See Configuration for every option.

  3. Run it:

    minis3 --config minis3.toml

  4. Point any S3 client at it, using path-style addressing:

    aws --endpoint-url https://localhost:443 s3api put-object \
  --bucket example --key hello.txt --body hello.txt

Design notes and simplifications

A few places where Mini S3 knowingly diverges from real S3 behavior, to keep the implementation small:

  • Addressing: path-style only (https://host/bucket/key); no virtual-hosted-style addressing.
  • CreateSession: Mini S3 has no STS, so the "temporary" credentials it returns are literally the bucket's own configured access key and secret, scoped only by an opaque, time-limited session token. See API Coverage for details.
  • CopyObject: only same-bucket copies are supported (matching the directory-bucket-flavored subset of the API this server targets).
  • ETags and object metadata: since the filesystem itself has no notion of ETag or user metadata, Mini S3 stores a small JSON sidecar file per object (under a hidden .minis3-meta/ directory in the bucket). If an object appears on disk without its sidecar (e.g. after being placed there directly), the ETag is computed on first access and cached from then on.