Skip to content
CatalystCatalyst Docs

Storage

Panel host

Section titled “Panel host”

The bundled stack keeps four named Docker volumes: catalyst-postgres-data (the database), catalyst-server-data, catalyst-backup-data (backups), and catalyst-plugin-data.

  • PostgreSQL is the system of record — users, servers, audit logs, settings. Back it up continuously; see backups and disaster recovery.
  • Backups are stored in the catalyst-backup-data volume (/var/lib/catalyst/backups) by default. Choosing the storage backend (BACKUP_STORAGE_MODE) and its retention is covered in backups.
  • Redis is an ephemeral cache and coordination layer: config caches, cross-instance invalidation, realtime fan-out, agent command relay, shared rate-limit counters, and locks. It has no volume, no AOF/RDB, and no persistence by design — sessions live in PostgreSQL, not Redis. Losing Redis means slower requests and degraded realtime, never lost data; the backend falls back to the database when it is down (catalyst-backend/src/lib/redis.ts).
  • Keep database volumes on fast, monitored disks separate from bulk backup storage.

Nodes

Section titled “Nodes”

Each server’s data lives in a per-server loop-mounted disk image whose size is the server’s disk allocation — that is how Catalyst enforces a per-server disk quota. A node that cannot mount images (an unprivileged LXC, for example) falls back to plain data directories with no quota enforcement (requirements).

Node disk fills with, in rough order: game server images and data, container images, logs, and temporary backup staging. Plan for it:

  1. Separate filesystems (or at least quotas) for server data vs. images/logs, so a log flood cannot wedge game I/O.
  2. Image pruning on a schedule — old game images accumulate silently.
  3. Backup retention that matches disk. The agent stages each archive under its data root before it is transferred to the panel, S3, or SFTP, so large backups still need node headroom.
  4. Alert at 80%, act at 90%. A full disk stops servers ugly. Wire node disk into monitoring.

Rules

Section titled “Rules”
  • Never let any volume hit 100%. Ever. This is the single most preventable cause of “everything broke at 3 AM”.
  • Test restores, not just backups — an untested snapshot is a hope.
Section titled “Related”