Files
Archive/admin-panel/public/ADMIN_PANEL.md

717 lines
20 KiB
Markdown

# 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