304 lines
11 KiB
Markdown
304 lines
11 KiB
Markdown
# Feature Request: Server Command Center Rebuild
|
|
|
|
**Date:** 2026-04-14
|
|
**Topic:** Rebuild Trinity Console server module into a full server command center
|
|
**Priority:** HIGH — post-launch week, target build start April 15+
|
|
**Filed by:** Chronicler #87
|
|
**Scope:** Large — multiple new files, DB migration, new npm dependency
|
|
|
|
---
|
|
|
|
## Background
|
|
|
|
The current server matrix page (`/admin/servers`) is functional but minimal:
|
|
- Shows online/offline, whitelist status, last sync, Discord channel status
|
|
- Sync Now + Toggle Whitelist buttons only
|
|
- Discord channel detection is broken for many servers (slug derivation from full name fails)
|
|
- No power controls, no restart scheduling, no createserver/delserver from UI
|
|
- `_matrix_body.ejs` duplicates all card HTML inline instead of using `_server_card.ejs`
|
|
|
|
Michael wants this page to become a **Server Command Center** — the single place to manage every aspect of every game server without touching the Pterodactyl panel UI.
|
|
|
|
---
|
|
|
|
## Session Context (Chronicler #87, April 13-14)
|
|
|
|
Tonight we:
|
|
- Discovered all Discord channel detection is broken due to slug derivation failures
|
|
(e.g. "All the Mods 10: To the Sky" → code generates `all-the-mods-10-to-the-sky`, Discord has `atm10-tts`)
|
|
- Designed the `short_name` system to fix this permanently
|
|
- Added Pterodactyl Admin API key to Arbiter `.env` and ops manual
|
|
- Added Uptime Kuma API key to Arbiter `.env`
|
|
- Confirmed Uptime Kuma 2.1.0 uses Socket.IO (not REST) for monitor management
|
|
- Established that `/createserver` and `/delserver` move to Trinity Console buttons (slash commands remain as fallback only)
|
|
- Confirmed 5 Discord channels per server: chat, in-game, forum, status, voice
|
|
|
|
---
|
|
|
|
## New Environment Variables (already added to `/opt/arbiter-3.0/.env`)
|
|
|
|
```
|
|
UPTIME_KUMA_URL=http://localhost:3001
|
|
UPTIME_KUMA_API_KEY=uk2_-iM8Trb4ftJCedpv2Kcz2JRSD49Zrv-gbNkVyh87
|
|
PANEL_ADMIN_KEY=ptla_4eKCnPBofAmvLDjouTGS5OagDpIra58nRetjnXOeoh5
|
|
```
|
|
|
|
Note: `PANEL_CLIENT_KEY` and `PANEL_APPLICATION_KEY` already exist in `.env`.
|
|
Use `PANEL_ADMIN_KEY` for power actions and application-level calls.
|
|
|
|
---
|
|
|
|
## Part 1: Database Migration
|
|
|
|
### New table: `server_config`
|
|
|
|
```sql
|
|
CREATE TABLE IF NOT EXISTS server_config (
|
|
server_identifier VARCHAR(36) PRIMARY KEY,
|
|
short_name VARCHAR(64) UNIQUE,
|
|
short_name_locked BOOLEAN DEFAULT false,
|
|
display_name VARCHAR(128),
|
|
restart_enabled BOOLEAN DEFAULT true,
|
|
restart_offset_minutes INTEGER DEFAULT 0,
|
|
node VARCHAR(8),
|
|
pterodactyl_name VARCHAR(128),
|
|
created_at TIMESTAMP DEFAULT NOW(),
|
|
updated_at TIMESTAMP DEFAULT NOW()
|
|
);
|
|
```
|
|
|
|
`restart_enabled` and `restart_offset_minutes` are for Task #94 (Global Restart Scheduler) — include now, use later.
|
|
|
|
---
|
|
|
|
## Part 2: New npm Dependency
|
|
|
|
```bash
|
|
npm install uptime-kuma-api
|
|
```
|
|
|
|
This is the official Socket.IO wrapper for Uptime Kuma 2.x.
|
|
REST API only exposes status pages — monitor CRUD requires Socket.IO.
|
|
|
|
---
|
|
|
|
## Part 3: New Service Files
|
|
|
|
### `src/services/uptimeKuma.js`
|
|
|
|
Wrapper around `uptime-kuma-api`. Must handle:
|
|
- Connect/disconnect lifecycle (don't leave connections open)
|
|
- `createMonitor(name, hostname, port, discordChannelId)` — creates a Game monitor type, sets Discord notification to the status channel
|
|
- `deleteMonitor(name)` — finds by name, deletes
|
|
- Error handling if Kuma is unreachable (don't crash createserver)
|
|
|
|
Monitor config to use:
|
|
- Type: `port` (TCP port check, works for Minecraft)
|
|
- Interval: 60 seconds
|
|
- Name format: `{pterodactyl_name} - {node}` (matches existing monitors e.g. "Stoneblock 4 - TX")
|
|
- Notification: Discord webhook to the `{short_name}-status` channel
|
|
|
|
**Important:** Look at existing monitors in Uptime Kuma to match the exact format.
|
|
Run this to see existing monitor names:
|
|
```bash
|
|
# Check existing monitor names via Kuma API
|
|
```
|
|
|
|
### `src/services/pterodactyl.js`
|
|
|
|
Consolidate Pterodactyl API calls. Must handle:
|
|
- `powerAction(identifier, signal)` — start/stop/restart/kill
|
|
- `sendCommand(identifier, command)` — send console command
|
|
- `getServerResources(identifier)` — CPU, RAM, player count (via SFTP query or resources endpoint)
|
|
- Uses `PANEL_CLIENT_KEY` for client endpoints, `PANEL_ADMIN_KEY` for application endpoints
|
|
|
|
---
|
|
|
|
## Part 4: Backend Route Changes
|
|
|
|
### `src/routes/admin/servers.js` — major additions
|
|
|
|
#### POST `/:identifier/set-short-name`
|
|
- Validates `short_name` is URL-safe (lowercase, hyphens, numbers only)
|
|
- Checks uniqueness against `server_config` table
|
|
- If not locked: saves to DB, sets `short_name_locked = false`
|
|
- Returns updated card HTML via HTMX
|
|
|
|
#### POST `/:identifier/lock-short-name`
|
|
- Sets `short_name_locked = true` — **IRREVERSIBLE**
|
|
- Returns updated card HTML (lock button disappears, field becomes read-only)
|
|
|
|
#### POST `/:identifier/createserver`
|
|
- Requires `short_name_locked = true` — reject if not
|
|
- Creates Discord category: `🎮 {pterodactyl_name}`
|
|
- Creates 5 channels under category:
|
|
- `{short_name}-chat` (text)
|
|
- `{short_name}-in-game` (text)
|
|
- `{short_name}-forum` (forum)
|
|
- `{short_name}-status` (text — Uptime Kuma posts here)
|
|
- `{pterodactyl_name}` (voice)
|
|
- Creates Uptime Kuma monitor linked to status channel
|
|
- Returns success/error to card
|
|
|
|
#### POST `/:identifier/delserver`
|
|
- Confirmation required (HTMX confirm dialog)
|
|
- Deletes all 5 channels + category from Discord
|
|
- Deletes Uptime Kuma monitor
|
|
- Does NOT delete `server_config` row (keep history)
|
|
- Does NOT touch Pterodactyl (server stays in panel)
|
|
|
|
#### POST `/:identifier/power`
|
|
- Body: `{ signal: 'start' | 'stop' | 'restart' | 'kill' }`
|
|
- Calls `pterodactyl.powerAction()`
|
|
- Returns inline status to card
|
|
|
|
#### POST `/:identifier/console`
|
|
- Body: `{ command: string }`
|
|
- Calls `pterodactyl.sendCommand()`
|
|
- Used for the restart warning title/tellraw commands
|
|
|
|
---
|
|
|
|
## Part 5: View Changes
|
|
|
|
### `src/views/admin/servers/_server_card.ejs` — full rebuild
|
|
|
|
Each card should display:
|
|
|
|
**Header row:**
|
|
- Server name (bold)
|
|
- Node badge (🔥 TX1 or ❄️ NC1)
|
|
- Online/offline pill (green pulse or gray)
|
|
|
|
**Short name section (shown if not locked):**
|
|
- Text input: "Discord short name (e.g. atm10-tts)"
|
|
- "Save" button → `hx-post="/:id/set-short-name"`
|
|
- "Lock In" button (red, confirm dialog) → `hx-post="/:id/lock-short-name"`
|
|
- Warning: "⚠️ Once locked, this cannot be changed"
|
|
|
|
**Short name section (shown if locked):**
|
|
- Shows `short-name` as read-only badge
|
|
- No edit option
|
|
|
|
**Stats row (2-col grid):**
|
|
- Whitelist: ✅ Enabled / 🔓 Disabled
|
|
- Last Sync: timestamp
|
|
|
|
**Discord channels status:**
|
|
- If locked: show each of 5 channels with ✅/❌
|
|
- If not locked: show "Set short name to enable channel detection"
|
|
|
|
**Action buttons:**
|
|
- ⚡ Sync Now
|
|
- Toggle Whitelist
|
|
- 🚀 Create Server (Discord) — only if locked, only if channels missing
|
|
- 🗑️ Delete Server (Discord) — only if channels exist, red, confirm required
|
|
- Power: ▶️ Start | ⏹ Stop | 🔄 Restart (only if online status known)
|
|
|
|
### `src/views/admin/servers/_matrix_body.ejs`
|
|
|
|
Refactor to use `<%- include('./_server_card', { server }) %>` instead of duplicating card HTML.
|
|
|
|
---
|
|
|
|
## Part 6: Discord Channel Detection Fix
|
|
|
|
Update `checkServerChannels()` in `servers.js` to use `short_name` from `server_config` instead of deriving from the full server name.
|
|
|
|
```javascript
|
|
// NEW: use short_name from DB
|
|
function checkServerChannels(shortName, serverName, allChannels) {
|
|
if (!shortName) return { missing: [], found: [], complete: false, unconfigured: true };
|
|
|
|
const expectedChannels = [
|
|
{ name: `${shortName}-chat`, type: 'text' },
|
|
{ name: `${shortName}-in-game`, type: 'text' },
|
|
{ name: `${shortName}-forum`, type: 'forum' },
|
|
{ name: `${shortName}-status`, type: 'text' },
|
|
{ name: serverName.split(' - ')[0].replace(/\s*\([^)]*\)/g, '').trim(), type: 'voice' }
|
|
];
|
|
// ... rest of detection logic
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Part 7: Existing Short Names to Pre-Populate
|
|
|
|
These are already confirmed from Discord channel audit (Chronicler #87):
|
|
|
|
| Pterodactyl Name | short_name | Node |
|
|
|-----------------|------------|------|
|
|
| All the Mods 10: To the Sky | atm10-tts | NC1 |
|
|
| All the Mons | all-the-mons | NC1 |
|
|
| Mythcraft 5 | mythcraft-5 | NC1 |
|
|
| All of Create (Creative) | all-of-create | NC1 |
|
|
| DeceasedCraft | deceasedcraft | NC1 |
|
|
| Sneak's Pirate Pack | sneaks-pirate-pack | NC1 |
|
|
| Otherworld [Dungeons & Dragons] | otherworld | NC1 |
|
|
| Farm Crossing 6 | farm-crossing-6 | NC1 |
|
|
| Homestead - A Cozy Survival Experience | homestead | NC1 |
|
|
| Stoneblock 4 | stoneblock-4 | TX1 |
|
|
| Society: Sunlit Valley | society-sunlit-valley | TX1 |
|
|
| Submerged 2 | submerged-2 | TX1 |
|
|
| Beyond Depth | beyond-depth | TX1 |
|
|
| Beyond Ascension | beyond-ascension | TX1 |
|
|
| Cottage Witch | cottage-witch | TX1 |
|
|
| All The Mons (Private) - TX | all-the-mons-private | TX1 |
|
|
| Wold's Vaults | wolds-vaults | TX1 |
|
|
|
|
Write a migration script that pre-populates `server_config` with these AND sets `short_name_locked = true` for all of them — they're already live in Discord, locking is appropriate.
|
|
|
|
Farm Crossing 6 is missing its `-status` channel — note this in the card UI so Michael can run createserver for just that channel (or we handle partial channel creation).
|
|
|
|
---
|
|
|
|
## Part 8: Files to Create/Modify
|
|
|
|
| File | Action |
|
|
|------|--------|
|
|
| `src/services/uptimeKuma.js` | **NEW** |
|
|
| `src/services/pterodactyl.js` | **NEW** |
|
|
| `src/routes/admin/servers.js` | **MODIFY** (major) |
|
|
| `src/views/admin/servers/_server_card.ejs` | **REBUILD** |
|
|
| `src/views/admin/servers/_matrix_body.ejs` | **REFACTOR** |
|
|
| `package.json` | **MODIFY** (add uptime-kuma-api) |
|
|
| `migrations/add-server-config.sql` | **NEW** |
|
|
| `migrations/seed-server-config.sql` | **NEW** |
|
|
|
|
---
|
|
|
|
## Part 9: What NOT to Build Yet
|
|
|
|
These are on the roadmap but NOT in this request:
|
|
|
|
- **Restart scheduler UI** — Task #94, separate request after this lands
|
|
- **Console command input on card** — Phase 2
|
|
- **RAM/CPU/player count display** — Phase 2
|
|
- **Partial channel creation** (create only missing channels) — Phase 2
|
|
|
|
Build the foundation clean. Phase 2 adds to it.
|
|
|
|
---
|
|
|
|
## Deployment Notes
|
|
|
|
- Run `npm install` after adding `uptime-kuma-api`
|
|
- Run migration SQL before deploying new code
|
|
- Pre-populate `server_config` with seed data before first load
|
|
- Test `createserver` on a non-live server first (use All of Create Creative as test bed — it has no subscribers)
|
|
- Standard deploy pattern: clone to `/tmp`, rsync to `/opt/arbiter-3.0`, restart `arbiter-3`
|
|
|
|
---
|
|
|
|
## Questions for Code Before Starting
|
|
|
|
1. Does `uptime-kuma-api` npm package support Uptime Kuma 2.1.0? Verify before using.
|
|
2. What's the correct Discord category structure — should all 5 channels live under one `🎮 {name}` category, or does the voice channel go in a separate voice category?
|
|
3. Farm Crossing 6 is missing only the `-status` channel — should `createserver` handle partial creation (only create missing channels) or always create all 5?
|
|
|
|
---
|
|
|
|
*Filed by Chronicler #87 — April 14, 2026*
|
|
*This is the foundation of the Server Command Center. Build it clean.*
|