Archive/documentation/ADMIN_PANEL.md

Admin Panel Documentation

Admin Panel is a centralized management interface for all Habbo emulators and services running in the Habland environment. It provides unified control over multiple emulator instances, databases, and associated services.

🎯 Overview

The Admin Panel is a Next.js-based web application that integrates with Docker containers to provide real-time monitoring and management capabilities for:

• Havana (v31+ Transition Era emulator)
• Kepler (v14 Classic Shockwave emulator)
• Roseau (v1 Goldfish era emulator)
• Arcturus Morningstar (Modern emulator with extensive features)

🚀 Quick Start

Accessing the Admin Panel

• URL: http://localhost:3000 (or configured port)
• Default Theme: Orange (customizable via Settings)
• Auto-Refresh: Container status updates every 2 seconds

Navigation

The sidebar provides access to all major sections:

• Dashboard - Container management and monitoring
• Users - User account management
• Furni - Furniture catalog management
• Catalog - In-game catalog configuration
• Clothing - Avatar clothing editor
• Documentation - Browse emulator documentation
• Settings - Theme and configuration
• Health - System health monitoring
• Debug - Development and debugging tools
• Bulk Ops - Bulk operations for data management
• Backups - Database backup and restore

---

📊 Dashboard (Container Manager)

The main page provides comprehensive container orchestration and monitoring.

Features

Emulator Filter Buttons

Filter containers by emulator type and their dependencies:

• All Containers - Shows all running containers
• Havana - Havana server, Havana web client, unified-db, asset-server
• Kepler - Kepler server, Kepler client, unified-db, asset-server
• Roseau - Roseau server, Roseau client, unified-db, asset-server
• Arcturus - Arcturus emulator, AtomCMS, Nitro React, Cool UI, Redis, unified-db, asset-server

Start All Button

When an emulator filter is selected, a green "Start All" button appears that:

• Starts all stopped containers for that emulator group
• Executes starts sequentially with 500ms delay between each
• Shows "Starting..." state during operation
• Useful for quickly spinning up a complete emulator environment

Container Cards

Each container displays:

• Status Badge - Running (green) or Exited (red) with animated pulse
• Container Image - Visual representation of the service
• Container Name - Docker container identifier
• Description - Brief explanation of the container's purpose
• Online Count - Live player count for emulator servers (Havana, Kepler, Roseau)
• Action Buttons:
  • Start - Launch stopped container
  • Restart - Reboot running container
  • Stop - Shutdown running container
• Press to view - Click anywhere on the card to open detailed modal

Container Modal

Click any container card to open the detailed management modal with tabs:

Links Tab

• Quick access links to web interfaces
• Service-specific URLs (phpMyAdmin, Redis Commander, etc.)
• Documentation references

Notes Tab

• Add custom notes for each container
• Useful for configuration details, deployment notes, or troubleshooting tips
• Persisted across sessions

Secrets Tab

• Securely manage environment variables
• Store API keys, passwords, and configuration secrets
• Warning: Handle sensitive data carefully

Docs Tab

• Container-specific documentation
• For emulators: Full markdown documentation (Havana, Kepler, Roseau, Arcturus)
• External resource links (GitHub repos, official docs, wikis)

Controls Tab

• Advanced container operations
• Force restart, rebuild, update actions
• Container-specific management tools

Status Tab

• Detailed container status information
• Resource usage (CPU, memory, network)
• Container health checks
• Uptime statistics

Logs Tab

• Real-time container logs
• Last 100 log lines with auto-refresh
• Color-coded log levels
• Search and filter capabilities

Online Stats Bar

Displays live player counts across all emulators:

• Havana Online: Current players on Havana server
• Kepler Online: Current players on Kepler server
• Roseau Online: Current players on Roseau server

---

👥 Users Management

Manage user accounts across all emulator databases.

Features

Emulator Selection

Switch between emulator databases:

• Havana - Havana user database
• Kepler - Kepler user database
• Roseau - Roseau user database
• Retro (Arcturus) - Arcturus user database

User Table

Displays comprehensive user information:

• Username - User account name
• Email - Registered email address
• Rank - User permission level (1=User, 5=Moderator, 7=Admin)
• Credits - In-game currency balance
• Last Online - Timestamp of last login
• Actions - Edit, delete, manage user

Search & Filters

• Search Bar - Find users by username or email
• Rank Filter - Filter by permission level
• Sort Options - Sort by username, credits, last online
• Pagination - Navigate large user lists efficiently

