Upgrades

Witness is pre-1.0. Pin a reviewed commit or release, read its changes, and upgrade deliberately. The gateway's SQL migrations are compiled into the binary and run automatically at startup; they are forward-only.

Procedure

1. Review the new binary, configuration changes, and release notes.
2. Create and test a compatible SQLite backup and save the matching configuration.
3. Build the gateway from the reviewed source:

cargo build --release -p witness-gateway

1. Exercise the new binary against a copy of the database before production.
2. Stop the existing gateway, install the reviewed binary, and start it once.
3. Inspect migration and witness-health logs, then verify /health through the TLS-terminating proxy.
4. Confirm that threshold collection, database writes, metrics, and intended authentication controls behave as expected.

Do not run multiple gateway processes against one SQLite file. Graceful shutdown allows in-flight requests to complete subject to the service manager's stop timeout, but operators should still use a controlled window.

Rollback boundary

There are no down migrations. To roll back, stop the gateway, restore a compatible pre-upgrade database backup, deploy the previously reviewed binary and matching configuration, then verify health and witness connectivity.

Changing witness keys changes the network verification configuration. Coordinate the new public keys and restart the gateway; clients must review or pin the resulting configuration. The project does not define a universal key-revoke mechanism.