Local Development

Prerequisites

Tool	Minimum version	Install
Go	1.22	go.dev/dl
pnpm	9	`npm i -g pnpm`
Docker + Docker Compose	Latest stable	docker.com
task	3	taskfile.dev
buf	1.30	buf.build/docs/installation

Dependency Tiers

Choose the tier that matches the work you are doing. The same bitvaultd binary runs in all tiers — only the external dependencies differ.

Tier	Stack	When to use
lite	Postgres + MinIO	Core file/storage work: upload, download, commit protocol, versioning
standard	+ Redis + NATS JetStream	Sync, notifications, session caching, rate limiting
full	+ OpenSearch	Content search, full async-plane development

task up:lite       # Postgres + MinIO only
task up:standard   # + Redis + NATS
task up:full       # + OpenSearch

All tiers use docker-compose.{lite,standard,full}.yml in deploy/compose/. Data is stored in named Docker volumes; task down stops containers without deleting data, task clean removes volumes.

:::tip Minimal setup task up:lite gets you Postgres + MinIO + bitvaultd. This is sufficient for the entire upload/download/commit flow without Redis, NATS, or OpenSearch. Most backend contributors can start here. :::

Common Commands

Command	Description
`task gen`	Regenerate Go, TypeScript, and OpenAPI from `proto/`
`task up:lite`	Start lite dependency stack (Postgres + MinIO)
`task up:standard`	Start standard dependency stack (+ Redis + NATS)
`task up:full`	Start full dependency stack (+ OpenSearch)
`task down`	Stop all containers
`task build`	Build all Go binaries
`task test`	Unit + integration tests (real Postgres + MinIO)
`task test:e2e`	Black-box E2E tests against a running stack
`task test:chaos`	Fault-injection tests (dual-write, conflict harness)
`task lint`	Run Go linter + import-boundary checker + buf lint
`helm install bitvault deploy/helm/bitvault -f values.full.yaml`	Kubernetes path

Running bitvaultd Locally

bitvaultd is configured via environment variables (12-factor). Minimal set for the lite tier:

go run ./cmd/bitvaultd \
  BITVAULT_DB_DSN="postgres://bitvault:bitvault@localhost:5432/bitvault" \
  BITVAULT_STORAGE_PROVIDER=minio \
  BITVAULT_STORAGE_ENDPOINT=http://localhost:9000 \
  BITVAULT_STORAGE_ACCESS_KEY=minioadmin \
  BITVAULT_STORAGE_SECRET_KEY=minioadmin \
  BITVAULT_STORAGE_BUCKET=bitvault \
  BITVAULT_AUTH_ISSUER=http://localhost:4444 \
  BITVAULT_OTEL_EXPORTER=stdout

task up:lite prints the exact environment block for the running containers.

Running the Web App

The Next.js app consumes the REST API generated from gen/openapi/bitvault.yaml.

cd apps/web
pnpm install
pnpm dev          # starts on http://localhost:3000

Set NEXT_PUBLIC_API_URL=http://localhost:8080 (or the gateway port) in apps/web/.env.local. The dev server proxies /v1/ requests to the local bitvaultd instance.

Proto Changes

When you modify a .proto file:

Edit proto/bitvault/<context>/v1/<file>.proto.
Run task gen to regenerate gen/go/, gen/ts/, and gen/openapi/.
Commit the changed gen/ files in the same PR as the .proto change.

buf lint and buf breaking run in CI. A breaking change to an existing field (removal, renumber, type change) fails the pipeline. Additive changes (new optional fields, new RPCs) pass.