Complete Guide to Hosting a Minecraft Server with PaperMC

Table of Contents

1. Introduction
2. Prerequisites
3. Installing Java
4. Downloading PaperMC
5. Initial Server Setup
6. Server Configuration
7. Port Forwarding
8. Installing Plugins
9. Server Optimization
10. Backup and Maintenance
11. Troubleshooting

---

Introduction

PaperMC is a high-performance Minecraft server software that offers significant improvements over the vanilla server in terms of performance, stability, and plugin compatibility. This guide will walk you through every step of setting up your own Minecraft server using PaperMC.

Why Choose PaperMC?

• Better Performance: Optimized for speed and efficiency
• Plugin Support: Compatible with Bukkit and Spigot plugins
• Active Development: Regular updates and bug fixes
• Configuration Options: Extensive customization capabilities
• Community Support: Large community and documentation

Download PaperMC

---

Prerequisites

Before we begin, ensure you have the following:

Hardware Requirements

Software Requirements

• Operating System: Windows 10/11, Linux (Ubuntu/Debian), or macOS
• Java: Java 21 (for Minecraft 1.20.5+)
• Internet Connection: Stable broadband connection
• Administrator Access: Required for installation

---

Installing Java

Java is essential for running Minecraft servers. PaperMC requires specific Java versions depending on your Minecraft version.

For Windows

Step 1: Download Java

Visit the official Java download page or use one of these options:

Download Java 21 (Adoptium)

Step 2: Run the Installer

# After downloading, run the installer
# Accept the license agreement
# Choose installation directory (default is fine)
# Complete the installation

Step 3: Verify Installation

Open Command Prompt and run:

java -version

Expected output:

openjdk version "21.0.1" 2023-10-17
OpenJDK Runtime Environment Temurin-21.0.1+12 (build 21.0.1+12)
OpenJDK 64-Bit Server VM Temurin-21.0.1+12 (build 21.0.1+12, mixed mode, sharing)

For Linux (Ubuntu/Debian)

Step 1: Update Package List

sudo apt update
sudo apt upgrade -y

Step 2: Install Java

# Install Java 21
sudo apt install openjdk-21-jdk -y

Step 3: Verify Installation

java -version

Step 4: Set Java Home (if needed)

# Add to ~/.bashrc or ~/.bash_profile
echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64' >> ~/.bashrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

For macOS

