Skip to content
Klutch.sh Docs

Deploying Luanti

Introduction

Luanti (formerly known as Minetest) is an open-source voxel game engine that provides a platform for creating and playing sandbox games similar to Minecraft. Unlike traditional games, Luanti is a game engine that can run various games and supports extensive modding through its Lua API. The project was renamed to Luanti in 2024 to better reflect its nature as a game creation platform rather than a single game.

With Luanti, you can host multiplayer servers for various game types, from survival and creative building to educational environments and mini-games. The engine’s lightweight design means it runs efficiently on modest hardware while supporting up to 255 players on a single server.

Key highlights of Luanti:

  • Voxel Game Engine: Create and play various sandbox games
  • Easy Modding: Extensive Lua API for custom content
  • Multiple Games: Support different games on the same engine
  • Cross-Platform: Players can join from Windows, macOS, Linux, Android
  • Multiplayer: Host servers supporting up to 255 players
  • Resource Efficient: Low hardware requirements
  • Content Database: Access thousands of mods and games
  • Educational Use: Popular in schools for teaching programming
  • Active Community: Large community of modders and players
  • Open Source: LGPL/MIT licensed with active development

This guide walks through deploying a Luanti server on Klutch.sh using Docker, configuring your game world, and managing mods and content.

Why Deploy Luanti on Klutch.sh

Deploying Luanti on Klutch.sh provides several advantages:

Always Online: Your game server remains accessible 24/7 without managing personal hardware.

Persistent Worlds: Attach persistent volumes for your world data. Player progress and builds survive restarts.

Easy Management: Docker deployment simplifies server administration.

GitHub Integration: Connect your configuration repository directly from GitHub for version-controlled server settings.

Scalable Resources: Allocate CPU and memory based on expected player count and world complexity.

Custom Domains: Use a memorable domain for players to connect.

Geographic Reach: Deploy close to your player base for better latency.

Prerequisites

Before deploying Luanti on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your server configuration
  • Basic familiarity with Docker and game server management
  • Players with Luanti/Minetest clients installed

Understanding Luanti Architecture

Luanti server uses a straightforward architecture:

Game Engine: The core Luanti engine handles world generation, physics, and client connections.

Games: Games are collections of mods that define gameplay. Popular games include Minetest Game, Mineclone 2, and NodeCore.

Mods: Lua scripts that extend functionality, add items, or modify gameplay.

World Data: Player data, map chunks, and metadata stored in the world directory.

Configuration: Server settings in minetest.conf control gameplay parameters.

Preparing Your Repository

To deploy Luanti on Klutch.sh, create a GitHub repository containing your Docker configuration.

Repository Structure

luanti-server/
├── Dockerfile
├── docker-compose.yml
├── minetest.conf
├── mods/
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile using LinuxServer’s image:

FROM lscr.io/linuxserver/luanti:latest


# Set environment variables
ENV PUID=1000
ENV PGID=1000
ENV TZ=UTC


# Copy server configuration
COPY minetest.conf /config/.minetest/minetest.conf


# Copy custom mods (if any)
COPY mods/ /config/.minetest/mods/


# Expose the game port
EXPOSE 30000/udp


# The base image includes the default entrypoint

Alternative: Official Luanti Image

Using the official Luanti image:

FROM ghcr.io/luanti-org/luanti:latest


# Set working directory
WORKDIR /var/lib/minetest


# Copy configuration
COPY minetest.conf /etc/minetest/minetest.conf


# Expose the game port
EXPOSE 30000/udp


CMD ["minetestserver", "--config", "/etc/minetest/minetest.conf"]

Creating Server Configuration

Create minetest.conf:

# Server Settings
name = My Luanti Server
description = Welcome to my Luanti server!
address =
port = 30000
max_users = 15
creative_mode = false
enable_damage = true
enable_pvp = true


# Security
default_privs = interact, shout
disallow_empty_password = true
enable_rollback_recording = true


# World Settings
default_game = minetest
motd = Welcome! Please read /rules


# Performance
max_block_send_distance = 10
max_simultaneous_block_sends_per_client = 10
dedicated_server_step = 0.05


# Server Listing (optional)
server_announce = false
serverlist_url = servers.minetest.net


# Admin
name = admin


# Debug (disable in production)
debug_log_level = warning

Creating Docker Compose Configuration

Create docker-compose.yml for reference:

version: '3.8'


services:
  luanti:
    image: lscr.io/linuxserver/luanti:latest
    container_name: luanti-server
    restart: unless-stopped
    ports:
      - "30000:30000/udp"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - CLI_ARGS=--gameid minetest
    volumes:
      - luanti_config:/config/.minetest


volumes:
  luanti_config:

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

VariableRequiredDefaultDescription
PUIDNo1000User ID for file permissions
PGIDNo1000Group ID for file permissions
TZNoUTCTimezone
CLI_ARGSNo-Additional server command arguments

Deploying Luanti on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile minetest.conf docker-compose.yml .dockerignore
    git commit -m "Initial Luanti server configuration"
    git remote add origin https://github.com/yourusername/luanti-server.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “luanti-server” or “game-server”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Luanti configuration.

    Configure UDP Traffic

    In the deployment settings:

    • Select UDP as the traffic type
    • Set the internal port to 30000

    Set Environment Variables

    In the environment variables section:

    VariableValue
    PUID1000
    PGID1000
    TZYour timezone (e.g., America/New_York)

    Attach Persistent Volumes

    Add persistent storage for your world and configuration:

    Mount PathRecommended SizePurpose
    /config/.minetest20 GBWorld data, mods, and configuration

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Detect your Dockerfile automatically
    • Build the container image
    • Attach the persistent volumes
    • Start the Luanti server
    • Configure UDP port forwarding

    Connect to Your Server

    Once deployment completes, players can connect using:

    • Server address: your-app-name.klutch.sh
    • Port: 30000

