Updating

HeadDB has separate systems for remote database updates and plugin JAR updates.

Database updates

The public head database can update without replacing the plugin JAR.

By default, HeadDB:

1. Loads the last verified cache during startup.
2. Checks the remote manifest during startup.
3. Repeats the remote check every six hours.
4. Downloads and activates artifacts only when catalog or revocation descriptors changed.

Configuration:

refresh:
  load-cache-on-startup: true
  refresh-on-startup: true
  scheduled:
    enabled: true
    interval-hours: 6

Manual commands:

/hdb status
/hdb verify
/hdb refresh

/hdb verify validates remote data without replacing the active database. /hdb refresh checks and activates the newest database.

A database loaded from CACHE is not inherently outdated. It means the active snapshot came from verified local artifacts; the startup or scheduled remote check can still confirm that those artifacts are current.

Plugin update checking

update-checker:
  enabled: true
  check-on-startup: true
  notify-console: true
  notify-admins: true
  include-prereleases: true
  include-builds: false

Use /hdb version to inspect update status or /hdb update to perform an immediate check and download an allowed release.

Automatic JAR installation

auto-updater:
  install-updates: false

When enabled, HeadDB replaces the active JAR when the platform permits it or stages HeadDB.jar in the server update directory. Windows file locking commonly requires the staged update path.

The server is never restarted automatically. Restart it to load the downloaded version.

Manual upgrade procedure

1. Back up plugins/HeadDB/, especially storage/headdb.db.
2. Stop the server.
3. Remove old duplicate HeadDB JARs.
4. Install the new JAR.
5. Apply any release-specific configuration migration instructions.
6. Start the server.
7. Run /hdb version, /hdb status, and /hdb verify.

When a release changes the GUI schema substantially, back up and delete the old gui.yml so the current file can be generated.