forked from Kweebec_Network/core-vitals
145 lines
7.1 KiB
Markdown
145 lines
7.1 KiB
Markdown
# Configuration
|
|
|
|
## Location
|
|
|
|
`<plugin data dir>/config.json`. NetworkCore writes a default file on first boot if none exists, with the values shown below.
|
|
|
|
## Full config
|
|
|
|
```json
|
|
{
|
|
"server": {
|
|
"id": null,
|
|
"role": "lobby",
|
|
"public_address": null,
|
|
"public_port": null,
|
|
"lobby_role": "lobby",
|
|
"lobby_role_prefix": "lobby_"
|
|
},
|
|
"redis": {
|
|
"url": null,
|
|
"host": "127.0.0.1",
|
|
"port": 6379,
|
|
"password": null,
|
|
"database": 0,
|
|
"key_prefix": "network:",
|
|
"tls": false,
|
|
"verify_peer": true
|
|
},
|
|
"network": {
|
|
"auth_token": null
|
|
},
|
|
"metrics": {
|
|
"enabled": true,
|
|
"bind": "127.0.0.1",
|
|
"port": 9100,
|
|
"path": "/metrics"
|
|
},
|
|
"rpc": {
|
|
"timeout_ms": 5000
|
|
},
|
|
"mysql": {
|
|
"enabled": false,
|
|
"host": "127.0.0.1",
|
|
"port": 3306,
|
|
"database": "kweebec",
|
|
"user": "kweebec",
|
|
"password": null,
|
|
"max_pool_size": 10,
|
|
"min_idle": 2,
|
|
"connection_timeout_ms": 5000,
|
|
"idle_timeout_ms": 600000,
|
|
"max_lifetime_ms": 1800000,
|
|
"use_ssl": false
|
|
}
|
|
}
|
|
```
|
|
|
|
## Fields
|
|
|
|
### server
|
|
|
|
| Field | Default | Meaning |
|
|
|---|---|---|
|
|
| `id` | `null` | Optional fixed server id. If null, auto-generated as `<role>-<8 hex chars>` (e.g. `lobby-3f2a91bd`) on every boot. Set this when you want a stable id across restarts. |
|
|
| `role` | `"lobby"` | Logical role of this server. Used to filter via `ServerRegistry.getServersByRole(...)`. Examples: `lobby`, `bridge_duel`, `arena`. Use snake_case. |
|
|
| `public_address` | `null` | Hostname/IP other servers will hand to players when transferring them HERE via `/send` / `/hub`. Null = auto-detect system hostname. **Set this explicitly on hosted setups** where auto-detect gives the wrong answer (typically `127.0.0.1` or a private LAN name). |
|
|
| `public_port` | `null` | Port for the same. Null = Hytale's `DEFAULT_PORT` (currently 5520). |
|
|
| `lobby_role` | `"lobby"` | Role string `/hub` and shutdown handoff look for first. |
|
|
| `lobby_role_prefix` | `"lobby_"` | If no server matches `lobby_role`, accept any role starting with this prefix (e.g. `lobby_eu`, `lobby_na`). |
|
|
|
|
### redis
|
|
|
|
| Field | Default | Meaning |
|
|
|---|---|---|
|
|
| `url` | `null` | Full Redis connection URI. Supports both `redis://` (plain) and `rediss://` (TLS). When set, **all other redis fields are ignored** (host, port, password, database, tls). This is what you want when your provider hands you a one-line connection string. Prefer the env var (below) over putting credentials in the file. |
|
|
| `host` | `"127.0.0.1"` | Redis host. Only used when `url` is null. |
|
|
| `port` | `6379` | Redis port. Only used when `url` is null. |
|
|
| `password` | `null` | Redis AUTH password. Only used when `url` is null. Prefer the env var. |
|
|
| `database` | `0` | Redis logical database (0-15 on stock Redis). Only used when `url` is null. |
|
|
| `key_prefix` | `"network:"` | All keys NetworkCore writes start with this prefix. Server registry keys end up at `network:servers:<id>`. Change this only if you're sharing a Redis with something unrelated. **Applies regardless of `url`.** |
|
|
| `tls` | `false` | Enables TLS for the Redis connection. Only used when `url` is null (the URI scheme picks TLS on/off when `url` is set). **Set to true whenever Redis is on a different host than the Hytale server**, since the connection crosses untrusted network. |
|
|
| `verify_peer` | `true` | When TLS is on (via `tls: true` or a `rediss://` url), verifies the Redis server's certificate against the JVM's default trust store. Set to false only in dev / against self-signed certs. Logs a warning when disabled. |
|
|
|
|
### network
|
|
|
|
| Field | Default | Meaning |
|
|
|---|---|---|
|
|
| `auth_token` | `null` | Shared secret. When set, every outgoing envelope is stamped with this token and every inbound message is rejected unless its token matches. When null, no auth is enforced. Use the env var. |
|
|
|
|
### metrics
|
|
|
|
| Field | Default | Meaning |
|
|
|---|---|---|
|
|
| `enabled` | `true` | Turn the whole metrics system on/off. When off, `getMetrics()` returns null. |
|
|
| `bind` | `"127.0.0.1"` | Address to bind the Prometheus HTTP server. Defaults to loopback so it's not exposed to the public internet. Set to `0.0.0.0` only if you've put auth / a reverse proxy in front. |
|
|
| `port` | `9100` | Port for the Prometheus exporter |
|
|
| `path` | `"/metrics"` | URL path. Standard convention is `/metrics`. |
|
|
|
|
### rpc
|
|
|
|
| Field | Default | Meaning |
|
|
|---|---|---|
|
|
| `timeout_ms` | `5000` | How long an RPC request waits for a response before completing the future exceptionally with `TimeoutException`. |
|
|
|
|
### mysql
|
|
|
|
| Field | Default | Meaning |
|
|
|---|---|---|
|
|
| `enabled` | `false` | Master switch. When false, `getDatabase()` returns null and no pool is created. Set to true once you've put real credentials in place. |
|
|
| `host` | `"127.0.0.1"` | MySQL host. |
|
|
| `port` | `3306` | MySQL port. |
|
|
| `database` | `"kweebec"` | Database (schema) name. Must exist before NetworkCore boots; we don't auto-create databases. |
|
|
| `user` | `"kweebec"` | MySQL user. |
|
|
| `password` | `null` | MySQL password. Prefer the env var. |
|
|
| `max_pool_size` | `10` | Hikari `maximumPoolSize`. |
|
|
| `min_idle` | `2` | Hikari `minimumIdle`. |
|
|
| `connection_timeout_ms` | `5000` | Hikari `connectionTimeout`. |
|
|
| `idle_timeout_ms` | `600000` (10 min) | Hikari `idleTimeout`. |
|
|
| `max_lifetime_ms` | `1800000` (30 min) | Hikari `maxLifetime`. Keep below MySQL's `wait_timeout`. |
|
|
| `use_ssl` | `false` | Adds `useSSL=true` to the JDBC URL. Turn on whenever MySQL is on a different host than the Hytale server. |
|
|
|
|
## Environment variable overrides
|
|
|
|
These take precedence over the config file at boot time. Use them for secrets so the config file stays safe to check into version control.
|
|
|
|
| Env var | Overrides |
|
|
|---|---|
|
|
| `REDIS_URL` | `redis.url` (full connection URI) |
|
|
| `REDIS_PASSWORD` | `redis.password` |
|
|
| `NETWORK_AUTH_TOKEN` | `network.auth_token` |
|
|
| `MYSQL_PASSWORD` | `mysql.password` |
|
|
|
|
## Recommended setup per environment
|
|
|
|
**Local dev (single server):**
|
|
- Defaults are fine. Run Redis on localhost, don't set the auth token.
|
|
|
|
**Multi-server staging or production:**
|
|
- `server.id` left null is fine if you're OK with the id changing on every boot. Set it to something stable like `lobby-prod-01` if you want logs and dashboards to keep continuity across restarts.
|
|
- `server.role` set explicitly per server. This is what dashboards and routing use.
|
|
- **Easiest path for hosted Redis**: set `REDIS_URL` env var to the `rediss://user:pass@host:port/0` string your provider gives you. Leave the host/port/password/database fields at defaults. The `rediss://` scheme already implies TLS - no need to touch `tls`.
|
|
- **Alternative**: set `redis.host` / `redis.port` explicitly, put the password in `REDIS_PASSWORD`, and set `redis.tls: true`. Works the same; just more fields to keep in sync across servers.
|
|
- `network.auth_token` not in the file; set `NETWORK_AUTH_TOKEN` env var to the same value on every server.
|
|
- `metrics.bind` stays `127.0.0.1`. Run Prometheus on the same host (or use an SSH tunnel / reverse proxy with auth to expose it elsewhere).
|