stowage
Get started
Documentation

Install from source

Use this when you're contributing, debugging an issue against a specific commit, or running on an architecture without published binaries.

#Prerequisites

  • Go 1.26 or newer.
  • Bun (only needed if you want to rebuild the embedded SvelteKit frontend).
  • A C toolchain is not required — Stowage uses the pure-Go modernc.org/sqlite driver.

#Clone

git clone https://github.com/stowage-dev/stowage.git
cd stowage

#Build the frontend (optional)

The Go build embeds web/dist/ via //go:embed all:dist. If you want the dashboard, build the bundle first:

cd web
bun install
bun run build
cd ..

If you only need a backend-only binary for local testing, scaffold a stub instead:

mkdir -p web/dist
[ -f web/dist/index.html ] || echo '<!doctype html><title>stowage</title>' > web/dist/index.html

This is what CI does when running Go-only jobs.

#Build the binary

make build
# → bin/stowage

For the operator binary as well:

make build-all
# → bin/stowage and bin/stowage-operator

#Test and lint

make test         # go test ./...
make vet          # go vet ./...
make lint         # vet + staticcheck

CI runs go test -race. Don't introduce data races, even in helpers.

#Run

./bin/stowage create-admin \
  --config config.example.yaml \
  --username admin \
  --password 'S3cur3-P@ssw0rd!'

./bin/stowage serve --config config.example.yaml

#Cross-compiling

Go's standard GOOS/GOARCH env vars work:

GOOS=linux   GOARCH=arm64 go build -trimpath -o bin/stowage-linux-arm64   ./cmd/stowage
GOOS=darwin  GOARCH=arm64 go build -trimpath -o bin/stowage-darwin-arm64  ./cmd/stowage
GOOS=windows GOARCH=amd64 go build -trimpath -o bin/stowage-windows.exe   ./cmd/stowage

The release pipeline does the same with goreleaser. See Makefile for the canonical recipe.