Installation

Requirements

Requirement	Notes
Java 25 or newer	Required by the Paper/Folia plugin module.
Paper or Folia	HeadDB targets modern Paper-compatible servers and declares Folia support.
Network access	Required for the initial database download and later database or plugin update checks.
Vault and an economy provider	Optional; required only when economy support is enabled.

The public API and core modules target Java 21. Server owners running the plugin should use Java 25 or newer.

Download

Download HeadDB from an official release location. When a checksum is supplied, verify it before installation.

sha256sum -c HeadDB-<version>.jar.sha256

Install

1. Stop the server.
2. Place the HeadDB JAR in the server plugins directory.
3. Remove older duplicate HeadDB JARs.
4. Start the server.
5. Wait for HeadDB to generate files and load the database.
6. Review the console for configuration or connectivity errors.

Expected data folder:

plugins/HeadDB/
  config.yml
  gui.yml
  sounds.yml
  economy.yml
  messages/
    en-US.yml
  cache/
  storage/
    headdb.db

Confirm installation

Run:

/hdb version
/hdb status
/hdb verify

• /hdb version shows the running version, build information, and updater state.
• /hdb status shows database state and catalog counts.
• /hdb verify validates the remote database without replacing the active snapshot.

Upgrading

Replace the old JAR while the server is stopped and retain the HeadDB data folder unless release notes explicitly require regeneration of a configuration file.

Back up storage/headdb.db before upgrades. When a release substantially changes gui.yml, back up and remove the old file so HeadDB can generate the current layout.

Uninstalling

Remove the HeadDB JAR from plugins.

Remove plugins/HeadDB/ only when you intentionally want to delete configuration, Custom Heads, Custom Categories, favorites, drafts, overrides, player-head cache data, and all other local state.