Complete Mindustry Server Setup Guide

1. System Requirements & Preparation

Mindustry is lighter than many survival game servers, but large public maps, late-wave enemy pathfinding, and heavy logic use can still push CPU and RAM higher than a private test world.

Minimum System Requirements:

• CPU: 1 CPU Core (1.5 GHz or higher) is sufficient to launch the server, but 2+ GHz is recommended.
• RAM: 512 MB to 1 GB. If you are running multiple gigantic sectors concurrently, 2 GB is safer.
• Storage: 2 GB minimum for the OS, Java, and the server jars, plus overhead for heavy maps. Fast NVMe storage ensures rapid map reloads.
• Network: 10 Mbps Up/Down. For large-scale warfare, latency matters, so a fiber or high-speed data center link is critical.
• Java Runtime: Use a current supported OpenJDK release and keep it aligned with the server build you deploy.

2. Installing Prerequisites (Java & Packages)

Before launching the server, you need an appropriate Java runtime environment. The Mindustry headless server relies entirely on the JVM (Java Virtual Machine).

Connect to your Linux server (Ubuntu/Debian is used here as an example) using SSH or your provider's web console. Update your package manager:

sudo apt update && sudo apt upgrade -y

Install OpenJDK 17 and `wget` to automatically download the server JAR:

sudo apt install openjdk-17-jre-headless wget unzip jq -y

Verifying Java: After installation, confirm that Java is correctly mapped in your environment:

java -version

If Java returns a healthy version string, the host is ready to run the server jar.

3. Downloading the Headless Server Jar

Creating a dedicated user to run Mindustry is a fundamental security best practice. Running servers as the root user exposes your entire operating system to potential exploits if the server software or a mod becomes compromised.

sudo adduser --disabled-login mindustry
sudo su - mindustry
mkdir ~/server
cd ~/server

Download the current headless server jar from the official GitHub releases page. Do not hardcode an old release into your automation; pin the version you actually intend to run.

# Replace vXXX with the release you want to run
wget https://github.com/Anuken/Mindustry/releases/download/vXXX/server-release.jar -O server.jar

Saving it as server.jar makes later service updates and rollbacks much easier.

4. Running and Provisioning Files

Launch the server manually to allow it to generate its foundational directory structure, including configurations, maps folder, mods folder, and logs:

java -Xms512M -Xmx1024M -jar server.jar

The -Xms and -Xmx flags allocate the initial and maximum heap size. You should adjust this based on the RAM availability you previously secured. As the server initializes, it will output logs indicating it is waiting for commands.

To safely stop the newly initialized server, type exit into the console and hit Enter. Never force close the server (unless frozen) as that can occasionally corrupt in-memory map savings.

Review the generated directory structure:

• config/ - Contains settings, bans, and admin IP configurations.
• maps/ - Drop your `.msav` custom map files here.
• mods/ - Drop your plugin and modification `.jar` files here.
• saves/ - Contains the active sector saves.

5. Configuring Server Settings

Mindustry creates its config and data directories on first launch. Depending on build and workflow, you may edit the generated config file directly or manage the same values through your server console and automation scripts.

Key values to review include:

• name: Your server's public name visible on the multiplayer browser. Use something catchy and descriptive (e.g., "Rusty Bolts - Vanilla PvE 24/7").
• desc: A brief description telling users what rules apply, if a Discord link is provided, etc.
• port: Default is `6567`. Change this if you are running multiple servers on a single IP address.
• logging: Set to `true` to keep comprehensive `.txt` file logs of all chat and errors.
• max players and rules: Keep these aligned with the map size and the type of public server you want to run.

6. Port Forwarding and Firewalls

For players outside your LAN to connect, port 6567 must be open on the host and any upstream firewall layers.

UFW (Ubuntu/Debian Firewall): If you use UFW, execute the following commands:

sudo ufw allow 6567/tcp
sudo ufw allow 6567/udp
sudo ufw reload

For home networks, you MUST log in to your router's administrative web interface (usually `192.168.0.1` or `192.168.1.1`). Locate the "WAN" or "Port Forwarding" tab, add a new rule covering ports 6567 for both protocols, and point it to the local IPv4 address of the computer hosting the jar.

7. Automating Startup with systemd

A systemd service gives you clean restarts, boot-time startup, and consistent logs.

Exit back to your root user (or sudo-capable user) and create a service file:

sudo nano /etc/systemd/system/mindustry.service

Use a simple service definition instead of a TTY-bound setup:

[Unit]
Description=Mindustry Headless Server
After=network.target

[Service]
Type=simple
User=mindustry
WorkingDirectory=/home/mindustry/server
ExecStart=/usr/bin/java -Xms512M -Xmx1G -jar server.jar
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Now, reload the systemd daemon, enable the service to start implicitly on boot, and initiate it:

sudo systemctl daemon-reload
sudo systemctl enable mindustry.service
sudo systemctl start mindustry.service

To inspect logs after startup, use:

sudo journalctl -u mindustry.service -f

8. Managing Maps and Campaigns

Mindustry is not very interesting until you host a real map. Create or export a map from the client, upload the .msav file into your server's map directory, and then host it from the server console.

Then, connect via console (or RCON if configured) and run:

host mapname survival

The server will instantly load the map and begin accepting players. You can interchangeably host PvP, Attack, or Survival maps.

For public communities, it is worth curating a short set of maps first instead of opening with an unbounded dump of community content.

9. Common Troubleshooting Solutions

While hosting, you might encounter issues. Here are the most persistent problems and immediate resolutions:

• java.lang.OutOfMemoryError: Your factory has expanded too greatly for the `-Xmx` limit. Increase `1024M` to `2048M` or higher. Check if a memory leak mod is responsible.
• Connection Refused/Timed Out: Confirm that your hosting provider (like AWS, Azure, or Hetzner) hasn't blocked UDP ports at their broader firewall dashboard. Check UFW rules internally.
• Version Mismatch: If clients and server are on different builds, they will not join cleanly. Verify the exact jar version deployed instead of guessing from filenames.