User Actions

• Add User - Create new accounts with custom settings
• Edit User - Modify username, email, rank, credits
• Delete User - Remove user accounts (with confirmation)
• Reset Password - Generate new passwords for users
• Grant Badges - Award achievement badges
• Manage Credits - Add or remove in-game currency

---

🪑 Furni Management

Manage furniture items in the catalog across emulators.

Features

Emulator Database Selection

Choose which emulator's furniture catalog to manage:

• Havana - Havana furniture database
• Kepler - Kepler furniture database
• Roseau - Roseau furniture database
• Retro - Arcturus furniture database

Furniture Table

Displays all furniture items with:

• Item Name - Furniture identifier
• Public Name - Display name shown to users
• Type - Floor item, wall item, effect, badge
• Width/Length - Furniture dimensions
• Stack Height - Stacking properties
• Can Sit/Lay - Interaction capabilities
• Sprite ID - Asset reference number

Furniture Operations

• Add Furniture - Import new items from catalog
• Edit Item - Modify properties (name, type, dimensions, interactions)
• Delete Item - Remove furniture from catalog
• Bulk Import - Upload CSV of furniture items
• Export Catalog - Download furniture database as CSV

Search & Filters

• Search - Find items by name or sprite ID
• Type Filter - Filter by furniture type
• Interaction Filter - Show only sittable/layable items
• Category Filter - Browse by catalog category

---

📦 Catalog Management

Configure in-game catalog pages and items.

Features

Catalog Pages

Manage the hierarchical catalog structure:

• Page Name - Display name in catalog
• Parent Page - Nested catalog organization
• Icon - Catalog page icon
• Visibility - Public, VIP, or rank-restricted
• Order - Page display order

Catalog Items

Configure purchasable items:

• Item Name - Product name
• Description - Item description shown to users
• Furniture Association - Link to furniture database
• Cost - Credit price
• Points Cost - Alternative currency (diamonds, duckets)
• Limit - Purchase limits per user

Catalog Operations

• Add Page - Create new catalog category
• Edit Page - Modify page properties
• Add Item - Add products to catalog
• Edit Item - Update pricing and availability
• Reorder - Drag-and-drop page reorganization
• Clone Page - Duplicate catalog structure

---

👔 Clothing Editor

Manage avatar clothing and figure data.

Features

Clothing Database

Browse and edit available clothing items:

• Part Type - Hair, shirt, pants, shoes, accessories
• Figure ID - Clothing identifier
• Gender - Male, female, or unisex
• Club Level - Free, VIP, or HC only
• Color Palette - Available color options

Figure Editor

Visual avatar builder:

• Interactive Preview - Real-time avatar rendering
• Part Selection - Choose clothing parts
• Color Picker - Customize colors
• Figure String - Generated figure code
• Save Presets - Store common outfits

Clothing Operations

• Add Clothing - Import new clothing items
• Edit Item - Modify properties and availability
• Delete Item - Remove from catalog
• Bulk Import - Upload clothing data
• Export Database - Download clothing catalog

---

📚 Documentation

Browse comprehensive documentation for all emulators and services.

Features

Documentation Browser

Two-panel interface for efficient browsing:

• Left Sidebar - List of available documentation
• Right Panel - Rendered markdown content with syntax highlighting

Available Documentation

• Havana Emulator - v31+ Transition Era documentation
• Kepler Emulator - v14 Classic Shockwave documentation
• Roseau Emulator - v1 Goldfish era documentation
• Arcturus Morningstar - Modern emulator documentation
• Admin Panel - This documentation

Search Functionality

• Real-time Search - Filter docs by title, description, or content
• Keyword Highlighting - Search terms highlighted in results
• Content Indexing - Search within markdown content

Documentation Features

• Markdown Rendering - Full CommonMark support
• Syntax Highlighting - Code blocks with language detection
• Table Support - Formatted tables
• Link Navigation - Internal and external links
• Responsive Design - Mobile-friendly layout

---

⚙️ Settings

Customize the admin panel appearance and behavior.

Theme Customization

Color Schemes

Choose from preset themes or create custom:

• Orange (Default) - Vibrant orange gradient
• Purple - Royal purple tones
• Blue - Cool blue palette
• Green - Fresh green theme
• Pink - Soft pink accents
• Custom - Define your own colors

Theme Settings

