README
¶
stowage
⚠️ Warning: This repository contains AI-generated content that has not yet gone through review. This warning will be removed once all content has been reviewed.
Official site: stowage.dev · Documentation: stowage.dev/docs · Downloads: stowage.dev/download
A single Go binary that puts a modern web dashboard, an embedded AWS-SigV4 S3 proxy, and an optional Kubernetes operator in front of any S3-compatible backend — MinIO, Garage, SeaweedFS, AWS S3, Cloudflare R2, Backblaze B2, Wasabi. One pane of glass for the storage you already run, with audit, quotas, share links, and per-tenant SDK credentials, without locking you to a vendor.
AGPL-3.0-or-later. No community edition, no enterprise tier — see Why AGPL and No community edition for the rationale.
Quickstart
Three paths. Pick the one that matches where you want Stowage to live. Each path is documented end-to-end at stowage.dev/docs/getting-started.
One-liner (Linux, macOS, WSL)
curl -fsSL https://stowage.dev/install.sh | sh
Windows (PowerShell)
irm https://stowage.dev/install.ps1 | iex
The installer downloads a SHA256-verified release binary into the
current directory and execs stowage quickstart, which spawns a managed
MinIO, creates a SQLite DB, prints a random admin password, and opens
the dashboard on http://localhost:8080. Nothing is installed
system-wide. Checksums and signatures for every release are published at
stowage.dev/releases.
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!'
Full walkthroughs: one-liner · Docker Compose · Kubernetes.
What ships in v1.0
A complete feature matrix lives at stowage.dev/features; the summary below mirrors it.
Dashboard. OIDC, local accounts with argon2id hashing, or a static admin from env. Object browser with multi-select, drag-and-drop multipart upload (16 MiB parts, pause/resume), preview (text / image / PDF / video), version history, tags + metadata, single-object rename, cross-bucket / cross-prefix move and copy, and streamed download-as-zip.
Public sharing. Share links with argon2id passwords, expiry presets,
atomic download caps (UPDATE … WHERE used < cap — no race), and
per-IP rate limiting. No presigned-URL plumbing.
Per-tenant SDK access. A second listener (default :8090) accepts
AWS SigV4 requests with per-tenant virtual credentials, verifies the
signature, enforces bucket scope, and re-signs to the upstream with the
backend's admin credentials. Standard AWS SDKs work unmodified:
AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... \
aws --endpoint-url http://stowage:8090 \
s3 cp ./hello.txt s3://uploads/hello.txt
ListBuckets is synthesised per-credential — tenants only see what they
were granted.
Multi-backend workflows. Cross-backend object copy streams through the proxy host. Per-user pinned buckets across backends. Unified search fans out across every configured endpoint with per-backend cancellation.
Quotas. Soft and hard caps per bucket, scheduled scanner, 507 Insufficient Storage on hard-cap, in-browser warning banner at the
soft cap. Quotas apply equally to dashboard uploads and SDK uploads.
Audit + observability. SQLite-backed audit log with per-event detail
JSON, CSV export, and a filtered list at /admin/audit. Prometheus
/metrics with bounded label cardinality, plus a starter Grafana
dashboard at
deploy/grafana/stowage.json.
Kubernetes-native (optional). A BucketClaim CRD provisions a
bucket on the upstream and writes an aws-sdk-shaped Secret into the
requesting namespace. An S3Backend CRD declares the upstream. The
operator and the dashboard ship from the same Helm chart.
Architecture
One Go binary. SvelteKit frontend embedded via //go:embed. SQLite
(pure-Go, no CGo) holds users, sessions, shares, audit events, sealed
backend secrets, and virtual credentials. Endpoint secrets and tenant
secret keys are sealed with AES-256-GCM under a master key from
STOWAGE_SECRET_KEY (or an auto-generated stowage.key file, mode
0600).
The runtime needs nothing except the binary — no Redis, no NATS, no external auth service, no separate frontend container. The build needs Go and Bun. See Why one binary for the tradeoffs (single-replica, SQLite-only, no hot config reload — all deliberate). The architecture overview, including diagrams, is at stowage.dev/docs/explanations/architecture.
Stowage does not store object bytes. Data lives on the upstream; Stowage proxies access to it.
Documentation
The canonical, versioned documentation is at
stowage.dev/docs. The sources also live
in ./docs/ in this repo for offline reading. Both follow
Diátaxis:
| Section | When to read |
|---|---|
| Getting started → | "I'm new — teach me by doing." |
| Self-host → | "I want this on a single host. Show me the recipes." |
| Run on Kubernetes → | Helm chart, operator, CRDs, virtual credentials. |
| Use as an S3 endpoint → | For tenant developers pointing AWS SDKs at the proxy. |
| Reference → | Every CLI flag, config key, API endpoint, CRD field, metric. |
| Explanations → | Architecture, threat model, design tradeoffs. |
| Security → | Threat model, hardening checklist, vulnerability reporting. |
| Comparisons → | Stowage vs MinIO Console, Cyberduck, raw S3 + presigned URLs. |
Building from source
Requires Go 1.26+ and Bun for the frontend.
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 (linux/amd64, linux/arm64,
darwin/amd64, darwin/arm64, windows/amd64) binaries — listed on
stowage.dev/download and mirrored to
GitHub Releases — and
multi-arch (linux/amd64, linux/arm64) container images on
ghcr.io/stowage-dev/stowage. Images are signed with cosign (keyless),
ship with SBOMs, and carry SLSA provenance attestations. Verification
recipes are at
stowage.dev/docs/security/verify-releases.
Deploying
Stowage listens on plaintext HTTP and expects TLS to be terminated by a
reverse proxy. See
Self-host → Reverse proxy
for the required headers, the server.trusted_proxies config, and
worked examples for nginx, Caddy, and Traefik. The
hardening checklist
is the pre-production gate.
Security
Report vulnerabilities privately via
GitHub Security Advisories
or by following the disclosure process at
stowage.dev/security. Do not open
public issues for security reports. The full policy, response SLAs, and
safe-harbour terms are in SECURITY.md and
stowage.dev/docs/security/report-vulnerability.
For operators, the security model summarises every defence (authentication, authorization, sigv4 proxy, sharing, secret handling, HTTP, audit) and links each to the source file that implements it.
Community
- Website: stowage.dev
- Blog & release notes: stowage.dev/blog
- Source: github.com/stowage-dev/stowage
- Discussions: github.com/stowage-dev/stowage/discussions
- Issues: github.com/stowage-dev/stowage/issues
Contributing
PRs welcome. All commits must be signed off (git commit -s) under the
Developer Certificate of Origin —
the DCO check in CI will tell you if you forget. There is no CLA. See
CONTRIBUTING.md and
stowage.dev/docs/contributing
for the workflow, and CODE_OF_CONDUCT.md for
community standards.
License
AGPL-3.0-or-later. Running unmodified Stowage — including inside a company, inside a homelab, or as part of a SaaS — imposes no publication obligation. If you modify Stowage and expose those modifications to other users over a network, you must publish your changes under the same license. The rationale is in Why AGPL.
Maintainer
Built and maintained by Damian van der Merwe, an infrastructure & DevOps engineer based in Hamilton, New Zealand. Project home: stowage.dev.
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. |