Config Files

Where TriBridge keeps its settings: two local files, and the shared database.

TriBridge keeps two things in the project root, next to the repository, and everything else in the shared PostgreSQL database. The local files are gitignored, so a git pull never touches them and nothing secret can be committed by accident.

.env is the one file you write yourself, and the bot will not start without it. Copy the .env.example template in the repository and fill it in — that copy is tracked in git, the .env it produces is not.

File	Holds	Managed with
.env	Token, bridge channel, log channel, database, first account	Editing it — see Configuration
.minecraft-auth/	Cached Microsoft tokens, one entry per account	The bot

Settings in the database

The settings you change from Discord are stored in the database DATABASE_URL points at, in one table, tribridge.config, which the bot creates the first time it starts. It sits in its own tribridge schema, apart from the community bot’s tables.

Setting	Holds	Managed with
guilds	The Hypixel guild registry	/guilds
globalProfile	The running global profile change, and its scope	/adminpanel
auditChannel	The default audit channel	/auditchannel
linkedAccounts	The bridge’s Minecraft account links	/link

These are the bridge’s own links, separate from the THG Community bot’s. What the two bots share is the blacklist and the admin roles, both in the community bot’s tables; neither has a config file here.

The first time the bot starts without a linkedAccounts setting (and without a linkedAccountsConfig.json to import), it copies the community bot’s links once, so nobody has to link again. That copy is saved even when it is empty, so it never runs twice; from then on the two lists are independent.

Upgrading from the JSON files

Older versions kept these settings in guildsConfig.json, globalProfileConfig.json, auditChannelConfig.json and linkedAccountsConfig.json in the project root. On the first start after upgrading, each setting that is not in the database yet is imported from its file, and the console says which. After that the database is authoritative, and nothing needs doing by hand. Restarting again does not import twice.

The files stay, as snapshots of the database: the bot rewrites each one after every saved change and on every start, so they always hold the last settings the database confirmed. They are written through a temporary file and a rename, so a crash mid-write leaves the previous snapshot intact. Don’t edit them by hand expecting an effect: the database wins, and the next start overwrites the file.

To import files from somewhere else (a copy taken off another server), or to check them first, use the import script. It prints only key names and list lengths, never the ids themselves:

npm run config:import -- --dry-run --dir path/to/folder   # check the files, no database needed
npm run config:import -- --dir path/to/folder             # import whatever the database doesn't have yet
npm run config:import -- --dir path/to/folder --force     # overwrite what the database has

Restart the bot afterwards to load what was imported.

A file that is not valid JSON stops the bot at startup, as long as the database has no copy of that setting yet. Fix the file and restart, or move it out of the project root to start without it. Starting on defaults instead would strand the file: the first change saved from Discord would create the setting in the database, and the file would never be imported after that. Once the database has the setting, the file is ignored whatever is in it.

linkRoleConfig.json and featureRequestsConfig.json are from features that moved to the community bot. Nothing reads them.

Things worth knowing

A database outage doesn’t take the bridge down. If the database cannot be reached at startup, the bot retries for about 40 seconds, then starts from the snapshot files and posts a warning in the log channel. The relay and every guild connection work as normal. Settings changes (/guilds, /auditchannel, the admin panel) fail with an error until the database is back, because every change is saved there first. That’s what stops a change from existing only in memory, or only on disk, and then being lost or overwritten later. The bot still refuses to start without DATABASE_URL set at all, or with neither a database nor a snapshot to start from, rather than coming up on empty settings that the next admin action would save over the real ones.

Back up the database as the primary copy. The snapshot files are a second copy on the server, kept current. .minecraft-auth/ is worth keeping too: losing it does not lose anything permanent, but every account has to go through a device-code sign-in again.

key and account in the registry are immutable, and the commands enforce it. account is the key prismarine-auth hashes for its token cache: changing it silently starts a fresh device-code flow against a different cache file, against an account nothing is signed in to. Remove the guild and add it again instead.

Per-guild channel overrides live in the registry, not in the audit channel setting — so removing a guild cannot leave an orphaned channel setting behind. officerChannelId and crossBridgeOfficer live there too, alongside crossBridge; see Officer chat. officerChannelId is the one channel field guilds may deliberately share — replies typed there are routed by guild tag.

Settings are read once at startup and held in memory; each change is written back whole. Editing a row by hand while the bot is running will be overwritten by the next change; stop the process first.

Never print or share these. .env holds a bot token and the database password, .minecraft-auth/ holds live Microsoft credentials, and the registry holds account addresses — which is why /guilds masks them in every reply.

Next

• Configuration
• Hypixel guilds
• Updating