Setup Guide

This guide walks through a complete Zander deployment from scratch — database, web platform, Discord bot, and Minecraft plugins. Follow the steps in order; each step builds on the previous one.

Prerequisites

Requirement	Version
Node.js	20.x or later
npm	8.5.0 or later
MySQL	8.x or later
Minecraft server	Paper/Spigot 1.19+ (for game server plugins), Velocity (for proxy)

---

1. Set Up the Database

1. Create a new MySQL database:

   CREATE DATABASE zander CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. Run the initialisation script to create the base schema:

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

3. Run all migration scripts in order from the migration/ directory:

   # Run each file in numeric order, e.g.:
   mysql -u <user> -p zander < migration/001_initial.sql
   mysql -u <user> -p zander < migration/002_....sql
   # ...

4. (Optional) If you are using LuckPerms, configure a separate read connection in .env under LUCKPERMS_URL.

5. (Optional) If you are using QuickShop for the shop directory, configure QUICKSHOP_URL in .env.

---

2. Configure the Web Platform

1. Copy the example files:

   cp .env.example .env
   cp config.json.example config.json

2. Edit .env and set at minimum:

   Variable	Value
   siteAddress	Your public URL, e.g. https://example.com
   sessionCookieSecret	A random string of 32+ characters
   DATABASE_URL	MySQL connection string
   apiKey	Your chosen API key (shared with all plugins)
   discordAPIKey	Your Discord bot token
   discordClientId	Your Discord application client ID
   discordClientSecret	Your Discord application client secret

3. Edit config.json and fill in:

   • siteConfiguration.siteUrl and siteName
   • discord.guildId
   • Discord webhook URLs under discord.webhooks
   • Discord channel and role IDs as required

4. Review features.json and disable any features you do not need.

---

3. Set Up the Discord Bot

1. In the Discord Developer Portal:

   • Create a new application.
   • Under Bot, enable Message Content Intent, Server Members Intent, and Presence Intent.
   • Copy the bot token into discordAPIKey in .env.
   • Under OAuth2, copy the client ID and secret into discordClientId and discordClientSecret.

2. Invite the bot to your guild with the required permissions (at minimum: Manage Roles, Manage Channels, Moderate Members, Ban Members, Send Messages, Embed Links).

3. Set discord.guildId in config.json to your server's ID.

---

4. Install and Start zander-web

npm install
npm run build    # runs migrations and generates Prisma client
npm run dev      # development mode (auto-reload)
# OR
npm run prod     # production mode

The application starts on the port defined by PORT in .env (default 8080).

tip

In production, run the app behind a reverse proxy (nginx, Caddy) with HTTPS. See Deployment.

---

5. Install Minecraft Plugins

Place the plugin JARs in the appropriate plugins/ directories:

Plugin JAR	Server type
zander-addon.jar	Each Paper/Spigot game server
zander-auth.jar	Dedicated auth Paper/Spigot server
zander-hub.jar	Hub Paper/Spigot server (+ PremiumVanish + ProtocolLib)
zander-velocity.jar	Velocity proxy

Start each server once to generate the default config.yml, then stop it and update:

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

The APIKey must exactly match apiKey in .env.

---

6. Verify the Connection

1. Start zander-web and confirm it is accessible at your configured siteAddress.
2. Start your Minecraft server(s) with the plugins installed.
3. Log in to Minecraft — the plugin should successfully call the session API.
4. Check the audit logs in the dashboard (/dashboard/logs) to confirm API calls are being received.