Mini S3

A simple, filesystem-backed server implementing a subset of the S3 REST API, in pure Go. See SPEC.md for the original specification and docs/ for full documentation.

Features

• SigV4-authenticated S3 REST API subset (see docs/api.md for exactly what's implemented), including multipart uploads and the S3-Express-style CreateSession/RenameObject operations
• Objects stored directly on the filesystem, one directory per bucket
• TOML configuration with general.include file merging and full environment-variable overrides (see docs/configuration.md)
• SIGHUP config/cert/log reload, SIGTERM graceful shutdown
• Prometheus metrics (see docs/metrics.md)
• Pure Go, no CGO; builds for Linux amd64/arm64, macOS arm64, and FreeBSD amd64/arm64

Quick start

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

cp examples/minis3.toml my.toml
# edit my.toml: point network.tls at cert.pem/key.pem, set a real
# access_key_id/secret_access_key, and a bucket path to store objects in

go run ./cmd/minis3 --config my.toml

Then, from another terminal:

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

See docker/ for a containerized example.

Building

go build ./cmd/minis3

Testing

go test ./...                      # unit tests
go test ./test/integration/...     # integration tests, driven by the real aws-sdk-go-v2 client
go vet ./...

Repository layout

cmd/minis3/          entrypoint: flags, signals, wiring
internal/config/      TOML config loading, include-merging, env overrides
internal/logging/      slog setup, reopenable log file (SIGHUP rotation)
internal/auth/         SigV4 verification, aws-chunked decoding, sessions
internal/storage/       filesystem-backed object storage (os.Root-confined)
internal/s3api/         HTTP routing, XML request/response handling
internal/metrics/       Prometheus metrics
internal/server/        TLS listeners, hot reload, graceful shutdown
test/integration/       end-to-end tests against a real S3 client
docs/                    MkDocs documentation source
docker/                  Dockerfile and docker-compose example
packaging/debian/        Debian package build script, systemd unit, maintainer scripts
.forgejo/workflows/      CI, release, and docs-publishing workflows
examples/                sample configuration and systemd unit