• Primary Color - Main accent color for buttons and highlights
• Secondary Color - Supporting color for UI elements
• Accent Color - Hover states and active elements
• Gradient Start/End - Gradient color definitions

Live Preview

• Real-time preview of theme changes
• Apply instantly without page reload
• CSS variable injection for smooth transitions

Configuration Options

• Auto-Refresh Interval - Container status update frequency (default: 2s)
• Log Tail Lines - Number of log lines to display (default: 100)
• Notification Preferences - Container event notifications
• Default Emulator - Preferred emulator for multi-select pages

---

🏥 Health Monitoring

System health dashboard for monitoring infrastructure.

Features

Container Health

Monitor the health of all Docker containers:

• Health Status - Healthy, unhealthy, or starting
• Health Checks - Last check timestamp and result
• Restart Count - Number of container restarts
• Uptime - Container running duration

Database Health

Monitor database connections and performance:

• Connection Status - Connected or disconnected
• Active Connections - Current database connections
• Query Performance - Average query execution time
• Database Size - Storage usage

System Resources

Overall system resource monitoring:

• CPU Usage - System and per-container CPU utilization
• Memory Usage - RAM consumption and available memory
• Disk Usage - Storage space utilization
• Network I/O - Bandwidth usage statistics

Alerts & Warnings

Automated health monitoring alerts:

• Container Crashes - Immediate notification of container failures
• Resource Limits - Warnings when approaching capacity
• Database Issues - Connection failures or slow queries
• Service Degradation - Performance below threshold

---

🔧 Debug Tools

Development and troubleshooting utilities.

Features

Container Inspector

Deep dive into container internals:

• Environment Variables - View all container env vars
• Volume Mounts - Mounted directories and files
• Network Settings - IP addresses, ports, DNS
• Running Processes - Active processes inside container

Database Query Tool

Execute SQL queries against emulator databases:

• Query Editor - SQL syntax highlighting
• Multi-Database - Connect to any emulator database
• Result Display - Formatted table output
• Export Results - CSV, JSON export options
• Query History - Recent queries

API Testing

Test API endpoints:

• Endpoint List - All available API routes
• Request Builder - Construct API requests
• Response Viewer - Formatted JSON/XML responses
• Authentication - Test with auth tokens

Log Aggregation

Centralized log viewing:

• All Containers - Aggregated logs from all services
• Filter by Level - Error, warning, info, debug
• Time Range - Filter logs by timestamp
• Export Logs - Download log archives

---

⚡ Bulk Operations

Perform batch operations on data across emulators.

Features

Emulator Selection

Choose target emulator database:

• Havana - Havana database
• Kepler - Kepler database
• Roseau - Roseau database
• Retro - Arcturus database

Operation Types

User Operations

• Mass User Creation - Bulk import users from CSV
• Rank Updates - Batch modify user ranks
• Credit Distribution - Add credits to multiple users
• Badge Awards - Grant badges to user groups
• Account Deletion - Bulk remove users

Furniture Operations

• Catalog Import - Bulk import furniture items
• Price Updates - Update pricing across catalog
• Item Deletion - Remove multiple items
• Category Assignment - Batch categorize items

Catalog Operations

• Page Creation - Generate multiple catalog pages
• Item Association - Link items to pages in bulk
• Visibility Updates - Modify page access in batch

Import/Export

• CSV Import - Upload structured data files
• Excel Support - Import .xlsx files
• JSON Import - Structured data import
• Export Options - Download data in multiple formats
• Template Download - Get import templates

Validation & Preview

• Data Validation - Check import data before commit
• Preview Changes - Review operations before execution
• Error Reporting - Detailed error messages
• Rollback Support - Undo bulk operations

---

💾 Backups

Database backup and restore functionality.

Features

Backup Creation

Create database backups:

• Select Database - Choose emulator database to backup
• Backup Name - Custom backup identifier
• Compression - Gzip compression for storage efficiency
• Scheduling - Automated backup schedules

Backup Management

Manage existing backups:

• Backup List - All available backups with metadata
• Backup Size - Storage space used
• Creation Date - Backup timestamp
• Database Version - Schema version information

Restore Operations

Restore from backups:

• Select Backup - Choose backup to restore
• Preview - Review backup contents before restore
• Restore Options - Full or partial restore
• Confirmation - Multi-step confirmation for safety

Backup Features

• Download Backup - Export backup files locally
• Delete Backup - Remove old backups
• Backup Verification - Test backup integrity
• Automated Retention - Auto-delete old backups (configurable)

