Configuration Reference

statfyr is configured entirely through plugins/statfyr/config.yml. This page documents every key in the shipped default file and what each one actually does in v1.0.0-BETA.

File location

plugins/statfyr/config.yml, created automatically on first boot with the defaults shown below. config-version is managed by the plugin; do not edit it.

Full example

This is the file the plugin ships, verbatim:

plugins/statfyr/config.yml (default)yaml

# Statfyr Configuration
config-version: 1

http:
  port: 8080
  bind-address: "0.0.0.0"     # 0.0.0.0 = public, 127.0.0.1 = localhost only
  request-timeout-seconds: 15
  max-request-body-kb: 512

https:
  enabled: false
  keystore-path: "plugins/statfyr/keystore.jks"
  keystore-password: "changeit"

compression:
  enabled: true

async:
  enabled: true

docs:
  enabled: true

debug: false

security:
  enable-api-key: false
  api-key: ""

  enable-rate-limit: true
  rate-limit-requests: 120
  rate-limit-window-seconds: 60

  enable-cors: true
  allowed-origins:
    - "*"

  enable-ip-whitelist: false
  allowed-ips: []

query:
  max-limit: 100

pagination:
  default-limit: 25
  max-limit: 100

sorting:
  default-order: "desc"       # asc | desc

cache:
  ttl-seconds: 60
  refresh-seconds: 10

Key reference

Status reflects v1.0.0-BETA behavior: enforced keys change runtime behavior today; reserved keys are read into the config but not yet wired to the feature they name.

Key	Default	Status	Behavior
`http.port`	8080	Enforced	Port the embedded HTTP server binds (clamped to 1–65535).
`http.bind-address`	0.0.0.0	Enforced	Bind address. Use 127.0.0.1 to keep the API local-only.
`http.request-timeout-seconds`	15	Reserved	Loaded but not applied to exchanges yet.
`http.max-request-body-kb`	512	Reserved	Loaded but not applied (all routes are GET with no body).
`https.enabled`	false	Enforced	Serve over HTTPS using the JKS keystore instead of plain HTTP.
`https.keystore-path`	plugins/statfyr/keystore.jks	Enforced	Path to the JKS keystore.
`https.keystore-password`	changeit	Enforced	Keystore password; `STATFYR_KEYSTORE_PASSWORD` wins if set.
`compression.enabled`	true	Reserved	Reported in `/api/health` features. Gzip is actually driven by each client's `Accept-Encoding`.
`async.enabled`	true	Reserved	Reported in `/api/health` features. Request handling is always asynchronous.
`docs.enabled`	true	Reserved	Reported in `/api/health` features. `/api` and `/api/docs` are always registered.
`debug`	false	Enforced	Verbose request logging (method, path, status) to the server console.
`security.enable-api-key`	false	Enforced	Require `Authorization: Bearer <key>`. Auth only activates when a non-blank key is configured.
`security.api-key`	(empty)	Enforced	The Bearer key. `STATFYR_API_KEY` wins if set.
`security.enable-rate-limit`	true	Enforced	Per-IP fixed-window rate limiting; excess requests get HTTP 429.
`security.rate-limit-requests`	120	Enforced	Requests allowed per window per IP.
`security.rate-limit-window-seconds`	60	Enforced	Window length in seconds.
`security.enable-cors`	true	Enforced	Sends CORS headers and answers `OPTIONS` preflights with 204.
`security.allowed-origins`	["*"]	Reserved	Loaded but not used for matching: when CORS is on, `Access-Control-Allow-Origin: *` is always sent.
`security.enable-ip-whitelist`	false	Enforced	Reject clients whose IP is not in `allowed-ips` with HTTP 403.
`security.allowed-ips`	[]	Enforced	Whitelist entries (exact IPs).
`query.max-limit`	100	Reserved	Loaded but unused; `pagination.max-limit` is what clamps `limit`.
`pagination.default-limit`	25	Enforced	Default page size for `/api/players` and leaderboards.
`pagination.max-limit`	100	Enforced	Maximum accepted `limit`; larger values are clamped.
`sorting.default-order`	desc	Enforced	Default sort direction when `order` is omitted.
`cache.ttl-seconds`	60	Reserved	Loaded but unused; the statistic cache TTL is hard-coded at 30 seconds.
`cache.refresh-seconds`	10	Reserved	Loaded but unused; the background refresh runs every 5 seconds.

Environment overrides

Two secrets can be supplied through the environment instead of the config file:

Variable	Overrides	Use
`STATFYR_API_KEY`	`security.api-key`	Keep the Bearer key out of config.yml and backups.
`STATFYR_KEYSTORE_PASSWORD`	`https.keystore-password`	Keep the keystore password out of config.yml and backups.

HTTPS setup

statfyr serves HTTPS from a Java JKS keystore. Generate one with keytool(ships with your JDK), then flip https.enabled to true and restart:

keytool -genkeypair -alias statfyr \
  -keyalg RSA -keysize 2048 \
  -storetype JKS \
  -keystore keystore.jks \
  -validity 3650

Reserved keys

Applying changes

Run /statfyr reload (permission statfyr.admin) to re-read the file without a restart, or /statfyr status to confirm what the server picked up: bind address, port, HTTPS, auth, rate limiting, and cache state.

← PreviousGetting Started Next →API Reference