Development

Development

Trove is a Go project with a small embedded dashboard and multiple agent binaries.

Requirements: Go 1.26+, make, and Docker with Compose for the local stack.

Repository map

cmd/
  trove-server/
  trove-agent-docker/
  trove-agent-k8s/
  trove-agent-proxmox/
  trove-agent-local/
internal/
  agentkit/
  alert/
  registry/
  server/
  staleness/
  store/
pkg/model/
web/
deploy/
build/docker/
examples/

Build commands

make native
make build
make test
make vet
make fmt
docker compose up --build

Common meanings:

Command	Purpose
make native	Build all binaries for the current host.
make build	Cross-compile release-style Linux binaries.
make test	Run go test ./....
make vet	Run go vet ./....
make fmt	Run gofmt.
docker compose up --build	Run the source-built development server and Docker agent.

Version stamping

Binaries default to version dev.

Build and release flows override this with linker flags.

Do not hardcode release versions into source files. That causes drift between tags, binaries, and reported agent/server versions.

Wire model

pkg/model is the shared contract between agents and server.

Be careful when changing it:

• agents import it
• reports depend on it
• server validation depends on it
• backward compatibility matters

Store layer

All SQL should live under internal/store.

Schema changes should be migrations in:

internal/store/migrations

Do not hand-edit live SQLite schemas and then forget to encode the change as a migration.

Alert engine tests

Alert behaviour has important edge cases around cooldowns, reconnects, stale mass-updates, and freshness unknown states.

When changing alert logic, test:

• bad transition sends once
• repeated same bad value does not resend
• cooldown suppresses flaps correctly
• resolved only sends if the bad state was actually notified
• agent reconnect after stale service mass-update does not lose notified state
• freshness unknown blips do not erase known incidents

Dockerfiles

There are development Dockerfiles and release Dockerfiles.

Development files live at the repo root. Release files live under:

build/docker

If you change one, check the matching counterpart. Base image drift and user/permission drift are easy to miss.

CI runs a final-stage drift checker between development and release Dockerfiles, but update both sides intentionally rather than waiting for CI to explain the relationship at you.

Local development stack

The root docker-compose.yml is for development.

Use it when you want to build from source and run locally.

Release examples under examples/ use published images.

Frontend

The dashboard is a static app embedded into the server binary.

Keep it lightweight. The project does not need a heavy frontend build pipeline just to render an infrastructure catalog.

Before opening a PR

Run:

make fmt
make vet
make test
make build

The pull request also runs lint, race tests, vulnerability scanning, secret scanning, release checks, and conventional-title validation. Keep changes on a short-lived branch; main is protected.