Installation

Install Bridge on Paper servers and a Velocity proxy, connect Stash to MongoDB and Redis, and point Bridge at Catalyst.

Before you start

Have these ready first. Requirements explains each one.

Catalyst running, with an API key.
A MongoDB and a Redis that Catalyst and every server can reach. Catalyst and Stash must use the same Redis.
The Aegis loader on every server. If it isn't there yet, follow Installation.

Paper servers

Repeat these steps on every Paper server.

Install packetevents

Put the packetevents plugin in plugins/. Bridge and Kernel need it and it isn't delivered by the loader.

Add Bridge to the loader

Add Bridge under products: in the loader's config.yml. Add Toolkit and Sentry too if you want them. Kernel and Stash come with Bridge on their own.

plugins/Aegis/config.yml

products:
  Bridge:
    enabled: true
    release: latest
    channel: stable
    required: true

Start the server once so it creates the config files below. Bridge won't connect until you set its Catalyst key, so don't let players in yet.

Connect Stash to MongoDB and Redis

Stash holds the database connections every Scala plugin on the server uses. Edit both files in plugins/Stash/.

plugins/Stash/mongo.yml

uri: mongodb://127.0.0.1:27017/admin
database: Scala

plugins/Stash/redis.yml

hostname: 127.0.0.1
port: 6379
password: null
database: 0
pubSubPublishTarget: __default__

These environment variables replace the file values when set: MONGODB_URI, MONGODB_DATABASE, REDIS_HOST, REDIS_PORT, REDIS_PASSWORD and REDIS_INDEX. Stash changes apply after a restart.

Name the server in Kernel

Set the server's id, region and group in plugins/Kernel/kernel.yml.

Key	Default	What it does
`serverId`	`unknown`	This server's unique id, like `lobby-1`. `BRIDGE_SERVER` overrides it.
`region`	`local`	The region this server runs in, like `na` or `eu`. `NEXUS_REGION` overrides it.
`group`	empty	The server's group, or several separated by commas. Empty uses the id without its last part. `BRIDGE_GROUP` overrides it.

Point Bridge at Catalyst

Edit plugins/Bridge/bridge.yml.

Key	Default	What it does
`catalystHost`	`http://127.0.0.1:8080`	Catalyst's address with `http://` or `https://` and the port. `CATALYST_HOST` overrides it.
`catalystKey`	empty	Your Catalyst API key. Bridge stays disconnected while it is empty or wrong. `CATALYST_KEY` overrides it.
`serverId`	`unknown`	The same id as in `kernel.yml`, matching the server's name in `velocity.toml`. `BRIDGE_SERVER` overrides it.
`hubServer`	`lobby`	The group or server id `/hub` sends players to. `BRIDGE_HUB` overrides it.
`maxPlayers`	`100`	The player limit this server reports, shown in `/list` and the server menu.
`degradation`	`FAIL_CLOSED`	What happens when a joining player's profile can't load because Catalyst is unreachable. `FAIL_CLOSED` turns them away; `FAIL_OPEN` lets them in.
`regions`	empty	Regions players can move to with `/region`. See Proxy and network.

The file also lists serverGroup, heartbeatSeconds, rankCacheSeconds, profileCacheSeconds and degradedKickMessage. This version of Bridge doesn't read them.

plugins/Bridge/bridge.yml

catalystHost: http://10.0.0.5:8080
catalystKey: cat_mynet_replace-with-your-key
serverId: lobby-1
hubServer: lobby

Restart

Restart the server. If catalystKey is empty, Bridge logs a warning every five minutes that names catalystHost and catalystKey. If Catalyst is unreachable or rejects the key, Bridge logs "heartbeat failed" once.

Velocity proxy

Add Bridge to the proxy's loader

Add Bridge under products: in the proxy loader's config.yml, the same way as on Paper. Don't add Toolkit or Sentry on the proxy.

Set the environment variables

Bridge on the proxy has no settings file. It reads environment variables, and it won't start without CATALYST_KEY.

Variable	Default	What it does
`CATALYST_KEY`	none	Your Catalyst API key. Required.
`CATALYST_HOST`	`http://127.0.0.1:8080`	Catalyst's address.
`BRIDGE_PROXY`	`proxy`	This proxy's id on the network.
`BRIDGE_SERVER`	empty	The proxy's name in staff join and leave notices. The last `-part` is dropped, so `proxy-1` shows as `proxy`. Falls back to `BRIDGE_PROXY`.
`BRIDGE_FAIL_OPEN`	`false`	`true` lets players in when Catalyst can't be reached.
`BRIDGE_PLAYER_CAP`	none	The maximum player count shown in the server list.
`BRIDGE_MOTD_CENTERED`	`false`	`true` centres every MOTD line.
`BRIDGE_ALLOWED_PROTOCOLS`	none	Comma-separated protocol numbers of the client versions allowed to join. Empty allows every version.
`BRIDGE_VERSION_LABEL`	empty	The versions named on the screen shown to a blocked client, like `1.21.x`.

Connect Stash on the proxy

Stash comes with Bridge on the proxy too. On Velocity its files are JSON: plugins/Stash/mongo.json with uri and database, and plugins/Stash/redis.json with hostname, port, password and database. The same MONGODB_* and REDIS_* environment variables work here.

Restart the proxy

The proxy logs "Bridge proxy gate active against" followed by Catalyst's address once it is running.

Check it works

Join through the proxy. If you get "The network is currently unavailable", the proxy or the server can't reach Catalyst. Check the key and address.
From a Paper server's console, run /rank create Owner, then /rank list. Owner should be listed on every Paper server.
Give yourself the rank from the console: /grantmanual <your name> Owner perm. Then set up your ranks as shown on Ranks and tags.

Messages and menus are in messages.yml and menus.yml in plugins/Bridge/ on each Paper server. The proxy has its own messages.yml in plugins/Bridge/. Saving these files reloads them.