Step 1: Install Homebrew (if not installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2: Install Java

brew install openjdk@21

Step 3: Link Java

sudo ln -sfn /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk

Step 4: Verify Installation

java -version

---

Downloading PaperMC

Now we'll download the PaperMC server software.

Method 1: Manual Download

Step 1: Visit the PaperMC Website

Go to PaperMC Downloads

Step 2: Select Your Minecraft Version

Choose the version you want to run (e.g., 1.20.4, 1.21, etc.)

Step 3: Download the JAR File

Click the download button for the latest build. The file will be named something like paper-1.20.4-###.jar

Method 2: Command Line Download (Linux/macOS)

# Create server directory
mkdir minecraft-server
cd minecraft-server

# Download latest Paper for version 1.20.4 (example)
wget https://api.papermc.io/v2/projects/paper/versions/1.20.4/builds/496/downloads/paper-1.20.4-496.jar -O paper.jar

# Or use curl
curl -o paper.jar https://api.papermc.io/v2/projects/paper/versions/1.20.4/builds/496/downloads/paper-1.20.4-496.jar

Method 3: Using a Script (Recommended)

Create a download script for automatic updates:

For Linux/macOS (download.sh):

#!/bin/bash

VERSION="1.20.4"
BUILD=$(curl -s "https://api.papermc.io/v2/projects/paper/versions/${VERSION}" | grep -oP '"builds":\[\K[0-9]+' | tail -1)
DOWNLOAD_URL="https://api.papermc.io/v2/projects/paper/versions/${VERSION}/builds/${BUILD}/downloads/paper-${VERSION}-${BUILD}.jar"

echo "Downloading PaperMC ${VERSION} build ${BUILD}..."
curl -o paper.jar "$DOWNLOAD_URL"
echo "Download complete!"

Make it executable:

chmod +x download.sh
./download.sh

For Windows (download.bat):

@echo off
set VERSION=1.20.4
set BUILD=496

echo Downloading PaperMC %VERSION% build %BUILD%...
curl -o paper.jar https://api.papermc.io/v2/projects/paper/versions/%VERSION%/builds/%BUILD%/downloads/paper-%VERSION%-%BUILD%.jar
echo Download complete!
pause

---

Initial Server Setup

Now that we have Java and PaperMC downloaded, let's set up the server.

Step 1: Create Server Directory Structure

# Create main directory
mkdir minecraft-server
cd minecraft-server

# Create subdirectories
mkdir plugins
mkdir worlds
mkdir backups
mkdir logs

Your directory structure should look like:

minecraft-server/
├── paper.jar
├── plugins/
├── worlds/
├── backups/
└── logs/

Step 2: First Run

We need to run the server once to generate configuration files.

For Linux/macOS:

java -Xmx2G -Xms2G -jar paper.jar --nogui

For Windows:

java -Xmx2G -Xms2G -jar paper.jar --nogui

The server will generate files and stop, showing a message about the EULA.

Step 3: Accept the EULA

Open the eula.txt file that was generated:

#By changing the setting below to TRUE you are indicating your agreement to our EULA (https://aka.ms/MinecraftEULA).
eula=false

Change eula=false to eula=true:

#By changing the setting below to TRUE you are indicating your agreement to our EULA (https://aka.ms/MinecraftEULA).
eula=true

Command line method:

# Linux/macOS
echo "eula=true" > eula.txt

# Windows PowerShell
echo "eula=true" | Out-File -FilePath eula.txt -Encoding ASCII

Step 4: Create Start Script

Create a proper startup script for your server.

For Linux/macOS (start.sh):

#!/bin/bash

# Configuration
JAR_NAME="paper.jar"
MIN_RAM="2G"
MAX_RAM="4G"
JAVA_FLAGS="-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -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 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true"

# Start server
java -Xms${MIN_RAM} -Xmx${MAX_RAM} ${JAVA_FLAGS} -jar ${JAR_NAME} --nogui

# Restart on crash
echo "Server stopped. Restarting in 5 seconds..."
echo "Press Ctrl+C to cancel."
sleep 5
exec bash start.sh

Make it executable:

chmod +x start.sh

For Windows (start.bat):

@echo off
title Minecraft Server

:start
java -Xms2G -Xmx4G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -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 paper.jar --nogui

echo Server stopped. Restarting in 5 seconds...
echo Press Ctrl+C to cancel.
timeout /t 5
goto start

Step 5: Start the Server

Run your start script:

# Linux/macOS
./start.sh

# Windows
start.bat

The server will now generate the world and start up. This may take a few minutes on the first run.

---

Server Configuration

PaperMC generates several configuration files. Let's configure the most important ones.

server.properties

This is the main configuration file for your Minecraft server.

# Server Properties Configuration

# Basic Settings
server-name=My Minecraft Server
motd=Welcome to My Server!
server-port=25565
max-players=20
online-mode=true
white-list=false

# World Settings
level-name=world
level-seed=
gamemode=survival
difficulty=normal
hardcore=false
pvp=true
spawn-protection=16
max-world-size=29999984

# Performance Settings
view-distance=10
simulation-distance=10
network-compression-threshold=256
max-tick-time=60000

# Player Settings
allow-flight=false
spawn-monsters=true
spawn-animals=true
spawn-npcs=true

# Advanced Settings
enable-command-block=false
enable-query=false
enable-rcon=false
rcon.password=
rcon.port=25575

Key settings explained:

• server-port: The port your server runs on (default 25565)
• max-players: Maximum number of players allowed
• view-distance: How far players can see (lower = better performance)
• online-mode: Requires Mojang authentication (keep true for security)

paper-global.yml

PaperMC's global configuration file:

# Paper Global Configuration

_version: 28

timings:
  enabled: true
  verbose: true
  url: https://timings.aikar.co

console:
  enable-brigadier-highlighting: true
  enable-brigadier-completions: true

chunk-loading:
  max-concurrent-sends: 2
  autoconfig-send-distance: true
  enable-frustum-priority: false
  global-max-chunk-load-rate: -1.0
  global-max-chunk-send-rate: -1.0
  global-max-concurrent-loads: 500.0
  player-max-chunk-load-rate: -1.0
  player-max-concurrent-loads: 20.0

commands:
  fix-target-selector-tag-completion: true
  suggest-player-names-when-null-tab-completions: true
  time-command-affects-all-worlds: false

misc:
  fix-entity-position-desync: true
  load-permissions-yml-before-plugins: true
  region-file-cache-size: 256
  use-alternative-luck-formula: false
  use-dimension-type-for-custom-spawners: false

paper-world-defaults.yml

World-specific configurations:

# Paper World Configuration

_version: 28

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 2
    max-block-height: 64
    update-radius: 2
    lava-obscures: false
    use-permission: false
    hidden-blocks:
    - copper_ore
    - deepslate_copper_ore
    - gold_ore
    - deepslate_gold_ore
    - iron_ore
    - deepslate_iron_ore
    - coal_ore
    - deepslate_coal_ore
    - lapis_ore
    - deepslate_lapis_ore
    - mossy_cobblestone
    - obsidian
    - chest
    - diamond_ore
    - deepslate_diamond_ore
    - redstone_ore
    - deepslate_redstone_ore
    - clay
    - emerald_ore
    - deepslate_emerald_ore
    - ender_chest
    replacement-blocks:
    - stone
    - oak_planks
    - deepslate

entities:
  spawning:
    all-chunks-are-slime-chunks: false
    alt-item-despawn-rate:
      enabled: false
      items:
        cobblestone: 300
    count-all-mobs-for-spawning: false
    creative-arrow-despawn-rate: 300
    despawn-ranges:
      ambient:
        hard: 128
        soft: 32
      axolotls:
        hard: 128
        soft: 32
      creature:
        hard: 128
        soft: 32
      misc:
        hard: 128
        soft: 32
      monster:
        hard: 128
        soft: 32
      underground_water_creature:
        hard: 128
        soft: 32
      water_ambient:
        hard: 64
        soft: 32
      water_creature:
        hard: 128
        soft: 32

spigot.yml

Spigot-specific configurations:

# Spigot Configuration

settings:
  debug: false
  bungeecord: false
  player-shuffle: 0
  user-cache-size: 1000
  save-user-cache-on-stop-only: false
  moved-wrongly-threshold: 0.0625
  moved-too-quickly-multiplier: 10.0
  timeout-time: 60
  restart-on-crash: true
  restart-script: ./start.sh
  netty-threads: 4
  attribute:
    maxHealth:
      max: 2048.0
    movementSpeed:
      max: 2048.0
    attackDamage:
      max: 2048.0

world-settings:
  default:
    verbose: false
    hopper-amount: 1
    mob-spawn-range: 8
    view-distance: default
    entity-activation-range:
      animals: 32
      monsters: 32
      raiders: 48
      misc: 16
      water: 16
      villagers: 32
      flying-monsters: 32
    entity-tracking-range:
      players: 48
      animals: 48
      monsters: 48
      misc: 32
      other: 64
    ticks-per:
      hopper-transfer: 8
      hopper-check: 1
    merge-radius:
      item: 2.5
      exp: 3.0
    growth:
      cactus-modifier: 100
      cane-modifier: 100
      melon-modifier: 100
      mushroom-modifier: 100
      pumpkin-modifier: 100
      sapling-modifier: 100
      beetroot-modifier: 100
      carrot-modifier: 100
      potato-modifier: 100
      wheat-modifier: 100
      netherwart-modifier: 100
      vine-modifier: 100
      cocoa-modifier: 100
      bamboo-modifier: 100
      sweetberry-modifier: 100
      kelp-modifier: 100

bukkit.yml

Bukkit configuration:

# Bukkit Configuration

settings:
  allow-end: true
  warn-on-overload: true
  permissions-file: permissions.yml
  update-folder: update
  plugin-profiling: false
  connection-throttle: 4000
  query-plugins: true
  deprecated-verbose: default
  shutdown-message: Server closed
  minimum-api: none
  use-map-color-cache: true

spawn-limits:
  monsters: 70
  animals: 10
  water-animals: 5
  water-ambient: 20
  water-underground-creature: 5
  axolotls: 5
  ambient: 15

chunk-gc:
  period-in-ticks: 600

ticks-per:
  animal-spawns: 400
  monster-spawns: 1
  water-spawns: 1
  water-ambient-spawns: 1
  water-underground-creature-spawns: 1
  axolotl-spawns: 1
  ambient-spawns: 1
  autosave: 6000

aliases: now-in-commands.yml

---

Port Forwarding

To allow players from outside your network to connect, you need to forward port 25565.

Step 1: Find Your Local IP Address

Windows:

ipconfig

Look for "IPv4 Address" under your active network adapter (usually something like 192.168.1.xxx)

Linux/macOS:

ip addr show
# or
ifconfig

Step 2: Access Your Router

1. Open a web browser
2. Enter your router's IP address (commonly 192.168.1.1 or 192.168.0.1)
3. Login with your router credentials

Common router login addresses:

• 192.168.1.1
• 192.168.0.1
• 10.0.0.1
• 192.168.2.1

Step 3: Configure Port Forwarding

The exact steps vary by router, but generally:

1. Look for "Port Forwarding" or "Virtual Servers" or "NAT Forwarding"
2. Create a new port forwarding rule:

Service Name: Minecraft Server
External Port: 25565
Internal Port: 25565
Internal IP: [Your computer's local IP]
Protocol: TCP/UDP (or both)

Example configuration:

Step 4: Find Your Public IP

# Linux/macOS
curl ifconfig.me

# Or visit in browser

Visit: https://whatismyipaddress.com/

Your public IP is what players will use to connect: your.public.ip.address:25565

Step 5: Test Port Forwarding

Use an online port checker:

Check Port Status

Enter:

• IP Address: Your public IP
• Port: 25565

Alternative: Using a VPN Service (Easier Method)

If port forwarding is too complex, consider using services like:

• ngrok (Free tier available)
• Playit.gg (Free for Minecraft)
• ZeroTier (Free VPN network)

Example with Playit.gg:

# Download and install playit
wget https://playit.gg/downloads/playit-linux-amd64
chmod +x playit-linux-amd64
./playit-linux-amd64

Follow the on-screen instructions to get your server address.

---

Installing Plugins

Plugins add functionality to your server. Here are essential plugins and how to install them.

Step 1: Popular Essential Plugins

Step 2: Download Plugins

Download the .jar files for your desired plugins.

Example using wget:

cd plugins

# Download EssentialsX
wget https://github.com/EssentialsX/Essentials/releases/download/2.20.1/EssentialsX-2.20.1.jar

# Download LuckPerms
wget https://download.luckperms.net/1544/bukkit/loader/LuckPerms-Bukkit-5.4.134.jar

# Download Vault
wget https://github.com/milkbowl/Vault/releases/download/1.7.3/Vault.jar

Step 3: Install Plugins

Simply place the .jar files in the plugins folder:

minecraft-server/
├── paper.jar
├── plugins/
│   ├── EssentialsX-2.20.1.jar
│   ├── LuckPerms-Bukkit-5.4.134.jar
│   └── Vault.jar

Step 4: Restart Server

# Stop the server (in server console)
stop

# Start it again
./start.sh

Step 5: Configure Plugins

Each plugin creates its own configuration folder in plugins/:

plugins/
├── Essentials/
│   └── config.yml
├── LuckPerms/
│   └── config.yml
└── Vault/
    └── config.yml

Example: Configuring EssentialsX

Edit plugins/Essentials/config.yml:

# EssentialsX Configuration

# Server locale
locale: en

# Enable/disable features
teleport-cooldown: 5
teleport-delay: 3
heal-cooldown: 60

# Starting items for new players
starter-kit:
  - 272 1  # Stone sword
  - 260 10 # Apples
  - 50 32  # Torches

# Spawn settings
spawn-on-join: true
update-bed-at-daytime: true

# Economy settings
economy:
  enabled: true
  starting-balance: 1000

Example: Configuring LuckPerms

# Set up admin permissions in-game
lp user YourUsername permission set *
lp user YourUsername parent add admin

Or edit plugins/LuckPerms/config.yml:

# LuckPerms Configuration

server: server
storage-method: h2
data:
  pool-settings:
    maximum-pool-size: 10
    minimum-idle: 10
    maximum-lifetime: 1800000
    connection-timeout: 5000

messaging-service: auto
auto-op: false
verbose-logging: true

Step 6: Useful Plugin Commands

EssentialsX Commands:

/give <player> <item> [amount] - Give items
/tp <player> [target] - Teleport
/home [name] - Go to home
/spawn - Go to spawn
/warp <name> - Warp to location
/kit <name> - Get a kit

LuckPerms Commands:

/lp user <user> permission set <permission> - Set permission
/lp creategroup <name> - Create group
/lp user <user> parent add <group> - Add user to group
/lp group <group> permission set <permission> - Set group permission

CoreProtect Commands:

/co inspect - Toggle inspect mode
/co lookup - Lookup block data
/co rollback - Rollback changes
/co restore - Restore changes

---

Server Optimization

Optimize your server for better performance.

Memory Allocation

Adjust RAM based on player count:

Optimal Start Script (Aikar's Flags):

#!/bin/bash
java -Xms4G -Xmx4G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -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 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true -jar paper.jar --nogui

Performance Configuration

paper-world-defaults.yml optimizations:

# Optimize mob spawning
entities:
  spawning:
    despawn-ranges:
      monster:
        soft: 32
        hard: 128
      creature:
        soft: 32
        hard: 128
  
# Reduce lag from hoppers
hopper:
  cooldown-when-full: true
  disable-move-event: false

# Optimize redstone
redstone:
  disable-move-event: true
  
# Chunk settings  
chunks:
  auto-save-interval: 6000
  delay-chunk-unloads-by: 10s
  entity-per-chunk-save-limit:
    experience_orb: 16
    snowball: 16
    ender_pearl: 16
    arrow: 16

# Tick settings
tick-rates:
  sensor:
    villager:
      secondarypoisensor: 40
  behavior:
    villager:
      validatenearbypoi: -1

server.properties optimizations:

# Reduce view distance for better performance
view-distance=8
simulation-distance=6

# Entity tracking
entity-broadcast-range-percentage=75

# Network
network-compression-threshold=256

Timing Reports

Use timings to identify lag:

# In server console
/timings on
# Wait 5-10 minutes
/timings paste

This generates a report URL showing what's causing lag.

Optimization Plugins

Install performance plugins:

cd plugins

# ClearLag - Removes entities periodically
wget https://dev.bukkit.org/projects/clearlagg/files/latest

# FarmControl - Limits farm entities
wget https://www.spigotmc.org/resources/farmcontrol.86923/download?version=398123

ClearLag Configuration:

# plugins/Clearlag/config.yml

auto-removal:
  enabled: true
  broadcast-removal: true