1. Getting started

Installation Guide

This comprehensive guide will walk you through setting up ServerPulse, including both the monitoring infrastructure (InfluxDB and Grafana) and the plugin for either Bukkit/Paper Minecraft servers or Velocity proxy.

Prerequisites

Before starting the installation, ensure you have:

Docker and Docker Compose installed on your machine
A Bukkit/Paper Minecraft server OR a Velocity proxy server
Java 21 or newer installed (required for the plugin)

Step 1: Setting Up the Infrastructure

Clone or Download ServerPulse

Download the latest release from GitHub or clone the repository
Navigate to the infra directory in the downloaded files

Start InfluxDB and Grafana

Open a terminal in the infra directory
Run the following command:
```
docker compose up -d
```
Wait a few moments for the containers to start

Step 2: Configuring InfluxDB

Initial InfluxDB Setup

Open http://localhost:8086 in your web browser
Complete the initial setup:
- Create a username and password
- Set organization name to my-org
- Create your first bucket named metrics_db

Create API Token

In InfluxDB UI, go to "Load Data" → "API Tokens"
Click "Generate API Token" → "Custom API Token"
Configure the token:
- Enable "Read" and "Write" permissions for the metrics_db bucket
- Name the token something recognizable (e.g., "serverpulse-token")
Save the token - you'll need it later

Step 3: Configuring Grafana

Update Grafana Datasource

Open infra/grafana/provisioning/datasources/influx.yml
Replace my-token with your InfluxDB API token
Save the file

Restart the Docker containers:

docker compose down
docker compose up -d

Configure Alert Notifications (Optional)

To set up Discord notifications:
- Open infra/grafana/provisioning/alerting/discord_contact.yml
- Replace your-webhook with your Discord webhook URL
To set up Telegram notifications:
- Open infra/grafana/provisioning/alerting/telegram_contact.yml
- Replace your_bot_token with your Telegram bot token
- Replace your_chat_id with your Telegram chat ID

Step 4: Installing the Plugin

Download the Appropriate Plugin Version

Download the latest ServerPulse plugin JAR from the releases page:
- For Bukkit/Paper servers: Download serverpulse-bukkit-x.x.x.jar
- For Velocity proxy: Download serverpulse-velocity-x.x.x.jar

Install the Plugin

Copy the appropriate JAR file to your server's plugins folder:
- For Bukkit/Paper: Copy to plugins/ folder
- For Velocity: Copy to plugins/ folder in your Velocity installation

First Run Configuration

Start your Minecraft server or Velocity proxy
The plugin will create its configuration file:
- For Bukkit/Paper: plugins/ServerPulse/config.yml
- For Velocity: plugins/serverpulse/config.yml
Stop the server
Edit the configuration file as detailed below

Bukkit/Paper Configuration

Edit plugins/ServerPulse/config.yml:

metrics:
  enabled: true
  interval: 5  # Metrics collection interval in seconds
  influxdb:
    url: http://localhost:8086  # Change if InfluxDB is on different host
    org: my-org
    bucket: metrics_db
    token: your-token-here      # Replace with your InfluxDB token
    table: minecraft_stats
  tags:
    server: "bed1"              # Change this to identify your server
messages:
  noPerms: "&7[&bServer&7Pulse] &7You don't have &bpermission &7to use this &bcommand&7."
  reloadConfig: "&7[&bServer&7Pulse] &7Configuration &breloaded&7."
  reloadConfigError: "&7[&bServer&7Pulse] &7Error &breloading &7configuration..."
  noArgs: "&7[&bServer&7Pulse] &7You need to specify a &bcommand&7: &breload&7, &bstatus&7."
  playerOnly: "&7[&bServer&7Pulse] &7This command can only be used by &bplayers&7."
  noCommand: "&7[&bServer&7Pulse] &7This command is not &bavailable&7."
  reloadConfigUsage: "&7[&bServer&7Pulse] &7Usage: &b/serverpulse reload&7."
  statusConfigUsage: "&7[&bServer&7Pulse] &7Usage: &b/serverpulse status&7."
  statusConnected: "&7[&bServer&7Pulse] &7Connected to &bInfluxDB&7."
  statusNotConnected: "&7[&bServer&7Pulse] &7Not connected to &bInfluxDB&7."

