Configuration

Most day-to-day settings live in the panel UI. A handful of infrastructure variables must be set in the compose environment before the backend starts; everything else can be managed from the panel.

Change a setting in the UI

This is always the first place to look. Every screen below validates input and saves immediately — except Admin → Environment, which asks for a restart when a change needs one.

Screen	What it controls
Admin → System	SMTP email, mod manager API keys (CurseForge/Modrinth), default interface language, and Auto Updater
Admin → Security	Rate limits, email verification, lockout policy, file-upload limits, and the panel MCP endpoint
Admin → Environment	Every environment variable the backend reads, with its source and a restart prompt when required
Admin → Theme	Panel identity (panel name, logo, favicon), brand colors, surfaces, and custom CSS
Admin → Databases	MySQL hosts used to provision databases for servers, plus Catalyst database health
Admin → Plugins	Installed plugins: permissions, configuration, enable/disable, updates
Admin → Marketplace	The Plugin marketplace (/admin/plugins/marketplace) — browse and install from the configured sources
Profile	Your own language, password, passkeys, and API keys

Mod manager API keys

Admin → System → Mod Manager API Keys stores the keys the Mod Manager uses to search and download mods, datapacks and modpacks. Keys are write-only in the panel: once saved, only the last four characters are shown.

1. Open Admin → System, section Mod Manager API Keys.
2. Paste the key into CurseForge API Key and/or Modrinth API Key and save.
3. Ask a user to open the Mod Manager tab and confirm the provider appears in the provider selector.

CurseForge requires a key for every request. Modrinth is hidden from the provider selector when its key is empty, so an unconfigured Modrinth key looks exactly like “the provider does not exist” rather than an error. If a user reports that a provider is missing from the Mod Manager, check this section first.

A key shared by many servers is rate limited by the provider; heavy use shows up as search returning fewer results or downloads failing intermittently.

Environment variables in the panel

Admin → Environment renders the backend’s own registry (catalyst-backend/src/lib/env-registry.ts): every variable it reads, with its category, where the current value comes from (Environment, Database or Default), and whether a restart is needed. A value saved there is stored in the database and applied on the next panel start — the page offers a Restart panel button, and Reset to .env drops the override.

Variables that have a dedicated editor are hidden from this page so each value has one home: the panel name under Theme, rate limits and console output under Security, update automation under System → Auto Updater, OIDC providers under Theme → Advanced, and marketplace sources in the Marketplace page.

Six variables are read before the backend can reach the database, so they are .env only (shown read-only in the panel): DATABASE_URL, NODE_ENV, PORT, POSTGRES_PASSWORD, TZ, and WORKERS. POSTGRES_PASSWORD, REDIS_PASSWORD, and BETTER_AUTH_SECRET are also the values the containers themselves start with, so change them in .env and recreate the stack:

cd catalyst-docker
nano .env
docker compose up -d

Environment reference

catalyst-docker/.env.example is the annotated template the installer copies. Docker ports, as written by the installer: FRONTEND_PORT=0.0.0.0:8080, BACKEND_PORT=127.0.0.1:3000, POSTGRES_PORT=127.0.0.1:5432. With no .env, compose falls back to FRONTEND_PORT=0.0.0.0:80. Redis is published on 127.0.0.1:6379 (loopback only) — the compose default REDIS_PORT is 127.0.0.1:6379, and commenting it out does not unpublish the port. To make Redis fully internal to the Docker network, add a ports: [] override for the redis service. See networking.

PUBLIC_URL is the single source of truth for the panel URL — it drives CORS, auth origins, and email links, and the installer derives PASSKEY_RP_ID from its hostname. networking covers the TLS and proxy side. Re-run the installer’s prompts to regenerate a configured .env with bash install.sh --reconfigure (installation).

NODE_ENV (development, production, test; default development) and SUSPENSION_DELETE_POLICY (block or allow) are enum-validated at startup: a wrong value exits the backend with Invalid environment configuration. LOG_LEVEL reaches pino only when NODE_ENV=production (otherwise info), an unrecognised BACKUP_STORAGE_MODE silently falls back to local, and a malformed PUBLIC_URL breaks CORS, auth origins, and email links at runtime instead of at startup. The suspension policy applies only while suspension is enforced, and only DELETE /api/servers/:id compares it literally — unset means deletion is allowed. The admin bulk delete uses SUSPENSION_DELETE_BLOCKED instead, which defaults to blocking.

Note

If the backend exits at startup with Invalid environment configuration, the [config] Environment variable validation failed lines above it name the variable. SUSPENSION_DELETE_POLICY=keep — the commented value in catalyst-docker/.env.example — is not accepted; use block or allow.

Rules

1. Do not edit the database by hand. Every supported change has a UI field, an API endpoint, or a documented variable. Raw SQL edits bypass validation and break upgrades (updating).
2. Keep secrets out of chat and screenshots. Database passwords, API keys, and node tokens live in your compose .env, never in docs or tickets.
3. Record what you changed. A one-line note (what, when, why) saves hours during the next incident.

Related

• Database and cache tuning: storage.
• TLS and proxy headers: networking.