1. Getting started

ServerPulse Installation Guide

This guide walks you through setting up ServerPulse, including both the monitoring infrastructure (InfluxDB and Grafana) and the plugin for Minecraft servers.

Prerequisites

Before starting, ensure you have:

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

Step 1: Setting Up the Infrastructure

Clone or Download ServerPulse

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

Start InfluxDB and Grafana

1. Open a terminal in the infra directory

2. Run the following command:

   docker compose up -d

3. Wait a few moments for the containers to start

Step 2: Configuring InfluxDB

Initial InfluxDB Setup

1. Open http://localhost:8086 in your web browser
2. 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

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

Step 3: Configuring Grafana

Update Grafana Datasource

1. Open infra/grafana/provisioning/datasources/influx.yml

2. Replace my-token with your InfluxDB API token

3. Save the file

4. Restart the Docker containers:

   docker compose down
   docker compose up -d

Configure Alert Notifications (Optional)

1. To set up Discord notifications:

   • Open infra/grafana/provisioning/alerting/discord_contact.yml
   • Replace your-webhook with your Discord webhook URL

2. 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 based on your server type:

• For Bukkit/Paper servers: serverpulse-bukkit-x.x.x.jar
• For Velocity proxy: serverpulse-velocity-x.x.x.jar
• For Fabric server: serverpulse-fabric-x.x.x.jar

Install the Plugin

Copy the appropriate JAR file to your server's plugins or mods folder:

• For Bukkit/Paper: Copy to plugins/ folder
• For Velocity: Copy to plugins/ folder
• For Fabric: Copy to mods/ folder

First Run Configuration

1. Start your server to generate the initial configuration file
2. The plugin will create its configuration file in the appropriate location:
   • For Bukkit/Paper: plugins/ServerPulse/config.yml
   • For Velocity: plugins/serverpulse/config.yml
   • For Fabric: config/serverpulse/config.yml
3. Stop the server
4. Edit the configuration file as detailed below

Configuration File Setup

Edit the configuration file for your platform and make the following changes:

metrics:
  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: "your-server-id"    # Change this to identify your server
                                # Use something like "bukkit1", "velocity1", or "fabric1"

The rest of the configuration contains customizable messages that you can adjust as needed.

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

For Fabric:

/serverpulse status

You should see a message confirming connection to InfluxDB.

Check Grafana Dashboard

1. Open http://localhost:3000 in your browser
2. Log in with default credentials (admin/admin) and change them on first login
3. Navigate to Dashboards and look for the appropriate dashboard based on your server type:
   • For Bukkit/Paper: "Bukkit Server Metrics" and "Bukkit Players and Ping"
   • For Velocity: "Velocity System Metrics" and "Velocity Players and Ping"
   • For Fabric: "Fabric Server Metrics" and "Fabric Players and Ping"
4. You should see metrics starting to appear within a few minutes

Platform-Specific Features

Common Features Across All Platforms

• Memory usage and disk space monitoring
• Player count and ping statistics
• Configuration reload commands

Bukkit/Paper Features

• TPS (Ticks Per Second) monitoring with automatic selection between Paper's native TPS API and custom tracking
• Per-world statistics for entities and loaded chunks

Velocity Features

• Proxy-specific metrics focusing on network performance
• Player monitoring across your entire network
• Commands use the /serverpulsevelocity prefix (or /spv for short)

Fabric Features

• Native Fabric implementation using Fabric API
• TPS monitoring through custom implementation
• Per-world entity and chunk metrics similar to Bukkit
• Compatible with modern Minecraft versions (1.20+)

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 with the status command
• Verify the server tag in config 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 environment:

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

Next Steps

After successful installation, you might want to:

• Set up multiple server implementations for complete network monitoring
• Configure 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