Getting started

TinyS3 runs three ways: as a Docker container, a standalone Java server, or an embedded library inside your JVM process. All of them expose the same S3 API.

Docker (fastest)

cat > config.yaml <<EOF
server:
  port: 8000
  baseUrl: "http://localhost:8000"
auth:
  accessKey: "admin"
  secretKey: "admin-secret"
  region: "us-east-1"
storage:
  mode: simple
  path: /data
EOF

docker run -v ./config.yaml:/etc/tinys3/config.yaml:ro \
           -v tinys3-data:/data \
           -p 8000:8000 \
           tinys3/server --config /etc/tinys3/config.yaml

Point any S3 client at it:

export AWS_ACCESS_KEY_ID=admin AWS_SECRET_ACCESS_KEY=admin-secret
aws s3 mb s3://my-bucket --endpoint-url http://localhost:8000
aws s3 cp file.txt s3://my-bucket/ --endpoint-url http://localhost:8000

The web console is at http://localhost:8000/console/ — sign in with the same credentials.

See Docker for every option the image accepts, and docker-compose examples for simple and erasure-coded setups.

Download a release

Every GitHub release ships ready-to-run artifacts (web console included):

Artifact	Run with
tinys3-<version>-all.jar	java -jar tinys3-<version>-all.jar --config config.yaml
tinys3-<version>.zip / .tar	unpack, then bin/tinys3 --config config.yaml

Requires Java 25 on the machine.

Standalone server

git clone https://github.com/devdilson/tiny-s3 && cd tiny-s3
./gradlew :tiny-s3-app:runTestServerSingleDisk   # port 8000, simple storage

Requires Java 25. Configuration comes from a YAML file — see Configuration.

Embedded library

TinyS3 is published to Maven Central as dev.totis:tiny-s3-lib. Handy for integration tests that need a real S3 endpoint without containers:

S3Server server = new S3Server.Builder()
    .withPort(8000)
    .withCredentials(new Credentials("access-key", "secret-key", "us-east-1"))
    .withStorageDir("storage")   // or .withInMemory() for tests
    .build();
server.start();

See Building & embedding for erasure-coded storage, TLS, and the rest of the builder API.

Choosing a storage mode

Mode	When
simple	Single disk, simplest setup — development, CI, small deployments
erasure	Multiple disks, tolerates disk failures, self-healing — anything you care about
in-memory	Tests only (embedded library)

Details in Storage modes.