Velocity Configuration

Edit plugins/serverpulse/config.yml:

metrics:
  enabled: true
  interval: 5  # Metrics collection interval in seconds
  influxdb:
    url: http://localhost:8086  # Change if InfluxDB is on different host
    org: my-org
    bucket: metrics_db
    token: your-token-here      # Replace with your InfluxDB token
    table: minecraft_stats
  tags:
    server: "velocity1"         # Change this to identify your proxy
messages:
  usage: "&7[&bServer&7Pulse] &7Please use &b/serverpulsevelocity [status|reload]&7."
  reloadConfig: "&7[&bServer&7Pulse] &7Configuration &breloaded&7."
  reloadConfigError: "&7[&bServer&7Pulse] &7Error &breloading &7configuration..."
  statusConnected: "&7[&bServer&7Pulse] &7Connected to &bInfluxDB&7."
  statusNotConnected: "&7[&bServer&7Pulse] &7Not connected to &bInfluxDB&7."

Start the server again

Step 5: Verifying the Installation

Check Plugin Status

In your server console or as an operator, run:

For Bukkit/Paper:

/serverpulse status

For Velocity:

/serverpulsevelocity status

You should see a message confirming connection to InfluxDB.

Check Grafana Dashboard

Open http://localhost:3000 in your browser
Log in with default credentials (admin/admin) and change them on first login
Navigate to Dashboards and look for:
- For Bukkit/Paper: "Bukkit Server Metrics" and "Bukkit Players and Ping"
- For Velocity: "Velocity System Metrics" and "Velocity Players and Ping"
You should see metrics starting to appear within a few minutes

Platform-Specific Features

Bukkit/Paper Features

Complete server metrics including TPS, memory usage, and disk space
Per-world statistics for entities and loaded chunks
Player count and ping statistics
Automatic selection between Paper's native TPS API and custom TPS tracking

Velocity Features

Proxy-specific metrics focusing on network performance
Player count and ping statistics across your entire network
Memory and disk usage metrics for the proxy server
Commands use the /serverpulsevelocity prefix (or /spv for short)

Common Issues and Troubleshooting

InfluxDB Connection Failed

Verify your InfluxDB token in both Grafana datasource and plugin config
Check if InfluxDB is accessible from your Minecraft server
Ensure the correct URL is set in plugin config
Check for firewall issues if running on separate machines

Missing Metrics

Check if the plugin is enabled (/serverpulse status or /serverpulsevelocity status)
Verify the server tag in config.yml matches your dashboard queries
Check server console for any error messages
Ensure the metrics interval is appropriate (5 seconds is recommended)

Grafana Can't Connect

Verify the Docker containers are running (docker compose ps)
Check if the token in datasource configuration is correct
Look for any error messages in Grafana's interface
Try restarting the containers with docker compose restart

Monitoring Multiple Servers

To monitor multiple servers or a mixed Bukkit/Velocity environment:

Use different server tags for each server in the config.yml
Install the appropriate plugin version on each server
Connect all servers to the same InfluxDB instance
Use Grafana's dashboard variables to switch between servers

Next Steps

After successful installation, you might want to:

Set up both Bukkit/Paper and Velocity implementations for complete network monitoring
Configure the server tags to match your network naming scheme
Create custom dashboards by duplicating the provided ones
Set up alert thresholds for TPS drops or memory issues
Explore InfluxDB data retention policies for long-term monitoring

Getting Help

If you encounter any issues not covered in this guide:

Check the GitHub repository for known issues
Join the community discussion on Discord
Submit a detailed bug report if you find a new issue

Provide feedback

Saved searches

Use saved searches to filter your results more quickly