README
¶
stowage
A single Go binary that puts a web dashboard, an AWS-SigV4 S3 proxy, and an optional Kubernetes operator in front of any S3-compatible backend — MinIO, Garage, SeaweedFS, AWS S3, R2, B2, Wasabi. One pane of glass for the storage you already run, with audit, quotas, share links, and per-tenant credentials.
Licensed AGPL-3.0-or-later
Quickstart
Pick where you want Stowage to live. Full walkthroughs: one-liner · Docker Compose · Kubernetes.`
One-liner (Linux, macOS, WSL)
curl -fsSL https://stowage.dev/install.sh | sh
Windows (PowerShell)
irm https://stowage.dev/install.ps1 | iex
The installer drops a SHA256-verified binary into the current directory and runs stowage quickstart: a managed MinIO, a SQLite DB, a random admin password, and the dashboard at http://localhost:8080. Nothing is installed system-wide.
Docker Compose
docker compose -f deploy/compose/docker-compose.yml up -d
docker compose -f deploy/compose/docker-compose.yml exec stowage \
stowage create-admin --username admin --password 'S3cur3-P@ssw0rd!'
Kubernetes (Helm)
helm install stowage ./deploy/chart \
--namespace stowage-system --create-namespace \
--set ingress.enabled=true --set ingress.host=stowage.example.com
kubectl -n stowage-system exec deploy/stowage -- \
stowage create-admin --username admin --password 'S3cur3-P@ssw0rd!'
What ships in v1.0
Full feature matrix at stowage.dev/features.
Dashboard. local accounts, an object browser with drag-and-drop multipart upload (pause/resume), previews, version history, tags, rename, cross-bucket move/copy, and download-as-zip.
Public sharing. Share links with passwords, expiry, race-free download caps, and per-IP rate limiting. No presigned-URL plumbing.
Per-tenant SDK access. A second listener (default :8090) accepts SigV4 requests with per-tenant virtual credentials, enforces bucket scope, and re-signs to the upstream. Standard AWS SDKs work unmodified — tenants only see the buckets they were granted.
AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... \
aws --endpoint-url http://stowage:8090 \
s3 cp ./hello.txt s3://uploads/hello.txt
Multi-backend workflows. Cross-backend copy, pinned buckets, and unified search across every configured endpoint.
Quotas. Soft and hard caps per bucket — a warning banner at the soft cap, 507 Insufficient Storage at the hard cap. Applies to dashboard and SDK uploads alike.
Audit + observability. SQLite-backed audit log with CSV export, Prometheus /metrics, and a starter Grafana dashboard.
Kubernetes-native (optional). A BucketClaim CRD provisions a bucket and writes credentials into the requesting namespace; an S3Backend CRD declares the upstream. Operator and dashboard ship from the same Helm chart.
Architecture
One Go binary: an embedded SvelteKit frontend, and pure-Go SQLite for users, sessions, shares, audit events, and credentials. Secrets are sealed with AES-256-GCM under a master key.
Stowage does not store object bytes — data lives on the upstream; Stowage proxies access to it.
Building from source
Requires Go 1.26+ and Bun.
make frontend # bun install + bun run build → web/dist/
make build # bin/stowage
make test
make docker # multi-stage distroless image
Tagged releases publish multi-arch binaries (downloads, GitHub Releases) and container images on ghcr.io/stowage-dev/stowage — cosign-signed, with SBOMs and SLSA provenance. Verification recipes.
Deploying
Stowage speaks plaintext HTTP and expects TLS from a reverse proxy — see Reverse proxy for nginx, Caddy, and Traefik examples, and the hardening checklist before production.
Security
Report vulnerabilities privately via GitHub Security Advisories — never public issues. Policy and SLAs in SECURITY.md; the security model maps every defence to the source that implements it.
Contributing
PRs welcome. Sign off your commits (git commit -s) under the DCO — no CLA. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.
License
AGPL-3.0-or-later. Run unmodified Stowage anywhere — company, homelab, SaaS — with no publication obligation. Modify it and expose those changes to users over a network, and you must publish them under the same license. (Why AGPL)
Maintainer
Built by Damian van der Merwe, an infrastructure & DevOps engineer in Hamilton, New Zealand.
Directories
¶
| Path | Synopsis |
|---|---|
|
stowage performance benchmark.
|
stowage performance benchmark. |
|
check
command
Regression gate for the stowage benchmark.
|
Regression gate for the stowage benchmark. |
|
miniobench
command
MinIO-direct comparison benchmark.
|
MinIO-direct comparison benchmark. |
|
s3proxybench
command
Comprehensive benchmark for stowage's embedded S3 SigV4 proxy.
|
Comprehensive benchmark for stowage's embedded S3 SigV4 proxy. |
|
cmd
|
|
|
stowage
command
|
|
|
internal
|
|
|
audit
Package audit records who did what.
|
Package audit records who did what. |
|
auth/oidc
Package oidc implements the OIDC authorization-code + PKCE flow for stowage.
|
Package oidc implements the OIDC authorization-code + PKCE flow for stowage. |
|
backend
Package backend defines the single abstraction through which all S3 access flows — this is the most important file in the project.
|
Package backend defines the single abstraction through which all S3 access flows — this is the most important file in the project. |
|
backend/memory
Package memory is an in-process Backend implementation for tests.
|
Package memory is an in-process Backend implementation for tests. |
|
backend/s3v4
Package s3v4 is the generic AWS SDK v2 driver.
|
Package s3v4 is the generic AWS SDK v2 driver. |
|
metrics
Package metrics is the in-process request counter used by the admin dashboard.
|
Package metrics is the in-process request counter used by the admin dashboard. |
|
operator/api/v1alpha1
Package v1alpha1 contains API Schema definitions for the broker v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the broker v1alpha1 API group. |
|
operator/backend
Package backend wraps the outbound S3 client used by the operator and the proxy.
|
Package backend wraps the outbound S3 client used by the operator and the proxy. |
|
operator/controller
Package controller holds the reconcilers for the operator CRDs.
|
Package controller holds the reconcilers for the operator CRDs. |
|
operator/credentials
Package credentials resolves and generates credentials for both the admin (backend-facing) and virtual (tenant-facing) paths.
|
Package credentials resolves and generates credentials for both the admin (backend-facing) and virtual (tenant-facing) paths. |
|
operator/manager
Package manager assembles the controller-runtime manager that runs the stowage operator's reconcilers and admission webhooks.
|
Package manager assembles the controller-runtime manager that runs the stowage operator's reconcilers and admission webhooks. |
|
operator/vcstore
Package vcstore manages the two Secrets produced for every BucketClaim:
|
Package vcstore manages the two Secrets produced for every BucketClaim: |
|
operator/webhook
Package webhook holds the admission validators for the operator CRDs.
|
Package webhook holds the admission validators for the operator CRDs. |
|
proxyurl
Package proxyurl resolves the URL clients use to reach the S3 proxy.
|
Package proxyurl resolves the URL clients use to reach the S3 proxy. |
|
quickstart
Package quickstart bootstraps a self-contained stowage instance: it downloads a matching MinIO release, starts it as a child process with random credentials, then runs the stowage dashboard pointed at it.
|
Package quickstart bootstraps a self-contained stowage instance: it downloads a matching MinIO release, starts it as a child process with random credentials, then runs the stowage dashboard pointed at it. |
|
quotas
Package quotas implements proxy-enforced per-bucket storage quotas.
|
Package quotas implements proxy-enforced per-bucket storage quotas. |
|
s3proxy
Package s3proxy implements the embedded S3 SigV4 data-plane proxy that runs on a separate listener from the dashboard.
|
Package s3proxy implements the embedded S3 SigV4 data-plane proxy that runs on a separate listener from the dashboard. |
|
secrets
Package secrets seals/opens at-rest secrets (e.g.
|
Package secrets seals/opens at-rest secrets (e.g. |
|
shares
Package shares implements the proxy-layer sharing feature (spec §5 Phase 5).
|
Package shares implements the proxy-layer sharing feature (spec §5 Phase 5). |
|
sigv4verifier
Package sigv4verifier verifies AWS SigV4 signatures on inbound HTTP requests.
|
Package sigv4verifier verifies AWS SigV4 signatures on inbound HTTP requests. |
|
sizes
Package sizes computes and caches per-bucket and per-prefix recursive byte totals.
|
Package sizes computes and caches per-bucket and per-prefix recursive byte totals. |
|
store
Package store defines the persistence interface used for sessions, users, audit events, share links, and preferences.
|
Package store defines the persistence interface used for sessions, users, audit events, share links, and preferences. |
|
store/sqlite
Package sqlite implements the default stowage persistence backend using modernc.org/sqlite (CGo-free, keeps the single-binary promise).
|
Package sqlite implements the default stowage persistence backend using modernc.org/sqlite (CGo-free, keeps the single-binary promise). |
|
test
|
|
|
chart
Package chart holds offline tests for the deploy/chart/ Helm chart.
|
Package chart holds offline tests for the deploy/chart/ Helm chart. |
|
Package web ships the SvelteKit static build embedded in the Go binary.
|
Package web ships the SvelteKit static build embedded in the Go binary. |