Skip to content

getting-started.md

Latest commit

 

History

History
694 lines (497 loc) · 26.8 KB

getting-started.md

File metadata and controls

694 lines (497 loc) · 26.8 KB
Raw

Getting Started Guide

🎉 Welcome to Catalyst! This guide walks you through everything after installation — from your first login to running your first game server.

If you haven't installed the panel yet, hop over to the Quick Start (5 minutes) or the Installation Guide (full details).

Table of Contents

Before You Begin

Welcome! This guide assumes you already have the Catalyst panel running. If you haven't installed it yet, check out:

You'll also need:

  • Access to a node machine (can be the same server or a separate one) with:
    • Linux (Ubuntu 22.04+, Debian 12+, or similar)
    • Root or sudo access
    • containerd installed and running
    • At least 2 CPU cores and 2 GB RAM available for game servers

🎉 The panel is running — let's get you set up!

This guide walks you through everything after installation: logging in for the first time, setting up a node, deploying the agent, and creating your first game server.

Step 1: Initial Setup and Login

Production / Docker path (default)

  1. Open your browser to your PUBLIC_URL (for example http://localhost:8080, not bare :80 unless you changed FRONTEND_PORT).
  2. On a fresh install the panel requires Setup (/setup):
    1. Welcome
    2. Admin Account — email, username, password for the first administrator
    3. Appearance — branding/theme options
  3. Finish setup. Catalyst creates the Administrator role (*), assigns it to your user, and disables open self-registration.
  4. Sign in with Sign in using the credentials you just created.

You land on the dashboard overview.

Do not rely on seed accounts for production. Seed users exist only if you deliberately ran a seed script in a development environment.

Development seed path (optional)

If you ran pnpm run db:seed / db:seed:admin (or equivalent) in a dev environment, you may sign in with the seed admin:

  • Email: admin@example.com
  • Password: admin123

Change this password immediately. Seed credentials are not part of the Docker one-liner production path.

Registration after setup

Open registration is off after setup. Admins can re-enable it under Admin → Security. When enabled, new users use Create account with:

  • Email — unique
  • Username — 2–32 characters, unique
  • Password — minimum 8 characters (complexity rules apply)

New self-registered users receive the default User role (limited access). They do not become administrators.

Forgot Password Flow

If you forget your password after creating an account:

  1. On the login page, click Forgot Password?
  2. Enter the email address associated with your account.
  3. Click Send Reset Link.
  4. Check your email for the reset message.
  5. Click the link in the email and enter your new password.
  6. Sign in with the new password.

Note: Password recovery requires SMTP to be configured by your administrator. If you don't receive the email, contact your server admin to verify email settings.

Reset Password Page

After clicking the reset link, you'll be taken to the Reset Password page (/reset-password):

  1. The page validates the reset token (1-hour expiry, single-use only).
  2. Enter your new password (min 8 characters) and confirm it.
  3. Click Reset Password.
  4. You're redirected to the login page.

Security: Reset tokens use constant-time comparison to prevent timing attacks. Failed attempts are rate-limited.

Cross-Tab Session Synchronization

Catalyst automatically keeps your sessions synchronized across all open browser tabs:

  • When you log in to Catalyst in one tab, all other open tabs are automatically logged in.
  • When you log out from any tab, you are logged out of ALL tabs simultaneously.
  • When your session expires, all tabs are notified and redirect to the login page.
  • Password changes revoke all other sessions across all tabs.

This is powered by the BroadcastChannel API and localStorage event listeners, ensuring that even if a tab is in a different browser window, it will still receive session state updates within milliseconds.

Note: Cross-tab sync only works within the same browser and the same Catalyst panel. It does not sync across different browsers or different panel instances.

Step 2: Configure Your Profile

After your first login, update your admin profile:

  1. Click your avatar or username in the top-right corner
  2. Navigate to Profile Settings
  3. Update your display name, first name, and last name
  4. Upload an avatar image (JPEG, PNG, GIF, or WebP, max 2 MB). Note: SVG files are not accepted due to XSS risk.

Enable Two-Factor Authentication

It's strongly recommended to enable 2FA for admin accounts:

  1. Go to Profile (sidebar user entry → /profile) → Security → Two-Factor Authentication. (There is no standalone /two-factor page — that route redirects to /login; 2FA setup is inline.)
  2. Click Enable 2FA.
  3. Enter your password to confirm your identity.
  4. A QR code is displayed — open your authenticator app (Google Authenticator, Authy, Microsoft Authenticator, etc.) and scan the code.
    • The QR code contains a TOTP secret encoded as otpauth://totp/ URI.
    • Your app will start generating 6-digit codes that change every 30 seconds.
  5. Enter the 6-digit verification code from your app to confirm setup.
  6. Save your backup codes — 10 one-time codes are provided. Store them in a password manager, printed document, or other secure location.
    • Each backup code can be used only once.
    • If you lose your authenticator device, backup codes are your only way to log in.

2FA Page Features

The 2FA Setup page (/two-factor) includes:

Feature Description
Password Verification You must enter your current password before enabling 2FA
QR Code Display Scannable TOTP secret for authenticator apps
Verification Code Input Enter the 6-digit code from your app to confirm
Backup Code Generation 10 one-time codes displayed after successful verification
Trust Device Checkbox "Trust this device for 30 days" option during verification
Revoke Trusted Devices View and revoke trusted devices at any time
Disable 2FA Toggle 2FA on/off with current code verification
Generate New Backup Codes Invalidate old codes and generate a new set

Trust Device Option

During 2FA verification, you'll see a "Trust this device for 30 days" checkbox:

  • When checked, future logins from the same device/browser won't require a 2FA code for 30 days.
  • Device identity is verified via a cryptographic browser fingerprint (not just cookies).
  • Each trusted device shows its registration date and fingerprint hash.
  • You can revoke a trusted device at any time by clicking Revoke Trust next to it.
  • Revoking a trusted device immediately requires 2FA on the next login attempt.

Set Up Passkeys (WebAuthn)

For passwordless login support:

  1. Go to Profile → Security → Passkeys.
  2. Click Add Passkey.
  3. Enter a name for the passkey (e.g., "MacBook Touch ID", "YubiKey").
  4. Click Continue.
  5. Follow your browser's biometric prompt (Face ID, Touch ID, Windows Hello, or security key).

2-step registration: Passkeys use a 2-step process — first you name the passkey, then you authenticate. This prevents phishing by committing to the name before biometric verification.

Change Your Password

  1. Go to Profile → Security → Change Password
  2. Enter your current password
  3. Enter and confirm the new password
  4. Optionally check Revoke other sessions to sign out all other devices

Step 3: Create a Location

Locations are logical groupings for your nodes (for example data centers or regions).

  1. Navigate to Admin → Nodes.
  2. Open Locations (modal from the Nodes page — there is no /admin/locations route).
  3. Create a location with a Name (for example US East 1) and optional description.
  4. Save.

Locations organize nodes and help users choose where to deploy servers.

Step 4: Create a Node

A node is a physical or virtual machine that runs game server containers via the Catalyst agent.

  1. Navigate to Admin → Nodes.
  2. Click Register Node (UI label; not “Create Node”).
  3. Fill in the required fields:
Field Description Example
Name Unique identifier for the node node-1
Description Optional description Main game server node
Location The location from Step 4 US East 1
Hostname System hostname of the machine node-1.example.com
Public Address IP address or hostname reachable from the panel 192.168.1.100
Max Memory (MB) Total RAM available for servers 32000
Max CPU Cores Total CPU cores available 16
Server Data Dir (Optional) Override data directory path /var/lib/catalyst
  1. Click Register node

After creation, the node will appear in the list with an offline status until the agent connects.

Node Allocations

Allocations define the IP:port combinations available on a node. They are managed on a separate page, not in the creation wizard:

  1. Select the node from the list
  2. Click Allocations (opens /admin/nodes/:nodeId/allocations)
  3. Click Add Allocation
  4. Enter the IP address and port range:
    • IP: 192.168.1.100 or a CIDR range like 10.0.0.0/24
    • Ports: 25565-25585 (supports individual ports, ranges, and comma-separated values)
  5. Click Save

When creating a server, you'll assign it an allocation from the available pool.

Generate Agent API Key

The agent needs an API key to authenticate with the panel. Node details has no separate Agent tab — key management lives on the node details page:

  1. Select the node
  2. Click Generate Key (or Regenerate Key if one exists)
  3. Copy the API key — you'll need it for the agent configuration

Important: The API key is only shown once. Store it securely.

Step 5: Deploy the Agent

The Catalyst agent is a Rust binary that runs on each node. It manages containers using containerd and communicates with the panel over WebSocket.

System Requirements

On each node machine:

  • OS: Linux (Ubuntu 22.04+, Debian 12+, or similar)
  • containerd installed and running (with CRI plugin)
  • Root access (required for containerd socket access and network management)
  • Ports: Agent needs outbound access to the panel's WebSocket endpoint (/ws)
  • Network: The panel must be able to reach the node's public address

One-Click Deployment

The easiest way to deploy the agent:

  1. In the panel, open the node details page and click Deploy
  2. Click Generate Deployment Token if needed
  3. This creates a one-time deployment URL (valid for 24 hours) and an API key
  4. On the node machine, run the deployment command shown in the dialog (form: curl -s 'deployUrl?apiKey=...' | sudo bash -x; use Copy to grab it exactly), for example: 
    curl -s 'https://your-panel.com/api/deploy/YOUR_TOKEN?apiKey=...' | sudo bash -x

The deployment script will:

  • Install the agent binary
  • Generate config.toml with the correct settings
  • Set up systemd service
  • Start the agent

Manual Agent Setup

If you prefer manual installation:

  1. Build or download the agent binary:

    # From source
cd catalyst-agent
cargo build --release
sudo cp target/release/catalyst-agent /usr/local/bin/

  2. Create the configuration file at /opt/catalyst-agent/config.toml (the path shown in the panel; CATALYST_CONFIG_PATH overrides it):

    [server]
backend_url = "wss://panel.example.com/ws"
node_id = "your-node-uuid"
api_key = "your-api-key-from-panel"
hostname = "node-1"
data_dir = "/var/lib/catalyst"
max_connections = 100

[containerd]
socket_path = "/run/containerd/containerd.sock"
namespace = "catalyst"

[logging]
level = "info"
format = "json"

  3. Create a systemd service:

    [Unit]
Description=Catalyst Agent
After=network-online.target containerd.service
Requires=containerd.service

[Service]
Type=simple
ExecStart=/usr/local/bin/catalyst-agent --config /opt/catalyst-agent/config.toml
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target

  4. Start the agent:

    sudo systemctl daemon-reload
sudo systemctl enable --now catalyst-agent

Networking Configuration

The agent supports multiple networking modes for game server containers:

macvlan (Recommended for Game Servers)

macvlan gives each container its own MAC address and IP on the network, which is essential for games that need direct IP access (e.g., Minecraft).

Add network configuration to the agent's config.toml:

[[networking.networks]]
name = "mc-lan-static"
interface = "eth0"
cidr = "10.5.5.0/24"
gateway = "10.5.5.1"
range_start = "10.5.5.50"
range_end = "10.5.5.200"

If no networks are configured, the agent will automatically create a default network based on the primary interface.

Host Networking

For servers that need to bind directly to the host's network interfaces:

When creating a server, set the networkMode to host. The server will use the node's public IP address directly.

Bridge (Default)

Standard Docker bridge networking. The panel handles port forwarding from the host to the container.

Step 6: Server Templates

Templates define how game servers are configured and deployed. Catalyst comes with built-in templates and supports custom ones.

Using Built-in Templates

After seeding, you'll have two default templates:

Minecraft Server (Paper)

Setting Value
Image Eclipse Temurin 21 JRE
Default RAM 1024 MB
Default CPU 2 cores
Port 25565
Features Auto-restart, mod manager, plugin manager, file editor

Template Variables:

Variable Default Description
MEMORY 1024 Amount of RAM in MB (512–16384)
MEMORY_XMS 512 Initial heap size in MB (256–8192)
PORT 25565 Server port (1024–65535)
VERSION 1.21.11 Minecraft version to install
BUILD (latest) Paper build number (empty = latest)

Node.js Bot (Git Repository)

Setting Value
Image Node.js 20 (Debian Slim)
Default RAM 1024 MB
Default CPU 1 core
Port 3000
Features Auto-restart, Git-based deployment

Template Variables:

Variable Default Description
GIT_REPO (required) Git clone URL
GIT_BRANCH main Branch or tag to deploy
NPM_INSTALL_COMMAND npm install --no-audit --no-fund Dependency install command
START_COMMAND npm start Fallback startup command
BOT_START_COMMAND (empty) Optional startup command override
PORT 3000 Application listen port (1024–65535)
NODE_ENV production Node.js runtime environment

Understanding Template Variables

Templates use {{VARIABLE_NAME}} syntax for interpolation in startup commands and install scripts. When you create a server, the panel replaces these placeholders with the values you provide.

Example — Minecraft startup command:

java -Xms{{MEMORY_XMS}}M -Xmx{{MEMORY}}M -jar paper.jar nogui

With MEMORY=2048 and MEMORY_XMS=1024, this becomes:

java -Xms1024M -Xmx2048M -jar paper.jar nogui

Built-in placeholders available in install scripts:

Placeholder Description
{{SERVER_DIR}} Absolute path to the server data directory
{{VARIABLE_NAME}} Any user-defined template variable
{{TEMPLATE_IMAGE}} The container image specified in the template

Step 7: Create Your First Server

  1. Navigate to Servers → New server (the dashboard Create Server shortcut links to /servers)
  2. Fill in the server details:

Basic Settings

Field Description Example
Name Display name for your server My Minecraft Server
Description Optional description Survival server for friends
Node The node to deploy on node-1
Template Server template Minecraft Server (Paper)

Resource Allocation

Field Description Example
Memory (MB) RAM to allocate (backend range 512–131072) 2048
CPU Cores CPU cores to allocate (backend range 1–128) 2
Disk (MB) Disk space to allocate (backend range 1024–1048576) 10240

Optional extras on the same step: Swap (MB), Backup (MB), and Database Allocation (blank = provider defaults). If the template defines Image Variants, pick one on the details step.

Network Settings

The creation wizard offers two Network Modes: Host (port mapping) and Macvlan.

Field Description Example
Primary Allocation Allocation picked from the node's pool (host mode) 192.168.1.100:25565
Primary Port Read-only in host mode — populated from the allocation 25565
Additional Port Bindings Extra allocation → container-port mappings 25566
Interface / IP Allocation Macvlan interface + Auto-assign eth0

Template Variables

Fill in the template-specific variables (e.g., for Minecraft: Memory, Version, Build). Required fields are marked with an asterisk.

  1. Click Create server

The server is created and installation starts immediately — you land on /servers/:id/console. The server is not left stopped waiting for a manual install.

Accepting an Invite (Optional)

If someone invited you to a server, you'll receive an invite link:

For existing users:

  1. Click the invite link.
  2. Log in if prompted.
  3. Click Accept Invite on the invite page.
  4. You'll gain access to the invited server.

For new users:

  1. Click the invite link.
  2. You'll be taken to the registration page with your email pre-filled.
  3. Fill in:
    • Username — your desired username (min 3 characters)
    • Password — your password (min 8 characters)
  4. Click Register.
  5. You'll automatically gain access to the invited server after registration.

Note: The email on the invite cannot be changed during registration. If you need a different email, contact the person who sent the invite.

Step 8: Installation (usually automatic)

Creating a server starts installation immediately in typical flows — you usually do not click a separate Install button after create.

While installing, the agent:

  • Pulls the container image
  • Creates the server data directory
  • Runs the template install script in a temporary container
  • Downloads game files (for example Paper.jar for Minecraft)
  • Writes default configuration files

Watch progress on the Console tab. For Minecraft, installation typically fetches the Paper jar and creates default server.properties / eula.txt.

If installation fails or you need a clean reinstall:

  1. Open the server detail page
  2. Use Admin → Reinstall (or the reinstall control your role exposes)
  3. Confirm — reinstall wipes server data and re-runs the install script

Warning: Reinstall is destructive. Back up first if you need existing files.

Step 9: Access the Console

The real-time console lets you interact with your server:

  1. Go to your server's detail page
  2. Click the Console tab
  3. The console shows real-time server output via WebSocket
  4. Type commands in the input field and press Enter to send them

Console features:

  • Real-time output streaming (WebSocket)
  • Command history (use arrow keys)
  • Scroll through past output
  • The console buffer is configurable via CONSOLE_OUTPUT_BYTE_LIMIT_BYTES (default: 256 KB)

Common Minecraft console commands:

help                   — Show available commands
list                   — List online players
op <username>          — Grant operator status
whitelist add <player> — Add player to whitelist
stop                   — Stop the server gracefully

Step 10: Basic Server Management

Start / Stop / Restart

Use the control buttons on the server page:

Action Description
Start Boot the server container
Stop Gracefully stop (sends the stop command, then SIGTERM)
Restart Stop and start the server
Kill Force-stop (sends SIGKILL immediately)

File Manager

Access your server files through the web UI:

  1. Go to your server → Files tab
  2. Browse the server directory structure
  3. You can:
    • Upload files (drag and drop or click to select)
    • Download files
    • Edit text files directly in the browser
    • Create new files and directories
    • Delete files and directories
    • Compress / decompress archives (.tar.gz)
    • Rename files and directories

SFTP Access

For SFTP access (agent-hosted on the game node):

  1. Open the server → SFTP tab (or connection details from the UI)
  2. Generate or copy the SFTP token from the panel (GET /api/sftp/connection-info)
  3. Connect with your SFTP client using the values the panel shows: 
    Host: <node public address or hostname>
Port: <node SFTP port, often 2022>
Username: <server-id>          # not your panel username
Password: sftp_<token>         # opaque token, not a JWT

Backups

Create and manage server backups:

  1. Go to your server → Backups tab
  2. Click Create backup (button label is sentence-case)
  3. Backups can be stored locally or on S3 (configured per-server in Backups → storage settings; hidden when allocation is zero)
  4. Download existing backups or restore them to the server

Server Settings

Configure your server across two tabs:

  • Settings: rename the server, update description, adjust memory/CPU/disk
  • Configuration: edit template (startup) variables
  • Admin (owner or admin-write/server-delete holders): node transfer, ownership transfer, port allocations, restart policy, suspension, archive/restore, delete, reinstall

Next Steps

Congratulations — you now have a fully working Catalyst setup with a running game server! 🎉

Here's where to go next:

Essential Admin Pages

  • System Configuration (/admin/system) — SMTP settings, Mod Manager API keys, auto-updater, platform health dashboard
  • Security Settings (/admin/security) — rate limits, lockout policy, file tunnel security, brute-force protection, lockout viewer
  • System Errors (/admin/system-errors) — client-side error reporting dashboard for debugging frontend issues
  • Theme Settings (/admin/theme-settings) — panel branding, colors, custom CSS, light/dark mode
  • Database Hosts (/admin/database) — configure remote database servers for per-server provisioning
  • System-wide Alerts (/admin/alerts) — create and manage platform-level alert rules
  • Migration Tool (/admin/migration) — migrate from Pterodactyl Panel to Catalyst
  • Audit Logs (/admin/audit-logs) — system-wide activity trail with filtering, CSV export, and 15-second auto-refresh

Node & Template Details

  • Node Details (/admin/nodes/:nodeId) — view live metrics (CPU, memory, disk), server summary, allocation management, agent health
  • Template Details (/admin/templates/:templateId) — edit template variables, configuration, and features

Server Management Features

  • Server Transfer Ownership — transfer server ownership to another user (Settings → Transfer Ownership)
  • Server Suspension — admins can suspend/resume servers temporarily
  • Archive & Restore — preserve servers without deleting them (Admin tab)
  • File Editor — edit text files directly in the browser with save/cancel and dirty state tracking
  • Console Filters — toggle visibility of stdout (green), stderr (red), system (blue), and stdin (yellow) streams

Advanced Features

  • Cross-Tab Session Sync — automatically synced across all browser tabs via BroadcastChannel API
  • Brute Force Protection — rate limiting, IP blocking, email lockout, and lockout viewer
  • Invites Page (/invites/:token) — accept invites for existing users or register + accept for new users
  • API Keys — create scoped API keys with rate limits and expiration
  • Mod Manager — browse and install mods from CurseForge, Modrinth, and Paper
  • Plugin Manager — browse and install plugins from Modrinth, Spigot, and Paper

📖 Related Documentation

Guide For You If...
Quick Start You haven't installed Catalyst yet
Installation Guide You want full installation details
Docker Setup You need Docker Compose reference
Admin Guide You manage users, roles, and system config
Agent Guide You need advanced agent configuration
API Reference You're building integrations
Automation Guide You want scheduled tasks, webhooks, or plugins
User Guide You manage servers day-to-day
Architecture Overview You want to understand how Catalyst works
Troubleshooting Something went wrong

Part of the Catalyst Documentation. Last updated: 2026-05-11