Upgrade Guide

Upgrade Guide

Trove is designed to be simple to upgrade, but the database and agent tokens matter. Treat the SQLite database as the important state.

Before upgrading

1. Read the release notes.
2. Back up the SQLite database.
3. Check current server and agent versions.
4. Confirm you can roll back to the previous image/binary.

Docker Compose upgrade

Pull new images:

docker compose pull

Restart:

docker compose up -d

Check logs:

docker compose logs -f server

Verify:

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

Systemd binary upgrade

Stop the server:

sudo systemctl stop trove-server

Replace the binary:

sudo install -m 0755 trove-server /usr/local/bin/trove-server

Start:

sudo systemctl start trove-server
sudo systemctl status trove-server

Verify:

curl http://SERVER:8080/healthz

Database migrations

Migrations run automatically when the server opens the database.

That means the first start after upgrade may apply schema changes.

Back up before upgrading. Do not downgrade across migrations unless the release notes explicitly say it is safe.

Agent upgrade order

Usually upgrade the server first, then agents.

The report model is kept stable, but the server owns migrations and background workers, so it should be current before agents start sending any newer fields.

Rolling back

Rollback plan:

1. stop the upgraded server
2. restore the database backup if migrations were applied and downgrade compatibility is unknown
3. restore previous binary/image
4. start server
5. verify health and agents

Verify after upgrade

Check:

• dashboard loads
• /healthz returns OK
• /api/v1/agents shows current last-seen times
• /api/v1/services returns expected services
• alert test still works if alerts are configured
• image freshness still resolves if private registry creds are used

Common gotchas

The dashboard loads but no new data arrives

Check agent logs. The server may be reachable from your browser but not from the agent network.

Agents show stale after upgrade

Confirm agents are still running and still have the correct TROVE_SERVER_URL and TROVE_TOKEN.

Private image freshness stops working

Confirm TROVE_REGISTRY_AUTHS still reaches the server after the upgrade.