How to develop stromboli
You need Go (the version in go.mod) and Docker. For proto changes, buf; for query or migration changes, sqlc. Read CONTRIBUTING.md before opening a pull request.
Run from source against the demo stack
docker compose -f docker-compose.dev.yml up -d # Postgres :55432, Loki :3100, demo app
export STROMBOLI_DB_URL="postgres://stromboli:stromboli@localhost:55432/stromboli?sslmode=disable" STROMBOLI_SECRET_KEY=dev
go run ./cmd/stromboli serve
In another terminal, load the example catalog:
go run ./cmd/stromboli connector add loki loki url=http://localhost:3100
go run ./cmd/stromboli catalog import examples/catalog/services.yaml --runbooks examples/catalog/runbooks
go run ./cmd/stromboli brief api
The demo app breaks db-proxy after DEMO_INCIDENT_AFTER (default 3m). To see a full investigation, set an LLM key on the server and run go run ./cmd/stromboli investigate api. Tutorial 1 walks through it.
Run the checks CI runs
gofmt -l . # must print nothing
go vet ./...
go test ./...
buf lint # if you changed proto/
Tests that need Postgres (including the end-to-end agent test) are skipped unless STROMBOLI_TEST_DB_URL is set:
STROMBOLI_TEST_DB_URL="postgres://stromboli:stromboli@localhost:55432/stromboli?sslmode=disable" go test ./...
Regenerate code
Generated code is committed. Regenerate it in the same change as its source:
| You changed | Run | Output |
|---|---|---|
proto/stromboli/v1/*.proto |
buf lint && buf generate |
gen/stromboli/v1 |
internal/store/queries/*.sql or internal/store/migrations/*.sql |
sqlc generate |
internal/store/db |
| the MCP tool definitions | go test ./internal/mcpserver -update if the golden test fails on purpose |
internal/mcpserver/testdata/tools.golden.json |
The API must stay backwards compatible (buf breaking runs on pull requests), and migrations only move forward: add a new numbered file under internal/store/migrations rather than editing one.
Add a setting
Read it in internal/config/config.go, then document it in .env.example, in the configuration reference, and in the Railway declaration .railway/railway.go.
Record a design decision
Bigger changes start as an ADR: copy docs/adr/template.md to the next number, open it as Proposed in a pull request, and add it to the index.
Find your way around
Architecture maps each package to its job.