Skip to content

initial-setup.md

Latest commit

 

History

History
415 lines (290 loc) · 10.6 KB

initial-setup.md

File metadata and controls

415 lines (290 loc) · 10.6 KB

Complete Minecraft Server Setup Guide

This guide walks you through setting up a Minecraft Fabric server on a Raspberry Pi from scratch. If you're starting fresh, this is where you want to begin.

Table of Contents

What You'll Need

  • Raspberry Pi (Pi 4 or 5 recommended, 4GB+ RAM)
  • Raspberry Pi OS installed (64-bit recommended)
  • Internet connection
  • Domain name (optional, for TCPShield setup)
  • Router access (for port forwarding)

Step 1: Update Your System

First, make sure everything is up to date:

sudo apt update
sudo apt upgrade -y

Step 2: Install Java

Minecraft 1.21+ requires Java 21. Since Raspberry Pi OS doesn't have Java 21 in the default repos yet, we'll use Adoptium (Eclipse Temurin):

Installing Java 21 on Raspberry Pi OS

1. Install prerequisites:

sudo apt install wget apt-transport-https gpg -y

2. Add Adoptium repository:

wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo gpg --dearmor -o /usr/share/keyrings/adoptium.gpg
echo "deb [signed-by=/usr/share/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/adoptium.list

3. Update and install Java 21:

sudo apt update
sudo apt install temurin-21-jdk -y

4. Verify it installed correctly:

java -version

You should see something like:

openjdk version "21.0.x"
Eclipse Adoptium

For Older Minecraft Versions

Java requirements:

  • Minecraft 1.17-1.20.4: Java 17
  • Minecraft 1.20.5-1.20.6: Java 17 or 21
  • Minecraft 1.21+: Java 21 required

To install Java 17 (available in default repos):

sudo apt install openjdk-17-jre-headless -y

Step 3: Create Server Directory

Set up a dedicated location for your server:

sudo mkdir -p /opt/minecraft/server
cd /opt/minecraft/server

Step 4: Download Fabric Server

Go to https://fabricmc.net/use/server/ to get the latest Fabric server installer.

Download the installer:

# Download Fabric installer (get latest version from fabricmc.net)
wget https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.0.1/fabric-installer-1.0.1.jar -O fabric-installer.jar

Run the installer:

For Minecraft 1.21.10 (replace version as needed):

sudo java -jar fabric-installer.jar server -mcversion 1.21.10 -downloadMinecraft

This will:

  • Download the Minecraft server JAR
  • Install Fabric loader
  • Create fabric-server-1.21.10.jar

Accept the EULA:

sudo nano eula.txt

Change eula=false to eula=true, then save (Ctrl+O, Enter, Ctrl+X).

Step 5: First Test Run

Let's make sure it works before setting up auto-restart:

java -Xms2G -Xmx4G -jar fabric-server-1.21.10.jar nogui

What the flags mean:

  • -Xms2G - Minimum RAM (2GB)
  • -Xmx4G - Maximum RAM (4GB)
  • nogui - Run without GUI (required for headless servers)

Adjust RAM based on your Pi:

  • Pi with 4GB RAM: -Xms1G -Xmx3G
  • Pi with 8GB RAM: -Xms2G -Xmx5G

The server should start up and generate the world. Once you see:

[Server thread/INFO]: Done (XX.XXXs)! For help, type "help"

Type stop to shut it down gracefully.

Step 6: Configure Server Settings

Edit the server properties:

sudo nano server.properties

Important settings to check:

# Server port (default is fine unless you need a different port)
server-port=25565

# Online mode (true = requires Mojang authentication)
online-mode=true

# Max players
max-players=20

# View distance (lower = better performance)
view-distance=10

# MOTD (server name shown in multiplayer list)
motd=My Awesome Server

# Difficulty
difficulty=normal

# Game mode
gamemode=survival

Save and exit (Ctrl+O, Enter, Ctrl+X).

Step 7: Add Performance Mods (Recommended)

Performance mods help your Pi run the server better. Here are the essentials:

Download these from Modrinth:

  1. Fabric API - Required by most mods
  2. Lithium - Server optimizations
  3. Krypton - Network optimizations
  4. ServerCore - Various server improvements
  5. FerriteCore - Memory optimization

Install them:

# Create mods folder
sudo mkdir -p /opt/minecraft/server/mods

# Download mods (example for Lithium)
cd /opt/minecraft/server/mods
sudo wget [download URL from Modrinth] -O lithium.jar

