A complete, portable developer environment for provisioning Minecraft servers with zero hassle.
mineismine is a self-contained server and client deployment toolkit for developers. It ships everything you need to spin up a high-performance Void Linux server and connect to it with a fast, minimal Minecraft client.
- mineismine
- Zero-Dependency Quick Start (Windows): A single-click hybrid script downloads all necessary tools (uv, Rio) into a separate environment. No pre-installed Python or other dependencies needed.
- Declarative Configuration: Manage the entire server, from
server.propertiesto mod lists and system paths, through a singleconfig.xmlfile. - Automated Deployment: Intelligent updates and idempotent deploy steps of a remote Void Linux host with Fabric, including system configuration, kernel tuning, modpack deployment, and service setup.
- Performance-Oriented Stack: Built on Void Linux, GraalVM, and FabricMC for a lean and responsive server experience.
- Instantaneous Backups: Leverages Btrfs snapshots to create and transfer backups with zero server downtime or performance impact.
- Integrated Maintenance Toolkit: Includes wrapped commands for SSH, VNC, password management (KeePassXC), log streaming, RCON commands, and network testing (iPerf3).
- Simplified Client Access: Generates a public HTTP bucket with packwiz-compatible index, ZIP modpacks, and a simple all-in-one batch script that is perfect for complete newcomers who just want to jump straight into the game.
This guide will walk you through setting up the local environment and deploying a new Minecraft server from scratch.
Prerequisites:
- A local Windows machine to use the full developer environment and toolset. (Linux/macOS can use the deployment but will miss the maintenance toolkit).
- A remote server/VPS where the Minecraft server will be hosted. This guide assumes you know its configuration, VNC credentials, and a public IP address.
First, get the project code onto your local machine, using the "Download ZIP" button on GitHub.
Alternatively, use Git client:
# Clone the repository
git clone https://github.com/nadvotsky/mineismine.git
cd mineismineEdit the provided sample config.xml configuration file.
Most defaults work out of the box — you typically only need to adjust:
- Server IP address
- RAM allocation for JVM
- Player whitelist
- Modpack selections
Check the Configuration Reference for detailed explanations of all options.
Windows:
Just run env.cmd, which will:
Linux/macOS:
Install uv manually:
curl -LsSf https://astral.sh/uv/install.sh | shIt is time to install Void Linux on the remote server. This lightweight, high-performance distribution is specifically chosen for optimal Minecraft server hosting.
Hint: Void Linux offers regional mirrors. If the default download is slow, pick one closer to you.
Many server providers do not offer Void Linux as a standard image. If you
cannot boot an .iso file directly, do not worry! Follow the
GRUB ISO Boot for a detailed guide on installing it from
another Linux environment using a GRUB trick.
During the installation, ensure you format the root partition with Btrfs, as this is required for the snapshot-based backup system.
Tip: ClickPaste is your friend for sharing clipboard contents as keystrokes.
# Open secure password storage
uv run src/tools.py keepassxc
# Connect to the server, and start ClickPaste.
uv run src/tools.py vncBy default, Void Linux disables root login with a password over SSH. Use VNC to re-enable it temporarily:
# On the server, enable temporary password login
echo 'PermitRootLogin yes' > /etc/ssh/sshd_config.d/10-permit-root.conf
sv restart sshdBack on your local machine, generate and deploy SSH keys:
# Windows: Auto-generate key pairs (will fail to connect then)
uv run src\tools.py ssh
# Linux/macOS: Manual key generation
ssh-keygen -C "mineismine: main" -f persist/id_main
ssh-keygen -C "mineismine: backup" -f persist/id_backup
# Deploy SSH configuration
uv run src/deploy.py sshNow that the key is installed, disable password login on the server:
rm -f /etc/ssh/sshd_config.d/10-permit-root.conf
sv restart sshdFrom now on, all interactions with the server should happen over our secure SSH connection. It is also a great time to change the root password if you used a simple one during setup.
With the host prepared and configured, you can now provision everything with a single command on the local machine.
The script is idempotent, meaning you can run it multiple times, and it will only apply necessary changes.
# List all deployment targets
uv run src/deploy.py all
# This installs and configures everything
uv run src/deploy.py minecraft
# Or step-by-step for granular control
uv run src/deploy.py ssh
uv run src/deploy.py kernel
uv run src/deploy.py misc
uv run src/deploy.py system
uv run src/deploy.py bucket
uv run src/deploy.py modpacks
uv run src/deploy.py minecraftImportant: Reboot the server after the first deployment to apply kernel command-line parameters.
Connect to the server via SSH:
# Windows
uv run src\tools.py ssh
# Other Platforms
ssh root@<SERVER_IP> -i persist/id_mainStart the Minecraft service manually to watch the logs for any first-run errors:
# This command runs the server in the foreground
/etc/sv/minecraft/runCheck the server startup and visit the public file server in the browser. You can also download the client installer and ZIP modpack to test how it works.
If everything looks good, press Ctrl+C to stop the server and start it
properly as a background service:
# Start the service
sv up minecraft
# Optional: Enable the service to start automatically on boot
sv enable minecraftCongratulations! The server is now live and ready for players.
- System Maintenance — learn about the helpful commands for managing the server.
- Configuration Reference — fine-tune every bit of the setup.
- Hacking Guide — customize the setup even further.
All project configuration is centralized in the config.xml
file. The file consists of a single global dictionary named mineismine.
Paths: All path values can be relative or absolute. They also support environment variable expansion (e.g.,
%TEMP%on Windows, or$HOMEon Linux).Lists: Values for lists can be separated by whitespaces for multi-line strings, or by semicolons (
;) for inline lists.
Minecraft version to install, such as: 1.21.1.
Settings for the local development machine.
Paths for storing local data and caches.
| Key | Description |
|---|---|
ssh |
SSH keys |
backups |
Downloaded server archives |
vault |
KeePass vault |
pycache |
Python's bytecode cache |
uvcache |
Package cache for uv |
uvpython |
Downloaded Python distributions by uv |
ruff |
Cached data for Ruff linter |
Paths for the portable tools used by the Windows toolkit.
| Tool | Description |
|---|---|
rio |
Rio terminal |
uv |
uv package manager |
keepassxc |
KeePassXC password manager |
openssh |
OpenSSH secure shell |
tigervnc |
TigerVNC client |
clickpaste |
ClickPaste clipboard emulator |
iperf |
iPerf network testing |
Settings for the remote server.
The IP address or hostname of the remote server.
The VNC address of the remote server, including the port (e.g.,
127.0.0.1:5901).
A boolean (true or false) that controls whether to automatically update all
mods to their latest compatible versions on each server startup.
Critical paths on the remote server. Usually, there is no need to change defaults.
java: Location of the GraalVM JVM.bucket: Root directory for the public Caddy file server.modpacks: Internal storage for the modpack index and state.backups: Directory for storing temporary and pending Btrfs backup snapshots.
This section maps to
server.properties file.
port: The Minecraft server port.seed: The world seed.difficulty: World difficulty (peaceful,easy,normal,hard).motd: The "Message of the Day" displayed in the server list.players: A list of whitelisted player nicknames.distancesimulation: The simulation distance.view: The view distance.
A list of JVM arguments for GraalVM.
Pay close attention to the
-Xmsand-Xmxflags, which control the Java heap size (e.g.,-Xms6G -Xmx6G). It is generally recommended to allocate 80-90% of the server's available RAM to leave room (~1-2G) for the kernel, system services, and the JVM's own non-heap memory usage (metaspace, stack, etc.).
Modpacks definitions. Each modpack is a dictionary named after the pack.
Each modpack needs to use its own XML dictionary.
side: Can beserver,client, orall. Anallpack is volatile and can only be included by other packs.include: Optional list of other modpack names to include. This is not recursive.items: A list of download links for mods from Modrinth or CurseForge. May point to the specific version of a mod (e.g. https://modrinth.com/mod/sodium/version/mc1.21.1-0.6.13-fabric).
Important: If using specific versions, set
server.modupdatetofalseto avoid them from being overwritten.
Quick-start client launcher configuration.
language: The default language for the Minecraft (e.g.,en_us).jvmargs: A list of JVM arguments for the client.
The project includes a suite of convenient commands to manage, debug, and interact with the server. All tools are Windows-compatible.
# List available tools
uv run src\tools.pyInstalls OpenSSH (if needed), generates key pairs, and opens an SSH session to the remote machine using the provisioned main key.
Configuration:
Fetches a new backup from the remote server.
Backups are only when requested; once they are it is performed instantly using Btrfs snapshots, meaning there is no lag or downtime on the game server during the process.
The backup operation uses a dedicated, restricted SSH key for enhanced security
(it is safe to share with moderators). The resulting archive is a
Zstandard-compressed tar file (.tar.zst), which provides a trade-off between
compression speed and compression ratio.
A fork of 7z archver, 7-Zip-zstd may be used to open such archives in a friendly GUI.
Configuration:
Source:
Downloads and runs iPerf3 for bandwidth testing.
Pass the --reverse flag to test the download speed from the server to
the local machine.
Configuration:
Downloads and runs the KeePassXC password manager. It is good practice to store sensitive data like server passwords here.
Configuration:
Live tail of Minecraft server logs over SSH.
Executes a command on the running Minecraft server via RCON.
The command must be passed as an argument.
See Also:
Downloads VNC suite which includes TigerVNC and ClickPaste.
Opens a TigerVNC session to the remote machine. Also launches ClickPaste, a utility that emulates typing, which is very useful for pasting long text into VNC sessions.
Configuration:
There is much more about this project, including various nuances about almost each component. It is opinionated because it is built to solve a specific problem in a specific way. The core philosophy is to create a reproducible, high-performance server environment with minimal manual intervention, using a stack of modern, yet lightweight technologies.
Below is a quick reference of the folder hierarchy and key components:
.
├── config.xml # Main configuration
├── env.cmd # Windows zero-dependency developer environment setup
├── persist/ # Directory for persistent data (e.g., SSH keys)
├── share/ # Deployment templates
│ ├── bucket/ # Files for the Caddy file server
│ ├── linux/ # System-level configs (GRUB, rc.local)
│ ├── minecraft/ # Minecraft service definition and server.properties
│ ├── modpacks/ # A place to add custom config files for specific mods
│ └── ssh/ # SSH daemon configuration templates
└── src/ # Python source code
├── common/ # Shared utilities like the config parser
├── deploy/ # The main deployment logic and tasks
│ ├── connection/ # SSH/remote utilities
│ ├── paths/ # Path models
│ └── tasks/ # Individual deployment tasks
├── helpers/ # Other shared components
└── tools/ # The client-side maintenance toolkit scripts
Note on
share/modpacks: Files you place here will be synchronized to as a regular configuration files. However, the synchronization only happens if the file does not already exist, preventing user-modified configurations from being overwritten. This allows to preconfigure both server and client mods.
If there is no possibility to boot from an .iso directly, you can use this
method to chainload the Void installer from an existing Linux installation.
This example uses Alpine Linux as an example, which is common on VPS panels.
1. Start by logging in as root and download the Void Linux live image:
curl https://repo-fastly.voidlinux.org/live/current/void-live-x86_64-<DATE>-base.iso --output /root/void.iso2. Install GRUB:
apk add grub grub-bios grub-efi efibootmgr
# List available disks
fdisk -l
grub-install /dev/<DISK>
# Disable GRUB timeout and regenerate the configuration
echo 'GRUB_TIMEOUT=0' > /etc/default/grub
grub-mkconfig -o /boot/grub/grub.cfg3. Find the root device path:
Reboot the system and open GRUB console using the C key. Then find the root
device arc as shown on the image:
4. Create a custom GRUB entry:
cat <<EOF > /etc/grub.d/40_custom
#!/bin/sh
exec tail -n +3 \$0
menuentry "Void Linux" {
# Replace with the correct root device
set isofull=(hd0,msdos3)/root/void.iso
set isoroot=/root/void.iso
loopback loop \$isofull
probe --set isolabel --label (loop)
linux (loop)/boot/vmlinuz iso-scan/filename=\${isoroot} root=live:CDLABEL=\${isolabel} ro init=/sbin/init rd.luks=0 rd.md=0 rd.dm=0 loglevel=4 gpt add_efi_memmap vconsole.unicode=1 vconsole.keymap=us locale.LANG=en_US.UTF-8 rd.live.ram
initrd (loop)/boot/initrd
}
EOF
# Regenerate GRUB configuration
grub-mkconfig -o /boot/grub/grub.cfg5. Boot Void Linux:
Reboot the system. At the GRUB menu, select "Void Linux". This will load the installer into RAM, allowing to wipe the disk and perform a standard installation.
This project stands on the shoulders of giants! Thanks to the developers and communities behind these incredible open-source projects:
Automation:
- Python programming language and
the Astral team for
uvandruff. - Fabric Python library for SSH automation.
Infrastructure:
- Void Linux team for a radically different and powerful OS.
- Caddy web server for a secure file server.
- Ruby programming language.
Minecraft:
- FabricMC team for the amazing mod loader and community.
- packwiz project for a complex modpack management solution.
- console-minecraft-launcher for an incredible launcher experience.
- Modrinth and CurseForge for Minecraft content.
...and the countless other projects that these depend on!
This project is licensed under the MIT License. You are free to use, modify, and distribute this software, but please provide attribution.