3aed09b60f
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>
356 lines
13 KiB
Markdown
356 lines
13 KiB
Markdown
# 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 |