Installation

There are three pieces to install: the master service (Postgres-backed event sink), the Paper and Velocity plugins (event producers), and optionally Metabase (dashboards).

1. Pre-flight

RabbitMQ reachable from every game server.
PostgreSQL 15+ reachable from the master node.
AstralCore installed and configured (its env-based CredentialsProvider is reused for the RabbitMQ connection).

2. Database

The master ships a schema.sql that the DatabaseService runs on connect:

CREATE TABLE IF NOT EXISTS events (
    id           SERIAL PRIMARY KEY,
    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    type         VARCHAR(50) NOT NULL,
    player_uuid  UUID        NULL,
    server_name  VARCHAR(50) NOT NULL DEFAULT 'main',
    server_group VARCHAR(50) NOT NULL DEFAULT 'default',
    payload      JSONB       NOT NULL
);

CREATE INDEX idx_events_created_at ON events (created_at DESC);
CREATE INDEX idx_events_type       ON events (type);
CREATE INDEX idx_events_player_uuid ON events (player_uuid);
CREATE INDEX idx_events_payload_gin ON events USING GIN (payload);

The GIN index on payload lets you filter on JSONB fields (e.g. payload->>'country' = 'FR') without a sequential scan.

3. Master service

The master is a MageHic plugin. Drop the master JAR into your MageHic plugins directory and provide database.properties in its data folder:

jdbcUrl=jdbc:postgresql://metabase_db:5432/metabase?sslmode=disable
driverClassName=org.postgresql.Driver
dataSource.user=metabase
dataSource.password=your_strong_password
poolName=AstralAnalytics

The PostgreSQL JDBC driver must be on the classpath. The master fails fast on startup with a clear error if it can't load org.postgresql.ds.PGSimpleDataSource.

RabbitMQ credentials come from environment variables via AstralCore's EnvCredentialsProvider.

4. Paper plugin

Drop the paper JAR into plugins/ on every Paper server you want telemetry from. The plugin:

Connects to RabbitMQ using the same env-based credentials AstralCore uses.
Registers the AnalyticsService with AstralPaperAPI.
Registers the track-event global action.
Wires three sources of built-in events: join/quit, command execution, and the LuckPerms hook.

plugin.yml:

name: AstralAnalytics
api-version: '1.21'
depend:
  - AstralCore
softdepend:
  - LuckPerms

No additional configuration file is required on Paper.

5. Velocity plugin

Drop the velocity JAR into the proxy's plugins/ directory. The proxy plugin emits the richest set of join events (IP, client brand, mod info, locale settings) — see Events.

6. Metabase (optional)

docker-compose.yml in the repo provisions Postgres and Metabase in one shot:

docker compose up -d

Service	Port	Notes
PostgreSQL 15	5432	Volume: `postgres_data`.
Metabase	3000	Volume: `metabase_data`.

On first launch:

Open http://localhost:3000.
Complete the Metabase setup wizard.
Add a database of type PostgreSQL pointing at the same events database the master writes to:
- Host: db (from inside the Docker network) or your DB host externally.
- Database name: metabase (or whatever you configured).
- User / password: as in docker-compose.yml.
Metabase scans the events table and exposes it for queries.

See Metabase for example dashboards.

Permissions

There is no permission tree — AstralAnalytics has no commands. Events are emitted automatically based on Bukkit / Velocity events and the track-event action. Plugins integrate through the AnalyticsService API.

Last modified: 25 July 2026