# Repeat for each mod

Or upload from your computer:

# On your computer (replace 'pi' with your actual username if different):
scp mod-file.jar pi@your-pi-ip:/home/pi/

# On your Pi:
sudo mv /home/pi/mod-file.jar /opt/minecraft/server/mods/

Step 8: Set Up Port Forwarding

For players outside your network to connect, you need to forward port 25565.

On your router:

  1. Log into your router (usually 192.168.1.1 or 192.168.0.1)
  2. Find "Port Forwarding" or "Virtual Server"
  3. Add a new rule:
    • Name: Minecraft
    • External Port: 25565
    • Internal IP: Your Pi's IP (find it with hostname -I)
    • Internal Port: 25565
    • Protocol: TCP or Both

Test if it's open:

Step 9: Set Up Auto-Restart (Optional but Recommended)

Using systemd, your server will auto-start on boot and restart if it crashes.

Create a minecraft user:

sudo useradd -r -m -d /opt/minecraft minecraft
sudo chown -R minecraft:minecraft /opt/minecraft/server

Create the service file:

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

Paste this (adjust RAM and version as needed):

[Unit]
Description=Minecraft Server 1.21.10
After=network.target

[Service]
Type=simple
User=minecraft
WorkingDirectory=/opt/minecraft/server
ExecStart=/usr/bin/java -Xms2G -Xmx5G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -jar fabric-server-1.21.10.jar nogui
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Save and exit.

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable minecraft
sudo systemctl start minecraft

Check if it's running:

sudo systemctl status minecraft

View logs:

sudo journalctl -u minecraft -f

See the systemd setup guide for more details.

Step 10: Connect to Your Server

You can now connect using:

From your local network:

  • Use your Pi's local IP: 192.168.x.x:25565

From outside your network:

  • Use your public IP: [your-public-ip]:25565
  • Or set up a domain with TCPShield (see TCPShield guide)

In Minecraft:

  1. Open Minecraft (same version as your server!)
  2. Go to Multiplayer
  3. Click "Add Server"
  4. Enter your server address
  5. Click "Done" and join!

Next Steps

Now that your server is running, you might want to:

  1. Set up DDoS protection - Follow the TCPShield guide to protect your server and get a domain name
  2. Add more mods - Check out the mods and versions guide
  3. Configure the server - Explore server.properties and mod configs in /opt/minecraft/server/config/
  4. Set up backups - Use rsync or similar to backup your world regularly

Troubleshooting

Server won't start

Check the logs:

sudo journalctl -u minecraft -n 50

Common issues:

  • Not enough RAM - Reduce -Xms and -Xmx values
  • Wrong Java version - Make sure you have Java 21 for Minecraft 1.21+
  • EULA not accepted - Make sure eula.txt says eula=true
  • Port already in use - Check if another server is running

Can't connect from outside network

Checklist:

  • Port forwarding is set up correctly
  • Port 25565 is open (test with yougetsignal.com)
  • Server is running (sudo systemctl status minecraft)
  • Using correct public IP address
  • Firewall isn't blocking the connection

Check your Pi's firewall:

sudo ufw status

If UFW is active, allow port 25565:

sudo ufw allow 25565/tcp

Performance issues

If your server is laggy:

  1. Reduce view distance in server.properties:

    view-distance=8

  2. Lower max players:

    max-players=10

  3. Add performance mods (Lithium, Krypton, ServerCore)

  4. Pre-generate your world using Chunky mod

  5. Monitor resources:

    htop

  6. Reduce RAM if you don't have enough - Pi needs RAM for OS too

Players can't authenticate

If players get "Failed to verify username":

  • Make sure online-mode=true in server.properties
  • Check that your server can reach Mojang's authentication servers
  • Test your internet connection

Tips and Best Practices

  1. Regular backups - Back up your world folder regularly:

    sudo cp -r /opt/minecraft/server/world /opt/minecraft/backups/world-$(date +%Y%m%d)

  2. Use a domain - Much easier than remembering IP addresses

  3. Monitor your server - Check logs occasionally for errors

  4. Keep Java updated - Run sudo apt update && sudo apt upgrade regularly

  5. Don't expose your Pi directly - Use TCPShield or similar for DDoS protection

  6. Be careful with mods - Too many mods can slow down your server

That's it! You now have a fully functional Minecraft server running on your Raspberry Pi. Enjoy!