Server Configuration

Game Selection

Choose which game to run:

# In minetest.conf
default_game = minetest


# Or use CLI_ARGS environment variable
CLI_ARGS=--gameid mineclone2

Popular games:

  • minetest: The classic Minetest Game
  • mineclone2: Minecraft-like experience
  • nodecore: Technology progression game
  • bucket_game: Adventure-focused gameplay

Player Privileges

Configure default player privileges:

# Basic privileges
default_privs = interact, shout


# More permissive
default_privs = interact, shout, home, teleport


# Available privileges:
# interact - interact with objects
# shout - chat
# home - set and use home position
# teleport - teleport to coordinates
# bring - bring players to you
# give - spawn items
# settime - change time
# fast - fast movement
# fly - flying
# noclip - pass through walls
# basic_privs - grant basic privs
# privs - grant any privileges
# server - server management
# ban - ban/unban players
# kick - kick players
# rollback - use rollback

World Settings

Configure world generation:

# Map generation
mg_name = v7
mg_flags = caves, dungeons, light, decorations


# Seed (for reproducible worlds)
fixed_map_seed = 12345


# World border (optional)
mapgen_limit = 31000

Performance Tuning

Optimize for your player count:

# For small servers (< 10 players)
max_block_send_distance = 10
max_simultaneous_block_sends_per_client = 10
dedicated_server_step = 0.05


# For larger servers (10+ players)
max_block_send_distance = 8
max_simultaneous_block_sends_per_client = 8
dedicated_server_step = 0.03


# Reduce memory usage
max_clearobjects_extra_loaded_blocks = 512
num_emerge_threads = 1

Installing Mods

Adding Mods

Add mods to your server:

  1. Download mods from ContentDB
  2. Place mod folders in the mods/ directory
  3. Enable mods in world.mt or server settings
  • areas: Protected regions
  • worldedit: Building tools
  • skins: Player customization
  • unified_inventory: Enhanced inventory
  • technic: Technology mod pack
  • mesecons: Redstone-like circuits
  • mobs_redo: Animals and creatures

Mod Configuration

Configure mods in minetest.conf:

# Enable specific mods
load_mod_areas = true
load_mod_worldedit = true


# Mod-specific settings
areas.self_protection = true
areas.legacy_table = true

Server Administration

In-Game Commands

Common server commands:

/status - Server status
/kick <player> - Kick a player
/ban <player> - Ban a player
/unban <player> - Unban a player
/grant <player> <privilege> - Grant privilege
/revoke <player> <privilege> - Remove privilege
/teleport <player> <x> <y> <z> - Teleport player
/shutdown - Shut down server
/clearobjects - Clear dropped items

Remote Console

Configure remote console access:

# Enable remote console
remote_console = true
# Set password (change this!)
remote_console_password = your_secure_password

Backups

Protect your world:

  1. Automated Backups: Back up /config/.minetest/worlds/ regularly
  2. Player Data: Include players/ directory in backups
  3. Configuration: Version control your minetest.conf

Production Best Practices

Security Recommendations

  • Strong Passwords: Require passwords for all players
  • Privilege Management: Grant minimal necessary privileges
  • Mod Vetting: Review mods before installation
  • Regular Updates: Keep server and mods updated
  • Ban Management: Maintain ban lists for problematic players

Performance Optimization

  • Resource Allocation: Scale based on player count
  • World Limits: Set reasonable map boundaries
  • Object Cleanup: Schedule regular clearobjects
  • Mod Selection: Avoid resource-heavy mods

Community Management

  • Rules: Display clear server rules
  • Moderation: Appoint trusted moderators
  • Communication: Set up Discord or forum
  • Events: Organize community activities

Troubleshooting Common Issues

Players Cannot Connect

Symptoms: Connection timeout or refused.

Solutions:

  • Verify UDP port 30000 is configured
  • Check server is running
  • Confirm address and port
  • Test from different network

World Not Loading

Symptoms: Server starts but world is empty.

Solutions:

  • Check world directory exists
  • Verify game ID is correct
  • Review server logs for errors
  • Check file permissions

Mod Errors

Symptoms: Server crashes or mods don’t work.

Solutions:

  • Check mod compatibility
  • Review server logs
  • Verify mod dependencies
  • Update to latest mod versions

Performance Issues

Symptoms: Lag or slow response.

Solutions:

  • Reduce max_block_send_distance
  • Increase allocated resources
  • Clear inactive player data
  • Optimize world with clearobjects

Additional Resources

Conclusion

Deploying Luanti on Klutch.sh gives you a powerful voxel game server with persistent worlds and easy management. The combination of Luanti’s extensive modding capabilities and Klutch.sh’s reliable hosting creates an excellent foundation for community game servers.

With support for multiple games, thousands of mods, and up to 255 players, Luanti scales from small private servers to large community hubs. The Docker deployment ensures consistent, reproducible server environments that can be version-controlled alongside your mods and configuration.

Whether you’re hosting a creative building server, survival adventure, or educational environment, Luanti on Klutch.sh provides the infrastructure for engaging multiplayer experiences.