gdatum is a self-hosted service that aggregates player-count and metadata for game multiplayer platforms. It periodically scrapes master-server APIs, persists raw and aggregated metrics in ClickHouse, and exposes a REST API, an embedded web UI, and Prometheus metrics.

A public instance runs at https://gdatum.epicstep.dev — API reference: https://gdatum.epicstep.dev/docs.

---

Supported platforms

Platform	Identifier	Source
RAGE Multiplayer	ragemp	https://cdn.rage.mp/master/
Majestic	magestic	https://api.majestic-files.com/meta/servers

---

Features

• Hourly collection from every supported master server, with retries and per-platform error metrics.
• Time-series storage on ClickHouse using MergeTree for online history and ReplacingMergeTree for server metadata.
• Per-hour / per-day aggregation precision for historical queries.
• OpenAPI 3.0 contract (api/spec.yaml), with the Go server stub generated by ogen.
• Embedded web UI — Next.js 16 static export served from the same binary via //go:embed.
• Production-ready ops: structured JSON logs (zap), Prometheus metrics, pprof on a separate admin port, distroless container image.
• Hardened releases: multi-arch (amd64/arm64) binaries and images, signed with Sigstore Cosign, SBOMs and SLSA build-provenance attestations.

---

Quick start

Docker Compose

The fastest way to try gdatum locally is to bring up ClickHouse with the bundled compose file, then run gdatum against it.

# 1. Start ClickHouse
docker compose up -d

# 2. Run migrations
docker run --rm --network host \
  -e DATABASE_DSN='clickhouse://default:dev-password@127.0.0.1:9000/default' \
  ghcr.io/epicstep/gdatum:latest --migrate

# 3. Run the server
docker run --rm --network host \
  -e DATABASE_DSN='clickhouse://default:dev-password@127.0.0.1:9000/default' \
  -e PUBLIC_LISTEN_ADDRESS='0.0.0.0:8080' \
  -e ADMIN_LISTEN_ADDRESS='0.0.0.0:8081' \
  ghcr.io/epicstep/gdatum:latest

Open http://127.0.0.1:8080 for the UI and http://127.0.0.1:8080/docs for the API reference.

From a release binary

Pre-built binaries for Linux, macOS and Windows (amd64 / arm64) are attached to every GitHub release, together with checksums.txt, SBOMs and Cosign signatures.

# Verify the checksum signature
cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github.com/EpicStep/gdatum/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  checksums.txt

# Extract and run
tar -xzf gdatum_*_linux_amd64.tar.gz
DATABASE_DSN='clickhouse://...' ./gdatum --migrate
DATABASE_DSN='clickhouse://...' ./gdatum

For building from source, see CONTRIBUTING.md.

---

Configuration

All configuration is read from environment variables.

Variable	Required	Default	Description
DATABASE_DSN	yes	—	ClickHouse DSN, e.g. clickhouse://user:pass@host:9000/db
PUBLIC_LISTEN_ADDRESS	no	127.0.0.1:8080	Address for the public HTTP server (UI + REST API)
ADMIN_LISTEN_ADDRESS	no	127.0.0.1:8081	Address for the admin HTTP server (metrics / pprof)

CLI flags:

Flag	Description
--migrate	Apply pending database migrations and exit
--version	Print build version, commit and date, then exit

---

HTTP endpoints

The REST API is described by api/spec.yaml and the rendered reference is available on every running instance at /docs — for example, https://gdatum.epicstep.dev/docs.

On the admin server (ADMIN_LISTEN_ADDRESS):

• GET /health — liveness probe, returns {"status":"ok"}.
• GET /metrics — Prometheus metrics.
• /debug/pprof/... — standard Go net/http/pprof profiles.

Do not expose the admin port to the public internet.

---

Documentation

• docs/ARCHITECTURE.md — system architecture, storage model, code layout.
• CONTRIBUTING.md — local development, build, test, lint and release workflow.

---

License

Licensed under the Apache License 2.0.