CatRealm Self-Hosted Server

Welcome to the CatRealm self-hosting documentation. Get your own CatRealm chat server running in minutes — on Windows, Linux, or through a Pterodactyl panel.

CatRealm is an open-source, self-hostable chat platform with text channels, voice chat, roles, permissions, and more. These docs cover everything you need to deploy and configure your own instance.

Dependencies

CatRealm requires very few dependencies to run:

OS Support

Windows Server

The easiest way to get started on Windows — no terminal required.

Manual Install

git clone https://github.com/VanillaChan6571/CatRealm-SelfHostable-Server.git
cd CatRealm-SelfHostable-Server

Linux Server

Run CatRealm on any modern Linux distribution.

Auto Installer

The fastest way to install CatRealm on Linux is the hosted auto-installer:

bash <(curl -fsSL https://raw.githubusercontent.com/VanillaChan6571/CatRealm-SelfHostable-Server/refs/heads/main/catrealm-auto-installer.sh)

Manual Install

git clone https://github.com/VanillaChan6571/CatRealm-SelfHostable-Server.git
cd CatRealm-SelfHostable-Server

chmod +x Start.sh

./Start.sh

nano .env

Manual Installation

If you prefer to skip the launcher scripts:

npm install --omit=dev
cp .env.example .env
nano .env          # edit your configuration
node src/index.js  # start the server

Running with PM2 (Production)

For a persistent, production-grade setup, use PM2:

# Install PM2 globally
npm install -g pm2

# Start CatRealm
pm2 start src/index.js --name catrealm

# Auto-start on system reboot
pm2 startup
pm2 save

Pterodactyl Egg

CatRealm has an official Pterodactyl egg for easy panel-based hosting.

Hoster Setup

https://raw.githubusercontent.com/VanillaChan6571/CatRealm-SelfHostable-Server/main/egg-cat-realm-server.json

ENV Overview

CatRealm is configured entirely through environment variables in your .env file. Below is a full reference for every option.

Server

Core settings that define how your server presents itself.

# ── Server ────────────────────────────────────────────────────
PORT=40500
SERVER_NAME=My CatRealm Server
SERVER_DESCRIPTION=A cozy self-hosted realm

Security

Authentication and encryption settings.

# ── Security ──────────────────────────────────────────────────
JWT_SECRET=change-this-to-a-long-random-string
SECURE_MODE=0
# SECURE_MODE_KEY=    # auto-generated when SECURE_MODE=1

Registration

Control whether new users can sign up on your server.

# ── Registration ──────────────────────────────────────────────
REGISTRATION_OPEN=true

Database

CatRealm uses SQLite — no external database server needed.

# ── Database ──────────────────────────────────────────────────
DB_PATH=./data/catrealm.db

CORS

Controls which origins can make requests to your server's API.

# ── CORS ──────────────────────────────────────────────────────
CLIENT_URL=*
# Production example:
# CLIENT_URL=https://app.example.com

Uploads Directory

Paths where user-uploaded files are stored on disk.

# ── Uploads ───────────────────────────────────────────────────
UPLOADS_DIR=./data/uploads
UGC_IMAGES_DIR=./data/ugc/images

Default Local Avatar Image Local Accounts Only

Set a default avatar URL for newly created local accounts. If not set, users will have no avatar until they upload one.

# Optional: default avatar for new local accounts
DEFAULT_AVATAR_URL=https://cdn.example.com/default-avatar.png

Block Generic Usernames Decentral Only

Prevent users from registering with reserved or common usernames (e.g. "admin", "moderator"). Only applies to local (decentral) accounts.

# Block specific usernames from registration (local/decentral accounts only)
BLOCKED_USERNAMES=admin,moderator,official,support
# Or use a file (one username per line):
BLOCKED_USERNAMES_FILE=./blocked-usernames.txt

Server Mode

Controls what type of accounts are allowed to join your server.

# Server mode (optional — defaults to mixed)
# SERVER_MODE=mixed            # both local and central (default)
# SERVER_MODE=decentral_only   # local accounts only
# SERVER_MODE=central_only     # central accounts only

# Required for mixed/central_only:
# AUTH_SERVER_URL=https://auth.catrealm.app

Media Limits

Configure upload size limits for different types of media.

# ── Media Limits ──────────────────────────────────────────────
MEDIA_MAX_MB=20
AVATAR_MAX_MB=10
MAX_PINS=300
MENTION_ALIAS=@everyone

Voice Chat

CatRealm uses WebRTC for voice chat. STUN/TURN servers are needed for users behind NAT or firewalls.

# ── Voice Chat (TURN/STUN) ────────────────────────────────────
# TURN_MODE=fallback   # use public fallback TURN servers (default)
# TURN_MODE=custom     # use your own TURN server
# TURN_MODE=central    # use CatRealm central TURN server

# If TURN_MODE=custom:
# TURN_HOST=turn.example.com
# TURN_PORT=3478
# TURN_TLS_PORT=5349
# TURN_SECRET=your-turn-server-secret

Auto Update

When enabled, the startup launcher will pull the latest changes from your configured Git repository before starting the server.

# ── Auto Update ───────────────────────────────────────────────
AUTO_UPDATE=true
GIT_REPO=https://github.com/VanillaChan6571/CatRealm-SelfHostable-Server.git
GIT_BRANCH=main

SSL / HTTPS Guide

HTTPS is required to use the CatRealm web app from any device other than localhost. CatRealm has built-in SSL support powered by Let's Encrypt — no separate reverse proxy needed.

Auto SSL via Cloudflare DNS Recommended

This method uses the DNS-01 ACME challenge, which means port 80 does not need to be open. It's ideal for servers behind firewalls or NAT. You just need a domain pointed to Cloudflare and a Cloudflare API token.

1

Point your domain to Cloudflare

Ensure your domain (e.g. chat.example.com) has an A record in Cloudflare DNS pointing to your server's public IP. Set the proxy status to DNS only (gray cloud) for TURN/voice to work properly.

2

Create a Cloudflare API token

Follow the steps below in the Cloudflare dashboard:

1 Click your profile icon in the top-right corner

2 Select API Tokens from the left sidebar

3 Find Edit zone DNS and click Use template

4 Leave permissions as-is, then click Continue to summary

5 Review the summary and click Create Token

6 Copy your token — it will not be shown again

⚠️

Save the token immediately. Cloudflare will not show it again after you leave the page. If you lose it, you'll need to delete it and create a new one.

3

Add SSL variables to your .env

# Auto-SSL via Cloudflare DNS-01
SSL_DOMAIN=chat.example.com
SSL_EMAIL=[email protected]
SSL_DNS_PROVIDER=cloudflare
SSL_DNS_API_TOKEN=your-cloudflare-api-token

4

Restart the server

CatRealm will automatically request a certificate from Let's Encrypt using the Cloudflare DNS challenge. Once issued, the server will serve HTTPS on port 443 and HTTP on your configured PORT.

SSL via Certbot

If you prefer to manage certificates manually, you can obtain them with Certbot and provide the paths to CatRealm.

sudo apt update
sudo apt install -y certbot

sudo certbot certonly --standalone -d chat.example.com --email [email protected] --agree-tos

# Manual certificate paths
SSL_CERT_PATH=/etc/letsencrypt/live/chat.example.com/fullchain.pem
SSL_KEY_PATH=/etc/letsencrypt/live/chat.example.com/privkey.pem

# /etc/letsencrypt/renewal-hooks/post/catrealm.sh
#!/bin/bash
pm2 restart catrealm

chmod +x /etc/letsencrypt/renewal-hooks/post/catrealm.sh

Advanced

Advanced configuration for power users and production deployments.

Host a Custom TURN Server

WebRTC voice chat works peer-to-peer for most users. However, users behind strict NAT or corporate firewalls need a TURN server to relay audio. By default, CatRealm uses public fallback TURN servers. For better reliability and privacy, host your own with coturn.

What is TURN?

• STUN — helps users discover their public IP. Most voice connections use STUN only (peer-to-peer).
• TURN — relays voice traffic when direct peer-to-peer fails (users behind strict NAT/firewall). Only ~20–30% of users typically need TURN.

1. Install coturn

sudo apt update
sudo apt install -y coturn

# Enable the service
sudo sed -i 's/#TURNSERVER_ENABLED=1/TURNSERVER_ENABLED=1/' /etc/default/coturn

2. Generate a TURN secret

# Generate a random 32-byte secret
TURN_SECRET=$(openssl rand -hex 32)
echo "Save this secret: $TURN_SECRET"

3. Configure coturn

Edit /etc/turnserver.conf:

sudo nano /etc/turnserver.conf

Paste the following configuration (replace the placeholder values):

# Listening port
listening-port=3478

# Your server's public IP (find with: curl -4 ifconfig.me)
external-ip=YOUR_PUBLIC_IP

# Media relay port range
min-port=49152
max-port=65535

fingerprint
lt-cred-mech
use-auth-secret
static-auth-secret=YOUR_TURN_SECRET_HERE

realm=catrealm
log-file=/var/log/turnserver.log
no-loopback-peers

# Block private IP ranges from relay
denied-peer-ip=0.0.0.0-0.255.255.255
denied-peer-ip=10.0.0.0-10.255.255.255
denied-peer-ip=172.16.0.0-172.31.255.255
denied-peer-ip=192.168.0.0-192.168.255.255
denied-peer-ip=127.0.0.0-127.255.255.255

4. Open firewall ports

# TURN server port
sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp

# Media relay port range
sudo ufw allow 49152:65535/udp

5. Start coturn

sudo systemctl enable coturn
sudo systemctl start coturn
sudo systemctl status coturn

6. Configure CatRealm to use your TURN server

Add the following to your .env in CatRealm:

TURN_MODE=custom
TURN_HOST=turn.example.com
TURN_PORT=3478
TURN_TLS_PORT=5349
TURN_SECRET=your-turn-server-secret

Resource Usage

Security Notes

• The TURN secret is never exposed to clients — the server generates time-limited credentials.
• Private IP ranges are blocked from relay (see config above).
• For production, configure TLS on port 5349: uncomment cert= and pkey= in turnserver.conf.
• Remove verbose from the coturn config in production to reduce log noise.