---

🔐 Security & Best Practices

Access Control

• Authentication - Secure admin panel access (configure via environment)
• Session Management - Auto-logout after inactivity
• Permission Levels - Role-based access control

Data Safety

• Confirmation Dialogs - Required for destructive operations
• Backup Before Changes - Automatic backups before bulk operations
• Audit Logging - Track all administrative actions
• Version Control - Database schema versioning

Performance Optimization

• Lazy Loading - Components load on demand
• Pagination - Efficient data display for large datasets
• Caching - Smart caching to reduce database queries
• Auto-Refresh - Configurable intervals to balance freshness and load

---

🛠 Troubleshooting

Common Issues

Container Won't Start

Symptoms: Container shows "Exited" status immediately after start attempt

Solutions:

1. Check container logs via the Logs tab in container modal
2. Verify database is running (unified-db container)
3. Check for port conflicts with other services
4. Review environment variables in Debug section

No Online Stats Showing

Symptoms: Online player counts show "—" instead of numbers

Solutions:

1. Verify emulator server is running
2. Check API endpoint /api/stats in Debug tools
3. Ensure database connection is healthy
4. Verify emulator is writing online user data

Bulk Operations Failing

Symptoms: CSV imports return errors or no data imported

Solutions:

1. Download CSV template from Bulk Ops page
2. Verify CSV format matches template exactly
3. Check for special characters or encoding issues
4. Review error messages for specific field issues

Theme Not Applying

Symptoms: Color changes in Settings don't take effect

Solutions:

1. Click "Save Theme" button after making changes
2. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
3. Clear browser cache
4. Check browser console for JavaScript errors

Getting Help

• Documentation Tab - Search for specific topics
• Container Logs - Debug container-specific issues
• Health Dashboard - Check overall system health
• Debug Tools - Advanced troubleshooting utilities

---

📡 API Reference

The Admin Panel exposes several API endpoints for programmatic access:

Container Management

• GET /api/containers - List all containers
• POST /api/control - Start/stop/restart containers
• GET /api/containers/:id/logs - Fetch container logs
• GET /api/containers/:id/stats - Container resource usage

User Management

• GET /api/users?emulator={name} - List users
• POST /api/users - Create user
• PUT /api/users/:id - Update user
• DELETE /api/users/:id - Delete user

Furniture & Catalog

• GET /api/furni?emulator={name} - List furniture
• GET /api/catalog/items?emulator={name} - Catalog items
• GET /api/catalog/pages?emulator={name} - Catalog pages

System

• GET /api/stats - Online player statistics
• GET /api/health - System health status
• GET /api/config - Configuration settings
• POST /api/settings - Update settings

Backups

• GET /api/backups - List backups
• POST /api/backups - Create backup
• POST /api/backups/restore - Restore backup
• DELETE /api/backups/:id - Delete backup

---

🚀 Advanced Features

Docker Compose Integration

The Admin Panel integrates directly with Docker Compose:

• Real-time status monitoring via Docker API
• Container lifecycle management (start/stop/restart)
• Log streaming from containers
• Resource usage monitoring

Multi-Database Support

Seamlessly switch between emulator databases:

• Unified connection pooling
• Database-specific optimizations
• Safe multi-tenant operations
• Isolated data management

Theme System

Advanced theming with CSS variables:

• Live theme preview
• Persistent theme storage
• CSS variable injection
• Gradient customization

---

📝 Version Information

• Admin Panel Version: 1.1.0
• Next.js Version: 16.0.7
• Node Version: 20 LTS
• Docker Integration: Docker Engine API v1.41+

---

🤝 Support & Contribution

Reporting Issues

Found a bug or have a feature request?

1. Check existing issues first
2. Provide detailed reproduction steps
3. Include browser/environment information
4. Attach relevant logs from Debug section

Feature Requests

Suggest new features:

1. Describe the use case
2. Explain expected behavior
3. Provide mockups or examples if applicable

---

📚 Additional Resources

• Havana Documentation: See HAVANA.md
• Kepler Documentation: See KEPLER.md
• Roseau Documentation: See ROSEAU.md
• Arcturus Documentation: See ARCTURUS_RETRO.md
• Docker Documentation: https://docs.docker.com
• Next.js Documentation: https://nextjs.org/docs

---

Last Updated: December 2024 Maintained By: Habland Development Team