Server

Server

trove-server is the central process. It accepts agent reports, stores the catalog, serves the dashboard, exposes read-only APIs, and runs the background workers.

Source areas:

• cmd/trove-server/main.go
• internal/server
• internal/store
• internal/alert
• internal/registry
• web

HTTP routes

The server registers these routes:

Method	Path	Auth	Purpose
POST	/api/v1/report	Agent bearer token	Ingest one full-state report from an agent.
GET	/api/v1/services	OIDC session or optional API token	List catalog services for the dashboard/API.
GET	/api/v1/agents	OIDC session or optional API token	List agents and last-seen status.
GET	/api/v1/events	OIDC session or optional API token	List recent activity events.
GET	/api/v1/me	OIDC session or optional API token	Return current dashboard/API auth state.
GET	/metrics	OIDC session or optional API token	Prometheus text metrics.
GET	/healthz	none	Basic health endpoint.
GET	/oauth2/login	none	Start OIDC login.
GET	/oauth2/callback	none	Receive OIDC callback.
POST	/oauth2/logout	none	Clear Trove session and redirect to IdP logout when available.
GET	/	OIDC session when enabled	Embedded dashboard SPA.

The dashboard and read APIs are open unless OIDC is configured. Treat them as private: bind them to a trusted network, put them behind an authenticating reverse proxy, or enable native OIDC. See Authentication.

Report ingest

Report ingest happens in internal/server/ingest.go.

The handler:

1. caps request bodies at 8 MiB
2. decodes JSON into model.Report
3. validates the report contract
4. calls store.ApplyReport
5. returns { "ok": true, "services": N }

Invalid JSON or invalid model data returns 400. Invalid/missing token returns 401. Store failures return 500.

Agent authentication

Agent authentication uses bearer tokens.

Authorization: Bearer trove_...

Tokens are created with:

trove-server agent create AGENT_NAME

The plaintext token is shown once. Trove stores a SHA-256 hash in SQLite, not the token itself.

At request time, the presented token is hashed and looked up. The matched hash is confirmed with constant-time comparison.

Dashboard/API authentication

Native OIDC is configured with TROVE_OIDC_ISSUER, TROVE_OIDC_CLIENT_ID, TROVE_OIDC_CLIENT_SECRET, and TROVE_OIDC_REDIRECT_URL.

When enabled, browser requests without a valid trove_session cookie are redirected through the IdP login flow. API clients can use TROVE_API_TOKEN as a bearer token for read APIs.

Logout is a POST to /oauth2/logout. Trove clears its local session cookie and redirects to the provider's discovered end_session_endpoint when present, including client_id and post_logout_redirect_uri.

See Authentication for setup and troubleshooting.

Bootstrap agent

Compose examples can seed a first agent with:

• TROVE_BOOTSTRAP_AGENT
• TROVE_BOOTSTRAP_TOKEN

This is useful for a first install where the server needs to accept an agent before the operator has run agent create interactively.

If an agent with that name already exists, bootstrap is idempotent and leaves the existing token alone.

Background workers

Staleness loop

The staleness loop evaluates agent heartbeat state from last_seen_at and report_interval_seconds.

General behaviour:

• never-seen agents are unknown
• normal recent agents are ok
• agents that miss enough pushes become stale
• agents that miss more become offline

When an agent changes heartbeat state, the server records an agent event.

When an agent is stale or worse, the server also marks that agent's services as health="stale". This avoids pretending services are healthy when the agent is no longer reporting.

Freshness loop

The freshness loop resolves latest image digests from registries and caches them in image_checks.

See Image-Freshness.

Maintenance loop

The maintenance loop prunes old history:

• old events, controlled by TROVE_EVENT_RETENTION
• old removed services, controlled by TROVE_REMOVED_RETENTION

This is deliberately not done on the report ingest write path.

Alert engine

The alert engine reads events and sends instant notifications through configured channels.

See Alerts-and-Digest.

Digest scheduler

The digest scheduler checks once per minute whether an email digest is due.

See Alerts-and-Digest.

Embedded dashboard

The dashboard is served from the embedded web filesystem.

There is no separate frontend build service required at runtime. The server binary includes the static assets.

Database location

The server uses TROVE_DB to find its SQLite database.

Common examples:

TROVE_DB=/data/trove.db
TROVE_DB=/var/lib/trove/trove.db

Back this file up. It contains the agent list, token hashes, service catalog, events, image check cache, and alert state.

Create a consistent online backup with:

TROVE_DB=/var/lib/trove/trove.db trove-server backup /path/to/trove-backup.db

The destination must not already exist. See Operations#backups for Compose and systemd examples.