Upgrade Guide

Upgrade Guide

Trove is designed to be simple to upgrade, but the database and agent tokens matter. Schema migrations only move forward, so a verified backup is your rollback path.

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.
5. For production-style installs, pin the target version instead of relying on latest.

Server and agents tolerate version skew within a minor release. You do not need to restart every agent at the same instant.

Back up first

# 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/

Keep the backup outside the container volume you are upgrading.

Docker Compose upgrade

If you pin versions, update each Trove image tag in the Compose file first, for example ghcr.io/techdox/trove-server:0.13.0.

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

Download and unpack the target release archive, then replace the binary and restart:

VERSION=0.13.0
curl -fLO "https://github.com/techdox/trove/releases/download/v${VERSION}/trove-server_${VERSION}_linux_amd64.tar.gz"
tar xzf "trove-server_${VERSION}_linux_amd64.tar.gz"
sudo install -m 0755 trove-server /usr/local/bin/trove-server
sudo systemctl restart 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.

Upgrade the server first, then agents when convenient. The server owns migrations and background workers, while agents repopulate current catalogue state on their normal push interval.

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

Do not point an older binary at a database that a newer migration has already changed unless the release notes explicitly confirm compatibility. Restore the pre-upgrade backup when in doubt.

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.