Get started

From nothing to a first bucket.

The image tessaridb/s3 carries the server and nothing else. The repository's compose file runs it beside the TessariDB node that holds its metadata, declares the server's own database account, and publishes S3 and the console on loopback.

1 · Run

One compose file, one `.env`.

Every value in .env is required and none has a default worth keeping: the database owner, the server's own database password, the S3 root key and secret, and a 64-digit key from which users' secret-sealing keys are derived (openssl rand -hex 32).

start the server and its metadata nodeshellwrap

git clone https://github.com/tessaridb/tessaridb-s3
cd tessaridb-s3
cp .env.example .env        # set every value in it
docker compose up -d --wait

2 · Use

Any S3 client. Here, the AWS CLI.

S3 answers on 127.0.0.1:9100, the console on 127.0.0.1:9101. Path-style addressing always works; virtual-hosted style works once the endpoint's domain is configured.

first bucketshellwrap

export AWS_ACCESS_KEY_ID=<S3_ROOT_ACCESS_KEY from .env>
export AWS_SECRET_ACCESS_KEY=<S3_ROOT_SECRET_KEY from .env>
export AWS_DEFAULT_REGION=us-east-1

aws --endpoint-url http://127.0.0.1:9100 s3 mb s3://first
aws --endpoint-url http://127.0.0.1:9100 s3 cp ./photo.jpg s3://first/2026/
aws --endpoint-url http://127.0.0.1:9100 s3 ls s3://first --recursive

3 · From Rust

The Rust SDK and command line.

tessaridb-s3-client is an async SDK built for moving files: streamed from and to disk without holding them in memory, large ones in parts that survive an interrupted transfer, checksums sent on upload and checked on download, and presigned links. tessaridb-s3-cli is the same work from a shell: ls, cp, mv, rm, mb, rb, stat, presign, sync. Both are Apache 2.0 and speak the S3 protocol, never the server's code.

add the SDKshellwrap

cargo add tessaridb-s3-client

4 · Before production

What to change before anybody else connects.

Put a TLS-terminating proxy in front of S3 and the console, or give the console its own certificate; without TLS a console sign-in crosses the network in the clear.
Keep the console on a private address, and configure an identity provider so people sign in with a second factor.
For a cluster, set TESSARIDB_S3_ERASURE, a node id and zone per node, the internal mutual-TLS certificates and the founding members. The documentation walks through it.
Run the TessariDB metadata cluster with a replication factor, and take its snapshot backups; object bytes are protected by erasure coding, but the facts about them live there.

NextLicensing →