Installation

Get Zander up and running in a few steps. This page covers prerequisites and the installation order - web platform first, then Minecraft plugins.

Prerequisites

Web Platform (zander-web)

Requirement	Minimum Version
Node.js	20.x or later
npm	8.5.0 or later
MySQL	8.x or later

Minecraft Plugins

Module	Minecraft Version	Platform	Plugin Dependencies
zander-addon	1.21+ (api-version)	Paper	None
zander-auth	1.19+ (api-version)	Paper	None
zander-hub	1.19+ (api-version)	Paper	PremiumVanish, ProtocolLib (hard depends - the server won't enable the plugin without both present)
zander-pgm	1.21+ (api-version)	Paper/Spigot (Mixed/PGM servers)	PGM (depend: PGM)
zander-velocity	-	Velocity proxy	signedvelocity
zander-waterfall	-	Waterfall/BungeeCord proxy	Votifier, AdvancedBan (soft dependencies)

note

zander-hub requires both PremiumVanish and ProtocolLib to be installed on the same Paper server.

note

The root Maven pom.xml's <modules> list currently only includes zander-velocity, zander-hub, zander-auth, and zander-addon. zander-pgm and zander-waterfall build independently as their own Maven modules. zander-bridge's source is not on master (which has only compiled output) - it lives on the unmerged branch codex/support-velocity-and-paper-in-bridge; check out that branch to build it. See the Overview page for details.

---

Step 1 - Set Up zander-web

1. Clone or download the zander-web repository.
2. Copy .env.example to .env and fill in all required values (see Configuration).
3. Copy config.json.example to config.json and configure your site settings.
4. Create a new MySQL database and run the initialisation script:

   mysql -u <user> -p <database> < dbinit.sql

5. Run database migrations in order from the migration/ folder.
6. Install dependencies and start the application:

   npm install
   npm run dev       # development
   npm run prod      # production

The API will be available at the siteAddress you configured (default http://localhost:8080).

---

Step 2 - Install Minecraft Plugins

Build each module with mvn package from the repo root (or from inside the module's own directory) and place the resulting JAR from target/ in the plugins/ folder of the appropriate server.

On each Paper game server

• zander-addon.jar - all game servers

On your auth server

• zander-auth.jar - servers requiring join-time verification

On your hub server

• zander-hub.jar
• PremiumVanish and ProtocolLib (required dependencies)

On your Mixed/PGM servers

• zander-pgm.jar (requires the PGM plugin already installed)

On your Velocity proxy

• zander-velocity.jar

On a Waterfall/BungeeCord proxy (if not using Velocity)

• zander-waterfall.jar

warning

zander-velocity's Heartbeat task polls zander-web every 60 seconds and disconnects every connected player if the check fails or zander-web is unreachable. This is a hard runtime dependency - make sure BaseAPIURL is correct and zander-web stays reachable from the proxy before going live. zander-waterfall behaves identically - confirmed by reading its Heartbeat.java: it polls {BaseAPIURL}/heartbeat every 60 seconds and disconnects all players ("API Heartbeat Failed, the server is temporarily offline.") whenever the response is unsuccessful or the request throws.

---

Step 3 - Configure the Plugins

Each plugin has a config.yml that is generated in plugins/<plugin-name>/ on first run. Most plugins (addon, auth, velocity, and waterfall - the last confirmed by reading its config.yml) use a BaseAPIURL/APIKey pair:

BaseAPIURL: "https://your-site.example.com/api"
APIKey: "your-api-key"

The APIKey must match the apiKey value in your .env file. Note that different plugins send this key differently: zander-addon's local API is unauthenticated, zander-auth/zander-velocity send it as an x-access-token header, and zander-pgm sends it as an Authorization: Bearer token (its config key is api.token, not APIKey) - see Configuration for per-plugin detail.

zander-hub does not call zander-web directly and has no BaseAPIURL/APIKey keys - its only cross-process communication is proxy plugin-messaging (server list/player count), not the web API.

See Configuration for all available options per plugin.