LuHost

A modern web interface for Luanti (formerly Minetest) server management with ContentDB integration.

This is a project of the Media Economies Design Lab 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

   git clone https://github.com/your-org/luanti-webserver.git
   cd luanti-webserver
   

2. Install dependencies

   npm install
   

3. Start the server

   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

   export NODE_ENV=production
   export SESSION_SECRET=your-secure-random-secret
   export PORT=3000
   

2. Use a process manager

   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:

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

   npm install
   

2. Run in development mode

   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