Initial commit: LuHost - Luanti Server Management Web Interface

A modern web interface for Luanti (Minetest) server management with ContentDB integration. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-23 17:32:37 -06:00
commit 3aed09b60f
47 changed files with 12878 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,356 @@
+# LuHost
+
+A modern web interface for Luanti (formerly Minetest) server management with ContentDB integration.
+
+This is a project of the [Media Economies Design Lab](https://medlab.host) at the University of Colorado Boulder. It is part of our ongoing work on the governance of online community spaces. Built largely with Claude Code.
+
+## Overview
+
+LuHost provides a comprehensive web-based dashboard for managing Luanti servers. It features real-time server monitoring, world management, mod installation via ContentDB, and extensive configuration management - all through an intuitive web interface.
+
+## Features
+
+### 🖥️ Server Management
+- **Real-time monitoring** - Live server status, player count, and performance metrics
+- **External server detection** - Automatically detects and monitors external Luanti servers
+- **Process control** - Start, stop, and restart your Luanti server with one click
+- **Live console** - View server logs in real-time and send commands directly
+- **Player management** - View online players with activity tracking and kick functionality
+- **World selection** - Choose which world to run when starting the server
+
+### 🌍 World Management  
+- **World browser** - View and manage all your Luanti worlds
+- **Backup creation** - One-click world backups with automatic compression
+- **World deletion** - Safe world removal with confirmation dialogs
+- **World statistics** - View world size, modification dates, and details
+
+### 🧩 Extensions Management
+- **ContentDB integration** - Browse and install mods and games directly from ContentDB
+- **Extensions browser** - View installed mods and games with descriptions and metadata
+- **Dependency handling** - Automatic resolution of mod dependencies
+- **Bulk operations** - Enable, disable, or remove multiple extensions at once
+- **Game management** - Install and manage different Luanti games
+- **Quick install** - Install popular extensions with one click
+
+### ⚙️ Configuration Management
+- **Visual config editor** - Edit minetest.conf through an intuitive interface
+- **Sectioned settings** - Organized into Server, World, Performance, Security, Network, and Advanced categories
+- **Real-time validation** - Input validation with helpful error messages
+- **Backup system** - Automatic configuration backups before changes
+- **Raw config access** - View and download the raw configuration file
+
+### 👥 User Management
+- **Multi-user support** - Create and manage multiple admin accounts
+- **Session management** - Secure authentication with session-based login
+- **Role-based access** - Granular permissions for different user roles
+
+### 🔒 Security
+- **Authentication required** - All management features require login
+- **Rate limiting** - Built-in protection against abuse
+- **Input validation** - Comprehensive validation of all user inputs
+- **Secure sessions** - HTTPOnly cookies with configurable security settings
+
+## Architecture
+
+- **Express.js Backend** - Robust Node.js server with EJS templating
+- **Real-time Features** - Socket.IO for live updates and monitoring
+- **Modern UI** - Responsive design with blocky Luanti-inspired theming
+- **Security** - Comprehensive input validation, authentication, and rate limiting
+
+## Installation
+
+### Prerequisites
+
+- **Node.js** (v16 or higher)
+- **npm** (comes with Node.js)
+- **Luanti/Minetest** installed on your system
+
+### Quick Start
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/your-org/luanti-webserver.git
+   cd luanti-webserver
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Start the server**
+   ```bash
+   npm start
+   ```
+
+4. **Access the web interface**
+   Open your browser and navigate to `http://localhost:3000`
+
+5. **Initial setup**
+   - Create your admin account on first visit
+   - Configure your Luanti installation path if needed
+   - Start managing your server!
+
+### Verification
+
+To verify your installation is working correctly:
+
+1. **Check server status** - Visit the dashboard and confirm server detection
+2. **Test external server detection** - If you have a Luanti server running, it should appear as "Running (External - Monitor Only)"
+3. **Create a test world** - Use the Worlds section to create a new world
+4. **Start managed server** - Try starting a server through LuHost with full control capabilities
+
+### Production Deployment
+
+For production use, consider these additional steps:
+
+1. **Set environment variables**
+   ```bash
+   export NODE_ENV=production
+   export SESSION_SECRET=your-secure-random-secret
+   export PORT=3000
+   ```
+
+2. **Use a process manager**
+   ```bash
+   npm install -g pm2
+   pm2 start app.js --name luhost
+   ```
+
+3. **Set up reverse proxy** (optional)
+   Configure nginx or Apache to proxy requests to LuHost
+
+## Configuration
+
+### Environment Variables
+
+- `NODE_ENV` - Set to 'production' for production deployments
+- `PORT` - Port number for the web server (default: 3000)
+- `SESSION_SECRET` - Secret key for session encryption
+- `HTTPS` - Set to 'true' if using HTTPS in production
+
+### Directory Structure
+
+LuHost automatically detects your Luanti installation and creates the following structure:
+
+```
+~/.minetest/                    # Default Luanti directory
+├── minetest.conf              # Server configuration
+├── worlds/                    # World files
+├── mods/                      # Installed mods
+└── games/                     # Game definitions
+```
+
+## API Reference
+
+LuHost provides a REST API for programmatic access:
+
+### Server Management
+- `GET /api/server/status` - Get server status
+- `POST /api/server/start` - Start server
+- `POST /api/server/stop` - Stop server
+- `POST /api/server/restart` - Restart server
+- `POST /api/server/command` - Send server command
+
+### World Management
+- `GET /api/worlds` - List all worlds
+- `POST /api/worlds/:name/backup` - Create world backup
+- `DELETE /api/worlds/:name` - Delete world
+
+### Player Management
+- `POST /api/server/command` - Send server commands (including kick players)
+
+### Configuration
+- `GET /api/config` - Get current configuration
+- `POST /api/config` - Update configuration
+- `POST /api/config/reset/:section` - Reset section to defaults
+
+### ContentDB
+- `GET /api/contentdb/packages` - Browse ContentDB packages
+- `GET /api/contentdb/search` - Search packages
+- `POST /api/contentdb/install` - Install package
+
+## WebSocket Events
+
+Real-time updates are provided via WebSocket:
+
+### Server Events
+- `server:status` - Server status changes with external server detection
+- `server:log` - New log entries in real-time
+- `server:players` - Player list updates with activity tracking
+- `server:stats` - Server performance statistics
+
+### System Events
+- `configUpdate` - Configuration changes
+
+## Troubleshooting
+
+### Common Issues
+
+**Server won't start**
+- Check that Luanti is properly installed (`luanti --version` or `minetest --version`)
+- Verify the Luanti executable is in your PATH
+- Check server logs for specific error messages
+- Ensure worlds exist before trying to start server
+
+**External server not detected**
+- External servers are detected automatically if running
+- Only servers started independently (not through LuHost) are marked as external
+- External servers have limited control - monitoring only
+
+**Permission errors**
+- Ensure LuHost has read/write access to Luanti directories
+- On Linux/Mac, you may need to adjust file permissions: `chmod -R 755 ~/.minetest`
+
+**Port conflicts**
+- Default web port is 3000, game server port is 30000
+- Change ports if conflicts occur with other services
+- Use `PORT=3001 npm start` to run on different port
+
+**Player kick not working**
+- Kick functionality only works on servers managed by LuHost
+- External servers show disabled kick buttons with explanatory tooltips
+- Ensure you have proper authentication when using server commands
+
+**WebSocket connection issues**
+- Check firewall settings
+- Verify that WebSocket connections aren't blocked by proxy/firewall
+
+### Log Files
+
+LuHost logs important events to the console. For persistent logging:
+
+```bash
+npm start > luhost.log 2>&1
+```
+
+### Support
+
+For issues and questions:
+1. Check the troubleshooting section above
+2. Review server logs for error messages
+3. Verify your Luanti installation is working independently
+4. Check file permissions and directory access
+
+## Development
+
+### Project Structure
+
+```
+├── app.js                     # Main application entry point
+├── package.json              # Dependencies and scripts
+├── routes/                    # Express route handlers
+│   ├── auth.js               # Authentication routes
+│   ├── api.js                # API endpoints
+│   ├── server.js             # Server management
+│   ├── config.js             # Configuration management
+│   ├── worlds.js             # World management
+│   ├── users.js              # User management
+│   ├── extensions.js         # Extensions (mods/games) management
+│   └── contentdb.js          # ContentDB integration
+├── views/                     # EJS templates
+│   ├── layout.ejs            # Base template
+│   ├── dashboard.ejs         # Main dashboard
+│   ├── auth/                 # Authentication views
+│   ├── server/               # Server management views
+│   ├── config/               # Configuration views
+│   ├── worlds/               # World management views
+│   ├── users/                # User management views
+│   ├── extensions/           # Extensions management views
+│   └── contentdb/            # ContentDB browser views
+├── utils/                     # Utility modules
+│   ├── server-manager.js     # Server process management
+│   ├── shared-server-manager.js # Shared server manager instance
+│   ├── config-manager.js     # Configuration handling
+│   ├── config-parser.js      # Configuration file parsing
+│   ├── contentdb.js          # ContentDB API client
+│   ├── auth.js               # Authentication utilities
+│   ├── paths.js              # Path resolution
+│   └── security-logger.js    # Security event logging
+├── middleware/                # Express middleware
+│   ├── auth.js               # Authentication middleware
+│   └── security.js           # Security middleware
+├── public/                    # Static assets
+│   ├── css/                  # Stylesheets
+│   ├── js/                   # Client-side JavaScript
+│   │   ├── main.js           # Global JavaScript
+│   │   ├── server.js         # Server management page
+│   │   └── shared-status.js  # Shared status updates
+│   └── images/               # Images and icons
+└── data/                      # Application data
+    ├── sessions.db           # User sessions
+    ├── users.db              # User accounts
+    └── packages.db           # Package registry cache
+```
+
+### Development Setup
+
+1. **Install development dependencies**
+   ```bash
+   npm install
+   ```
+
+2. **Run in development mode**
+   ```bash
+   npm run dev
+   ```
+
+3. **Development features**
+   - Automatic server restart on file changes (via nodemon)
+   - Detailed error logging
+   - Development-friendly settings
+
+### Key Implementation Notes
+
+**External Server Detection**
+- The system automatically detects external Luanti servers via process scanning
+- External servers are monitored but have limited control capabilities
+- Player data is extracted from debug.txt parsing for external servers
+- UI clearly distinguishes between managed and external servers
+
+**Real-time Features**
+- WebSocket integration provides live updates without page refreshes
+- Server status, player lists, and logs update automatically
+- Shared server manager instance ensures consistency across pages
+
+**Security Architecture**
+- Multi-layered security with authentication, CSRF protection, and rate limiting
+- Input validation and XSS protection on all user inputs
+- Session-based authentication with secure cookie handling
+- Comprehensive security logging for audit purposes
+
+**Player Management**
+- Intelligent player detection from server logs with activity classification
+- False positive filtering (excludes entities, explosions, etc.)
+- Real-time player activity tracking with kick functionality for managed servers
+- Player list automatically updates as players join/leave or become active/inactive
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test thoroughly with both internal and external servers
+5. Ensure security features remain intact
+6. Submit a pull request
+
+### AI-Enabled Development Notes
+
+When working on this codebase with AI assistance:
+
+1. **Server Manager** - The core logic is in `utils/server-manager.js` with external server detection
+2. **Authentication** - All routes require authentication; check `middleware/auth.js` for patterns
+3. **Real-time Updates** - WebSocket events are defined in `routes/api.js` and handled in client-side JS
+4. **Player Detection** - Complex logic in `getExternalServerPlayerData()` method with filtering rules
+5. **Security** - Multiple layers; always validate inputs and check existing patterns
+6. **Database** - SQLite databases for sessions, users, and package cache
+7. **File Structure** - Follow existing patterns in routes, views, and utilities
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Acknowledgments
+
+- **Luanti Project** - For the amazing voxel game engine
+- **ContentDB** - For the mod and game distribution platform