Running the server

LeonsDB is a single program. This page covers starting it, configuring it and managing who may connect.

Start it

leonsdb -config leonsdb.yml

Without -config, LeonsDB uses safe defaults: it listens on 127.0.0.1:7420 (this machine only) and stores data in ./data.

On the first start, LeonsDB creates an admin token and writes it to <data_dir>/initial-admin-token. The file is readable only by the user running LeonsDB. Copy the token somewhere safe (a password manager), then delete the file. The token is deliberately not printed in the log, because logs are often kept for a long time and read by many people.

Configuration

All settings are optional. A complete example:

# Address to listen on. 127.0.0.1 = this machine only.
listen: 0.0.0.0:7420

# Where data is stored. Must be a local disk (not NFS or SMB).
data_dir: /var/lib/leonsdb

# Memory for caching data read from disk, in megabytes.
cache_size_mb: 256

# How long a Minecraft server keeps a player without renewing (ms). After a
# crash, its players can join another server once this has passed.
lease_ttl_ms: 10000

# How long the change log keeps every change (hours), for bots and services
# that follow the change feed and resume after being away. Disk use grows
# with it: roughly 60 bytes per change, so a network saving 1,000 players
# once a second needs about 5 GB per day kept.
change_retention_hours: 24

# The HTTP and WebSocket API for websites, bots and stores. Empty disables
# it. See the HTTP API guide for its other settings.
http:
  listen: 0.0.0.0:7421

# Required when listening on a network address.
tls:
  cert_file: /etc/leonsdb/tls/fullchain.pem
  key_file: /etc/leonsdb/tls/privkey.pem

log:
  level: info    # debug, info, warn or error
  format: json   # text or json

LeonsDB refuses to listen on a network address without TLS. If the network between LeonsDB and your Minecraft servers is fully private, you can allow it explicitly with insecure_allow_plaintext: true.

Unknown settings are an error, so a typo never silently falls back to a default.

Tokens

Every client authenticates with a token. There are four roles:

Role	Can do
`server`	Read and write data, create collections. Give one to each Minecraft server.
`api`	Only what its grants allow, for websites, bots and stores. See the HTTP API.
`read_only`	Read all data. For trusted tools and dashboards.
`admin`	Everything, including managing tokens.

Manage tokens from any machine that can reach the server:

export LEONSDB_TOKEN=<your admin token>

leonsdb token create -name lobby-1 -role server
leonsdb token create -name website -role api -grant example.stats:read:name,kills
leonsdb token list
leonsdb token revoke -id <token id>

Add -addr host:7420 -tls to manage a remote server. A new token is shown once and never again: LeonsDB only stores a hash of it. Revoking a token takes effect immediately.

Lost the admin token?

Stop the server, then run:

leonsdb reset-admin-token -config leonsdb.yml

It prints a new admin token. Start the server again and revoke any tokens you no longer trust.

Stopping

Send SIGTERM (what systemd and Docker do) or press Ctrl+C. LeonsDB stops accepting new requests, lets running ones finish, and closes the database cleanly. Even a hard kill or power cut never loses acknowledged writes; see Durability.

Backups

Until automatic backups arrive, stop the server and copy the data directory, or snapshot the disk. Keep copies on another machine.