Operations

Operations

This page covers day-to-day Trove operations.

Health checks

Server health:

curl http://SERVER:8080/healthz

Agents:

curl http://SERVER:8080/api/v1/agents

Services:

curl http://SERVER:8080/api/v1/services

Events:

curl http://SERVER:8080/api/v1/events

When OIDC is enabled, /api/v1/agents, /api/v1/services, /api/v1/events, and /metrics require a browser session or TROVE_API_TOKEN. /healthz intentionally remains open. See Authentication#programmatic-read-api-access.

Logs

Docker Compose server:

docker compose logs -f server

Docker agent:

docker logs -f trove-agent-docker

Systemd server:

journalctl -u trove-server -f

Systemd local agent:

journalctl -u trove-agent-local -f

Kubernetes agent:

kubectl logs -f deploy/trove-agent -n trove

Creating agents

Create one token per agent:

trove-server agent create AGENT_NAME

Compose:

docker compose exec server trove-server agent create AGENT_NAME

Save the token immediately. It cannot be recovered later because Trove stores only the hash.

List or remove agents with:

trove-server agent list
trove-server agent delete AGENT_NAME

Deleting an agent removes its catalogue data from Trove. It does not stop or modify anything on the monitored platform.

Backups

Back up the SQLite database.

Use the built-in online backup command:

# systemd
sudo TROVE_DB=/var/lib/trove/trove.db \
  trove-server backup "/var/backups/trove-$(date +%F).db"

# Docker Compose
mkdir -p backups
docker compose exec server \
  trove-server backup "/data/trove-$(date +%F).db"
docker compose cp "server:/data/trove-$(date +%F).db" backups/

The destination must not already exist. Trove uses SQLite's online backup path, so the server can keep running. A stopped-server copy or consistent filesystem snapshot is also valid. Avoid copying a busy SQLite file and hoping for the best. SQLite has enough personality without inviting it to improvise.

Restore

To restore:

1. stop trove-server
2. replace the database file with the backup
3. ensure ownership/permissions match the service user
4. start trove-server
5. check /healthz
6. check /api/v1/agents

Agents will resume pushing with their existing tokens if the restored database contains their token hashes.

Retention

Event retention:

TROVE_EVENT_RETENTION=720h

Removed-service retention:

TROVE_REMOVED_RETENTION=24h

Shorter retention keeps the database smaller. Longer retention gives richer history and digest context.

Alert testing

After changing alert variables:

trove-server alert test

Compose:

docker compose exec server trove-server alert test

Confirm the message actually arrived. An ok from a webhook only means the receiving endpoint accepted the request.

Registry credentials

Private registry credentials go on the server, not the agents:

TROVE_REGISTRY_AUTHS={"ghcr.io":{"username":"techdox","password":"..."}}

Restart the server after changing them.

Keeping the dashboard private

The dashboard and read APIs are open by default. Use one of:

• LAN-only binding
• VPN-only access
• reverse proxy with auth
• native OIDC
• Cloudflare Access or similar front door
• firewall rules

Do not put the unauthenticated dashboard directly on the open internet. Native OIDC setup is covered in Authentication.