Skip to content

Configuration

Jump to bottom
Ashutosh Das edited this page May 20, 2026 · 1 revision

Configuration

Statfyr is configured via plugins/statfyr/config.yml, generated automatically on first run. After making changes, run /statfyr reload to apply them without restarting the server.

Full Default Config

# =========================================================
# Statfyr Configuration
# =========================================================
 
config-version: 1
 
http:
  port: 8080
  bind-address: "0.0.0.0"
  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"
 
cache:
  ttl-seconds: 60
  refresh-seconds: 10

Section Reference

http — HTTP Server

Controls the core HTTP server behaviour.

Key Type Default Description
port integer 8080 Port the REST API listens on
bind-address string "0.0.0.0" Network interface to bind to. Use 127.0.0.1 for localhost-only access
request-timeout-seconds integer 15 How long before an incoming request times out
max-request-body-kb integer 512 Maximum allowed request body size in kilobytes

Example — localhost only:

http:
  port: 8080
  bind-address: "127.0.0.1"

https — HTTPS / TLS

Enables SSL/TLS. Requires a Java keystore file.

Key Type Default Description
enabled boolean false Enable HTTPS
keystore-path string "plugins/statfyr/keystore.jks" Path to the JKS keystore
keystore-password string "changeit" Keystore password. Can be overridden via STATFYR_KEYSTORE_PASSWORD

Generate a keystore:

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

See Authentication & Security for full HTTPS setup guidance.

compression

Key Type Default Description
enabled boolean true Enable gzip response compression. Clients must send Accept-Encoding: gzip

async

Key Type Default Description
enabled boolean true Load player stats asynchronously, off the main server thread. Strongly recommended to leave enabled.

docs

Key Type Default Description
enabled boolean true Enable the built-in API documentation browser at /api and /api/docs

Disable this in production if you don't want the docs publicly accessible.

debug

Key Type Default Description
debug boolean false Enable verbose debug logging to the console

security — Authentication, Rate Limiting, CORS, IP Whitelist

API Key Authentication

Key Type Default Description
enable-api-key boolean false Require a Bearer token on all requests
api-key string "" The secret API key. Can be set via STATFYR_API_KEY environment variable

Rate Limiting

Key Type Default Description
enable-rate-limit boolean true Enable per-IP rate limiting
rate-limit-requests integer 120 Maximum requests allowed per window
rate-limit-window-seconds integer 60 Length of the rate limit window in seconds

CORS

Key Type Default Description
enable-cors boolean true Enable CORS headers
allowed-origins list ["*"] Allowed browser origins. Use ["*"] for open access or specify domains

Example — restrict to your dashboard domain:

allowed-origins:
  - "https://dashboard.example.com"
  - "https://stats.example.com"

IP Whitelist

Key Type Default Description
enable-ip-whitelist boolean false Restrict API access to specific IP addresses only
allowed-ips list [] List of allowed IP addresses

Example:

enable-ip-whitelist: true
allowed-ips:
  - "127.0.0.1"
  - "192.168.1.50"

query

Key Type Default Description
max-limit integer 100 Hard cap on the limit query parameter across all endpoints

pagination

Key Type Default Description
default-limit integer 25 Default page size when no limit param is specified
max-limit integer 100 Maximum page size

sorting

Key Type Default Description
default-order string "desc" Default sort direction. Accepts asc or desc

cache

Key Type Default Description
ttl-seconds integer 60 How long a cached response is considered valid
refresh-seconds integer 10 How often the cache checks for stale entries to refresh

See Caching for more detail.

Environment Variable Overrides

Sensitive values can be set via environment variables instead of the config file, which is useful for Docker or CI deployments.

Environment Variable Overrides
STATFYR_API_KEY security.api-key
STATFYR_KEYSTORE_PASSWORD https.keystore-password

Next: API Reference

Clone this wiki locally