Admin Guide

Administration panel and features

Admin Guide

Complete guide for administrators of the DBK Gaming Platform.

Table of Contents

Creating Admin Accounts

Initial Setup

Admins must be created manually using the admin creation script.

Step 1: Find Discord User ID

  1. Enable Developer Mode in Discord (User Settings → Advanced → Developer Mode)
  2. Right-click on the user and select "Copy ID"

Step 2: Create Admin User

# Development (SQLite)
node scripts/create-admin.js DISCORD_USER_ID Username

# Production (PostgreSQL)
npx dotenv -e .env.production -- node scripts/create-admin.js DISCORD_USER_ID Username

Example:

node scripts/create-admin.js 123456789012345678 AdminUser

Step 3: Verify Admin Creation

The script will output:

Admin user created successfully:
  ID: 123456789012345678
  Username: AdminUser
  Role: ADMIN

Adding Admins via Environment Variables

You can pre-configure admin Discord IDs in the environment file:

.env.development or .env.production:

ADMIN_DISCORD_IDS=123456789012345678,987654321098765432

Users with these Discord IDs will automatically be assigned the ADMIN role when they first log in.

Accessing the Admin Panel

Login

  1. Navigate to the web panel: https://yourdomain.com (or http://localhost:3000 for development)
  2. Click "Login with Discord"
  3. Authorize the application
  4. You will be redirected back to the web panel

Admin Dashboard

Once logged in as an admin, you can access the admin panel:

URL: https://yourdomain.com/admin

Navigation:

  • Dashboard: /admin
  • User Management: /admin/users
  • Server Management: /admin/servers
  • Announcements: /admin/announcements

Managing Users

Viewing Users

Navigate to: /admin/users

Features:

  • View all registered users
  • Search users by username
  • Sort by username, join date, role
  • Paginated list (20 users per page)

User Details

Click on any user to view their full profile:

  • Discord ID
  • Username and discriminator
  • Avatar
  • Bio and social links
  • Role (MEMBER, ADMIN)
  • Join date
  • Session activity

Changing User Roles

To promote a user to admin:

  1. Navigate to /admin/users
  2. Find the user in the list
  3. Click the "Role" dropdown
  4. Select "ADMIN"
  5. Confirm the action

To demote an admin to member:

  1. Follow the same steps above
  2. Select "MEMBER" from the dropdown

Note: This action is logged in the audit trail.

Deleting Users

⚠️ Warning: This action is irreversible and will delete:

  • User profile
  • All sessions
  • All notifications
  • All reviews and comments (if applicable)

To delete a user:

  1. Navigate to /admin/users
  2. Find the user in the list
  3. Click the "Delete" button
  4. Confirm the deletion

Managing Servers

Viewing Servers

Navigate to: /admin/servers

Features:

  • View all server listings
  • Filter by official/community/featured
  • Search by server name or description
  • View server details and games

Server Details

Click on any server to view:

  • Server name (from Discord)
  • Description
  • Region
  • Official status
  • Featured status
  • Approval status
  • Games managed by the bot
  • Added by (user)
  • Creation date

Featuring Servers

To feature a server (displays prominently on homepage):

  1. Navigate to /admin/servers
  2. Find the server in the list
  3. Click "Feature" button
  4. The server will appear in the featured section

To unfeature a server:

  1. Follow the same steps
  2. Click "Unfeature" button

Approving/Rejecting Servers

If you implement server approval workflow:

  1. Navigate to /admin/servers
  2. Filter by "Pending Approval"
  3. Review server details
  4. Click "Approve" or "Reject"

Removing Servers

To remove a server listing:

  1. Navigate to /admin/servers
  2. Find the server
  3. Click "Remove" button
  4. Confirm the action

Note: This only removes the web panel listing. The bot and games in Discord are not affected.

Creating Announcements

Announcements appear on the homepage and can be used to communicate with the community.

Creating an Announcement

  1. Navigate to /admin/announcements
  2. Click "Create Announcement" button
  3. Fill in the form:
    • Title: Short, descriptive title (required)
    • Body: Full announcement text (supports Markdown)
    • Published: Toggle to publish immediately or save as draft
  4. Click "Create"

Markdown Support:

# Heading
## Subheading

**Bold text**
*Italic text*

- Bullet point
- Another point

