# 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