Skip to content

1. Getting started

Jump to bottom
Vincenzo Reina edited this page Apr 21, 2025 · 10 revisions

Installation Guide

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

Prerequisites

Before starting the installation, ensure you have:

  • Docker and Docker Compose installed on your machine
  • A Paper Minecraft server
  • 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

Step 4: Installing the Plugin

Copy Plugin Files

  1. Download the latest ServerPulse plugin JAR from the releases page
  2. Copy the JAR file to your Minecraft server's plugins folder

First Run and Configuration

  1. Start your Minecraft server
  2. The plugin will create its configuration file at plugins/ServerPulse/config.yml
  3. Stop the server
  4. 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: "your-server-name"  # Change this to identify your server
  5. Start the server again

Step 5: Verifying the Installation

Check Plugin Status

  1. In your Minecraft server console or as an operator, run:

    /serverpulse status

  2. 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)
  3. Look for the "Bed1's metrics" dashboard
  4. You should see metrics starting to appear

Common Issues

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

Missing Metrics

  • Check if the plugin is enabled (/serverpulse status)
  • Verify the server tag in config.yml matches your dashboard queries
  • Check server console for any error messages

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

Next Steps

After successful installation, you might want to:

Getting Help

If you encounter any issues not covered here look for similar issues on GitHub

Clone this wiki locally