stowage
Get started
Documentation

Repo layout

Where things live in the Stowage repository. Source of truth: CLAUDE.md.

cmd/stowage/                CLI entrypoint for the dashboard + S3 proxy:
                            serve | quickstart | create-admin | hash-password
cmd/operator/               CLI entrypoint for the optional Kubernetes operator
internal/api/               chi router + HTTP handlers
internal/auth/              sessions, CSRF, rate limit, password hashing,
                            proxy-trust gate, oidc/
internal/backend/           Backend interface (backend.go) + drivers: s3v4/,
                            memory/. ProxyTarget escape hatch feeds the proxy.
internal/audit/             audit recorder (sync sqlite + async wrapper)
internal/config/            YAML + env loader (config.go)
internal/metrics/           Prometheus + per-request middleware
internal/quotas/            proxy-enforced soft/hard quota scanner +
                            LimitSource interface (SQLite + K8s + merged)
internal/secrets/           AES-256-GCM sealing for endpoint credentials
                            and S3 virtual credentials
internal/shares/            share resolver (public /s/:code surface,
                            argon2id passwords)
internal/server/            http.Server lifecycle, backend bootstrap,
                            second listener for the S3 proxy
internal/sigv4verifier/     AWS SigV4 signature verification (stdlib-only)
internal/s3proxy/           embedded S3 SigV4 proxy: server + sources
                            (SQLite + Kubernetes informer + merged) + admin
                            CRUD types
internal/store/             Store interface + sqlite/ implementation
                            (append-only migrations)
internal/operator/          operator-only Kubernetes code:
                            api/v1alpha1/  CRDs (S3Backend, BucketClaim)
                            controller/    reconcilers
                            credentials/   admin Secret resolver, VC generator
                            vcstore/       Secret writer (operator side)
                            webhook/       admission validators
                            backend/       k8s-side bucket lifecycle
internal/quickstart/        bundled MinIO downloader for one-command demo
web/                        SvelteKit + Svelte 5 (runes) + Tailwind v4;
                            built to web/dist/, embedded via web/embed.go
deploy/                     Dockerfile (multi-stage), compose, k8s, grafana
deploy/chart/               operator + dashboard Helm chart, CRDs, RBAC
docs/                       this docs site
benchmarks/                 perf harness (CI: .github/workflows/benchmark.yml)

#Key files

  • internal/backend/backend.go — the Backend interface. The most load-bearing file in the repo. See Architecture overview.
  • internal/operator/vcstore/labels.go ⇄ internal/s3proxy/source_kubernetes.go — the wire contract on Kubernetes Secret data fields. Both must agree. See Reference → Secret data fields.
  • internal/store/sqlite/migrations.go — append-only migration list. Never edit a past migration.
  • internal/config/config.go — single source of truth for every config key, default, and validation rule.

#Test files

Tests sit next to the code (*_test.go in the same package). The Go suite runs with -race in CI.

The frontend has its own tests:

cd web && bun run check     # svelte-check
cd web && bun run lint      # prettier + eslint

#Generated files

  • internal/operator/api/v1alpha1/zz_generated.deepcopy.go — generated by controller-gen. Don't edit by hand.
  • deploy/chart/crds/*.yaml — generated from the kubebuilder annotations on the v1alpha1 types.
  • web/dist/ — generated by bun run build.

#Local-only directories

  • .audit/ and private/ — gitignored scratch space. Don't commit.
  • stowage-demo.db* — local dev artefacts. Gitignored.
  • bin/ — make output. Gitignored.