[Link text](https://example.com)

Publishing/Unpublishing Announcements

To publish a draft:

  1. Navigate to /admin/announcements
  2. Find the draft announcement
  3. Click "Edit"
  4. Toggle "Published" to ON
  5. Click "Save"

To unpublish:

  1. Follow the same steps
  2. Toggle "Published" to OFF

Editing Announcements

  1. Navigate to /admin/announcements
  2. Find the announcement
  3. Click "Edit" button
  4. Modify title, body, or published status
  5. Click "Save"

Deleting Announcements

  1. Navigate to /admin/announcements
  2. Find the announcement
  3. Click "Delete" button
  4. Confirm the deletion

Managing Live Chat

The platform includes a real-time live chat system that can sync messages to Discord via webhooks.

Accessing Live Chat Settings

Navigate to: /admin/livechat-settings

Required Permission: MANAGE_LIVECHAT_SETTINGS or MANAGE_SYSTEM

Setting Up Discord Integration

To sync live chat messages to a Discord channel:

Step 1: Create Discord Webhook

  1. Open Discord and navigate to your server
  2. Right-click the channel where you want messages to appear
  3. Select "Edit Channel"
  4. Click "Integrations" in the left sidebar
  5. Click "Create Webhook" or "View Webhooks"
  6. Click "New Webhook"
  7. Customize the webhook:
    • Name: "Live Chat" (or any name you prefer)
    • Channel: Select the target channel
  8. Click "Copy Webhook URL"

Step 2: Configure Live Chat Settings

  1. Navigate to /admin/livechat-settings
  2. Paste the webhook URL into the "Discord Webhook URL" field
  3. Click "Test Webhook" to verify it works
  4. If successful, you'll see a test message in your Discord channel
  5. Toggle "Enable Discord Sync" to ON
  6. Click "Save Settings"

Testing the Webhook

Before saving your settings, test the webhook to ensure it's valid:

  1. Paste the webhook URL into the field
  2. Click "Test Webhook" button
  3. Check your Discord channel for a test message

Test Message Format:

LiveChat Settings Test
Test message from LiveChat settings

Common Test Failures:

  • Invalid webhook URL: Check the URL format (must start with https://discord.com/api/webhooks/)
  • Webhook deleted: The webhook was deleted in Discord, create a new one
  • No permissions: The bot token lost access to the channel
  • Network error: Check server's internet connection

Enabling/Disabling Discord Sync

To enable Discord sync:

  1. Navigate to /admin/livechat-settings
  2. Toggle "Enable Discord Sync" to ON
  3. Click "Save Settings"

To disable Discord sync:

  1. Navigate to /admin/livechat-settings
  2. Toggle "Enable Discord Sync" to OFF
  3. Click "Save Settings"

Note: When disabled, messages will still be saved in the database and visible in the web chat, but they won't be sent to Discord.

How Live Chat Works

User Experience:

  • Users must be logged in to send messages
  • Messages are sent in real-time via WebSocket (Socket.IO)
  • User avatars and usernames from Discord are displayed
  • Connection status is shown (Connected/Not connected)

Discord Integration:

  • When enabled, each message sent in the web chat is posted to Discord
  • Messages appear with the user's Discord username and avatar
  • Discord users cannot send messages back to the web chat (one-way sync)

Message Format in Discord:

[Username]
Message content here
  • Username appears as the webhook name
  • User's Discord avatar is shown
  • Timestamp is automatically added by Discord

Rate Limiting

To prevent spam, the live chat has rate limits:

  • 10 messages per minute per user
  • Exceeding this limit returns a 429 Too Many Requests error
  • Rate limits reset after 1 minute

Troubleshooting Live Chat

Problem: Messages not appearing in Discord

Solutions:

  1. Check if Discord sync is enabled in settings
  2. Verify webhook URL is correct and not deleted
  3. Test webhook using the "Test Webhook" button
  4. Check API logs for webhook errors: npm run prod:logs
  5. Ensure server has internet access

Problem: Users can't send messages

Solutions:

  1. Verify users are logged in (authentication required)
  2. Check if they're hitting rate limits
  3. Look for errors in browser console (F12 → Console)
  4. Verify Socket.IO connection is established

Problem: WebSocket not connecting

Solutions:

  1. Check that API server is running
  2. Verify NEXT_PUBLIC_API_URL is set correctly in frontend
  3. Check for CORS issues in browser console
  4. Ensure session cookie is being sent
  5. Test direct connection: curl http://localhost:3001/socket.io/?EIO=4&transport=polling

Problem: Webhook returns 404

Solution: The webhook was deleted in Discord. Create a new webhook and update the settings.

Security Considerations

Webhook URL Security:

  • Webhook URLs contain secret tokens
  • Store webhook URLs securely (database only, not in logs)
  • Don't expose webhook URLs in client-side code
  • Regenerate webhooks if compromised

User Authentication:

  • Only logged-in users can send messages
  • Session validation on every message
  • Socket.IO connection requires valid session cookie

Content Moderation:

  • Messages are limited to 2000 characters
  • Excessive whitespace is trimmed
  • Consider implementing content filters for inappropriate language

Managing AMP Servers

Official game servers managed through CubeCoders AMP (Application Management Panel).

Viewing AMP Servers

Navigate to: /amp-servers

Features:

  • View all official AMP-managed servers
  • Filter by game type
  • Search by server name
  • View server status (online/offline)
  • See player counts and uptime

Server Information

Each AMP server displays:

  • Server name and game type
  • Running status (online/offline)
  • Player count (current/maximum)
  • Uptime
  • IP address and port
  • Connect button (Steam games) or copy IP (non-Steam)

Starting/Stopping Servers (Admin Only)

To start a server:

  1. Navigate to /amp-servers
  2. Find the stopped server
  3. Click "Start Server" button
  4. Confirm the action

To stop a server:

  1. Navigate to /amp-servers
  2. Find the running server
  3. Click "Stop Server" button
  4. Confirm the action

Note: Start/stop buttons only visible to admins. Actions are logged in audit trail.

Force Sync with AMP

AMP servers are automatically synced every 5 minutes (configurable). To force immediate sync:

  1. Navigate to /amp-servers
  2. Click "Sync Now" button (admin only)
  3. Server status will update within seconds

AMP Configuration

Environment Variables (.env.production):

AMP_ENABLED=true
AMP_URL=http://your-amp-server:8080
AMP_USERNAME=admin
AMP_PASSWORD=secure_password
AMP_POLL_INTERVAL=*/5 * * * *

Troubleshooting AMP Connection:

  • Verify AMP_URL is accessible from server
  • Check AMP username/password are correct
  • Ensure AMP API is enabled
  • Review API logs for connection errors

Monitoring Platform

Dashboard Statistics

Navigate to: /admin

Available Metrics:

  • Total Users: Number of registered users
  • Active Sessions: Currently logged-in users
  • Total Servers: Number of server listings
  • Total Games: Number of games managed across all servers
  • Official Servers: Number of official DBK servers
  • Pending Approvals: Servers awaiting approval (if enabled)

Refresh: Statistics auto-refresh every 30 seconds.

Audit Logs

Navigate to: /admin (Activity Feed section)

Logged Actions:

  • User role changes
  • Server featured/unfeatured
  • Server approvals/rejections
  • Announcement created/edited/deleted
  • User deletions

Audit Log Details:

  • Admin who performed the action
  • Action type
  • Target resource (user, server, announcement)
  • Timestamp
  • Metadata (e.g., old role → new role)

Database Management

Viewing Database

Development (SQLite):

npm run db:studio

Opens Prisma Studio at http://localhost:5555

Production (PostgreSQL):

npm run db:studio:prod

⚠️ Warning: Only use Prisma Studio for viewing data. Avoid direct database edits in production.

Creating Database Backups

SQLite (Development):

# Backup
cp prisma/dev.db prisma/dev.db.backup

# Restore
cp prisma/dev.db.backup prisma/dev.db

PostgreSQL (Production):

# Backup
pg_dump -U dbk_user dbk_gaming > backup.sql

# Restore
psql -U dbk_user dbk_gaming < backup.sql

Automated Backups (Production):

Set up a cron job for daily backups:

# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * pg_dump -U dbk_user dbk_gaming > /opt/backups/dbk_gaming_$(date +\%Y\%m\%d).sql

Database Migrations

Important: Always backup the database before running migrations in production.

To apply migrations:

# Development
npm run db:migrate

# Production
npm run db:migrate:prod

Resetting Database

⚠️ Danger Zone: This will delete all data!

Development Only:

# Delete database file
rm prisma/dev.db

# Re-create database
npm run db:migrate

# Re-create admin users
node scripts/create-admin.js YOUR_DISCORD_ID YourUsername

Security Best Practices

Session Management

Session Expiry: Sessions expire after 7 days of inactivity.

To invalidate all sessions (force all users to re-login):

-- Connect to database
psql -U dbk_user dbk_gaming

-- Delete all sessions
DELETE FROM "Session";

Environment Variables

Never commit .env.development or .env.production to Git.

Secure Secrets:

  • SESSION_SECRET: Use a strong random string (32+ characters)
  • CSRF_SECRET: Use a different random string

Generate secure secrets:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Admin Access

Limit Admin Accounts:

  • Only grant admin role to trusted users
  • Use separate personal and admin accounts if possible
  • Regularly review admin user list

Monitor Admin Actions:

  • Review audit logs regularly: /admin → Activity Feed
  • Check for suspicious activity:
    • Mass user deletions
    • Unauthorized role changes
    • Unusual server modifications

Discord Bot Token

Keep Bot Token Secret:

  • Never share the bot token
  • Regenerate token if compromised (Discord Developer Portal)
  • Update .env.production with new token
  • Restart bot: pm2 restart bot

Database Access

Limit Direct Access:

  • Use Prisma Studio only for viewing (not editing)
  • Restrict PostgreSQL access to localhost or VPN
  • Use strong database passwords
  • Regularly update PostgreSQL

API Security

Rate Limiting:

  • Authentication endpoints: 10 requests per 15 minutes
  • API endpoints: 60 requests per 15 minutes

CORS Policy:

  • Only allow requests from your frontend domain
  • Update FRONTEND_URL in .env.production

CSRF Protection:

  • Enabled automatically via csurf middleware
  • CSRF token required for state-changing requests

Troubleshooting

Admin Can't Access Admin Panel

Possible causes:

  1. User not assigned ADMIN role
  2. Session expired
  3. ADMIN_DISCORD_IDS not configured

Solution:

# Re-create admin user
node scripts/create-admin.js DISCORD_ID Username

# Or check database
npm run db:studio
# Verify user role is "ADMIN"

Announcements Not Showing

Check:

  1. Is announcement published? (published = true)
  2. Is frontend fetching announcements? (Check browser console)
  3. Is backend API responding? (Check logs: npm run prod:logs)

Test API:

curl http://localhost:3001/api/announcements

Audit Logs Not Recording

Check:

  1. Is admin action using the audit logging service?
  2. Is database connection working?
  3. Are there any errors in logs?

View recent logs:

SELECT * FROM "AdminAuditLog" ORDER BY "createdAt" DESC LIMIT 10;

Users Can't Login

Common issues:

  1. Discord OAuth credentials incorrect
  2. Callback URL mismatch
  3. Session secret not set

Verify OAuth Configuration:

  • Check .env.production:
    • DISCORD_CLIENT_ID
    • DISCORD_CLIENT_SECRET
    • DISCORD_CALLBACK_URL
  • Check Discord Developer Portal:
    • Redirect URL matches DISCORD_CALLBACK_URL

Useful Commands

# View all admin users
npm run db:studio
# → Navigate to User table → Filter by role = "ADMIN"

# Check bot status (production)
pm2 status

# View bot logs
pm2 logs bot

# View API logs
pm2 logs api

# View frontend logs
pm2 logs frontend

# Restart all services
pm2 restart all

# Stop all services
pm2 stop all

# View PostgreSQL active connections
psql -U dbk_user dbk_gaming -c "SELECT * FROM pg_stat_activity;"

# View database size
psql -U dbk_user dbk_gaming -c "SELECT pg_size_pretty(pg_database_size('dbk_gaming'));"

Getting Help

Logs Location:

  • Bot: ~/.pm2/logs/bot-out.log and bot-error.log
  • API: ~/.pm2/logs/api-out.log and api-error.log
  • Frontend: ~/.pm2/logs/frontend-out.log and frontend-error.log

Common Log Commands:

# View all logs in real-time
pm2 logs

# View specific service logs
pm2 logs bot
pm2 logs api
pm2 logs frontend

# View last 100 lines
pm2 logs --lines 100

Support:

  • GitHub Issues: [Your repository]
  • Discord: [Your support server]
  • Email: [Your contact email]

Checklist: First-Time Admin Setup

  • Create admin user with create-admin.js
  • Login to web panel
  • Access admin dashboard at /admin
  • Create first announcement
  • Feature official servers
  • Review dashboard statistics
  • Set up database backups (production)
  • Configure monitoring/alerts (optional)
  • Document custom procedures for your team

Last Updated: February 2026