Skip to content

Installation

Pavel Erokhin edited this page Nov 9, 2026 · 2 revisions

The exporter needs a server on Paper 26.3, or a fork of it, with WorldAPI 3.0 or newer. Out of the box WorldAPI lets anonymous clients read everything the basic metrics need, so you can start without a token and add one later.

Pick one way to run it: Docker Compose, a ready stack from examples/, docker run, or a binary.

Docker Compose

  1. Add the exporter next to your server in compose.yaml:

    services:
      minecraft-exporter:
        image: ghcr.io/mairwunnx/minecraft-exporter:latest
        restart: unless-stopped
        environment:
          WORLDAPI_URL: http://minecraft:8110/api/v1

    WORLDAPI_URL points at WorldAPI and ends in /api/v1. Here minecraft is the server's service name: use yours.

  2. Start it: docker compose up -d minecraft-exporter.

  3. Check it as “Check that it works” says.

The image runs on amd64 and arm64. Besides latest, it carries tags for each release: 1.1.0, 1.1, and 1. Pin one in production, so an update comes when you choose.

The whole stack from examples/

examples/ holds the exporter, Prometheus, and Grafana with the dashboard provisioned.

  1. Clone the repository and go to examples/:

    git clone https://github.com/MairwunNx/minecraft-exporter.git
    cd minecraft-exporter/examples
  2. Fetch the dashboard:

    curl -Lo grafana/dashboards/minecraft.json https://github.com/MairwunNx/minecraft-grafana/releases/latest/download/minecraft.json
  3. Start the stack with your WorldAPI's address:

    WORLDAPI_URL=http://your-server:8110/api/v1 docker compose up -d

    Add WORLDAPI_TOKEN=… before docker compose to read with a token. The dashboard's chat, event, and console tables need one. Read WorldAPI token before you set it.

  4. Open Grafana at http://localhost:3000 and log in as admin / admin.

Without WORLDAPI_URL the stack reads http://host.docker.internal:8110/api/v1: a WorldAPI on the same machine.

docker run

docker run -d --name minecraft-exporter -p 10059:10059 \
  -e WORLDAPI_URL=http://your-server:8110/api/v1 \
  ghcr.io/mairwunnx/minecraft-exporter:latest

A binary

  1. Download the archive for your system from the latest release: Linux, macOS, or Windows, on amd64 or arm64. checksums.txt next to them holds their SHA-256 sums.

  2. Unpack it and start the exporter:

    WORLDAPI_URL=http://localhost:8110/api/v1 ./minecraft-exporter

    Flags work too: ./minecraft-exporter --worldapi.url=http://localhost:8110/api/v1. ./minecraft-exporter --version prints the version.

Check that it works

  1. Open http://localhost:10059/metrics. The page lists metrics that start with minecraft_.
  2. Look for minecraft_up 1: WorldAPI answered. 0 means it didn't: see Troubleshooting.
  3. Player statistics arrive a few at a time, so give them a minute or two of scrapes.

/healthz answers ok while the exporter runs, for a container health check.

Next: Configuration.

Clone this wiki locally