How to Host a Multi-Server Minecraft Network using Velocity Proxy and Paper on Linux

Before deploying your network, ensure your infrastructure meets the following requirements:

• Operating System: Ubuntu 22.04 LTS / 24.04 LTS or Debian 12 (64-bit).

• System Privilege: Root or sudo user access.

• Network Ports: Port 25565 (TCP/UDP) publicly accessible for Velocity proxy connections.

• Architecture Design:

  • Velocity Proxy Node: Accepts public client connections on 0.0.0.0:25565 and handles Mojang user authentication.

  • Paper Lobby Node: Internal backend server running on 127.0.0.1:25566.

  • Paper Survival Node: Internal backend server running on 127.0.0.1:25567.

                  ┌───────────────────────────────┐
                  │    Public Client / Players    │
                  └──────────────┬────────────────┘
                                 │ Port 25565
                                 ▼
                  ┌───────────────────────────────┐
                  │      Velocity Proxy Node      │
                  │   (Handles Auth & Routing)    │
                  └───────┬───────────────┬───────┘
                          │               │
     Internal (127.0.0.1) │               │ Internal (127.0.0.1)
             Port 25566   │               │ Port 25567
                          ▼               ▼
                  ┌───────────────┐┌───────────────┐
                  │  Paper Lobby  ││Paper Survival │
                  └───────────────┘└───────────────┘
                                

1. Modern Minecraft versions (1.20.5 and above) require Java 21 LTS. Update the system package repository and install OpenJDK 21 along with essential command-line tools:

   Bash Copy

   
   sudo apt update && sudo apt upgrade -y
   sudo apt install -y openjdk-21-jre-headless curl wget tar jq ufw tmux
                                           

2. Verify that Java 21 is active:

   Bash Copy

   
   java -version
                                           

3. Create a dedicated system user minecraft to isolate game processes from root:

   Bash Copy

   
   sudo useradd -r -m -d /opt/minecraft -s /bin/bash minecraft
   sudo mkdir -p /opt/minecraft/{proxy,lobby,survival}
   sudo chown -R minecraft:minecraft /opt/minecraft
                                           

1. Switch to the minecraft user and navigate to the proxy directory:

   Bash Copy

   
   sudo su - minecraft
   cd /opt/minecraft/proxy
                                           

2. Fetch the latest build of Velocity Proxy directly from the PaperMC API:

   Bash Copy

   
   LATEST_VELOCITY_BUILD=$(curl -s https://api.papermc.io/v2/projects/velocity/versions/3.3.0-SNAPSHOT | jq '.builds[-1]')
   curl -o velocity.jar "https://api.papermc.io/v2/projects/velocity/versions/3.3.0-SNAPSHOT/builds/${LATEST_VELOCITY_BUILD}/downloads/velocity-${LATEST_VELOCITY_BUILD}.jar"
                                           

3. Start Velocity once to generate default configuration files and exit. Once you see the output [INFO]: Done, stop Velocity by typing end into the console.

   Bash Copy

   
   java -jar velocity.jar
                                           

4. Open velocity.toml in your text editor and modify the following key settings:

   TOML Copy

   
   bind = "0.0.0.0:25565"
   motd = "<blue>Welcome to our Network!</blue>"
   show-max-players = 500
   online-mode = true
   player-info-forwarding-mode = "modern"
   forwarding-secret-file = "forwarding.secret"
   
   [servers]
   lobby = "127.0.0.1:25566"
   survival = "127.0.0.1:25567"
   
   try = [
     "lobby"
   ]
   
   [forced-hosts]
   "lobby.yourdomain.com" = ["lobby"]
   "survival.yourdomain.com" = ["survival"]
                                           

   Important: Setting player-info-forwarding-mode = "modern" ensures Velocity cryptographically signs forwarded player UUIDs and IP addresses, preventing IP spoofing exploits.

5. When Velocity generates forwarding.secret, inspect its contents and record the generated key string:

   Bash Copy

   
   cat forwarding.secret
   # Example Output: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
                                           

Setting Up the Lobby Server

1. Navigate to the lobby directory and download the latest Paper build:

   Bash Copy

   
   cd /opt/minecraft/lobby
   LATEST_PAPER_BUILD=$(curl -s https://api.papermc.io/v2/projects/paper/versions/1.21.1 | jq '.builds[-1]')
   curl -o paper.jar "https://api.papermc.io/v2/projects/paper/versions/1.21.1/builds/${LATEST_PAPER_BUILD}/downloads/paper-1.21.1-${LATEST_PAPER_BUILD}.jar"
                                           

2. Accept the Minecraft EULA and generate the initial configuration files:

   Bash Copy

   
   echo "eula=true" > eula.txt
   java -jar paper.jar --nogui
                                           

   Stop the server once fully loaded by typing stop.

3. Edit server.properties for the Lobby server:

   Properties Copy

   
   server-ip=127.0.0.1
   server-port=25566
   online-mode=false
   network-compression-threshold=-1
   prevent-proxy-connections=false
                                           

   Why online-mode=false? The Velocity proxy handles authentication with Mojang servers. Backend Paper servers must run in offline mode internally, with security enforced via modern forwarding secrets.

Setting Up the Survival Server

1. Repeat the setup for the Survival server:

   Bash Copy

   
   cd /opt/minecraft/survival
   cp /opt/minecraft/lobby/paper.jar .
   echo "eula=true" > eula.txt
   java -jar paper.jar --nogui
                                           

   Stop the server, then edit its server.properties:

   Properties Copy

   
   server-ip=127.0.0.1
   server-port=25567
   online-mode=false
   network-compression-threshold=-1
                                           

1. To pass real player IP addresses, skins, and UUIDs safely from Velocity to Paper, you must configure paper-global.yml on every backend node. Edit the global configuration file for the Lobby server:

   Bash Copy

   
   nano /opt/minecraft/lobby/config/paper-global.yml
                                           

2. Locate the proxies block and update it as follows:

   YAML Copy

   
   proxies:
     bungeecord:
       false
     velocity:
       enabled: true
       online-mode: true
       secret: "PASTE_YOUR_FORWARDING_SECRET_HERE"
                                           

   Replace PASTE_YOUR_FORWARDING_SECRET_HERE with the exact key retrieved from /opt/minecraft/proxy/forwarding.secret in Step 2.

3. Repeat this configuration step for the Survival server:

   Bash Copy

   
   nano /opt/minecraft/survival/config/paper-global.yml
                                           

   Paste the exact same secret string into the proxies.velocity.secret field.

If a backend server is directly accessible from the internet, malicious users could bypass the Velocity proxy, log in with any username, and gain administrator access.

1. Localhost Binding: By setting server-ip=127.0.0.1 in server.properties, backend servers accept connections exclusively from local proxy sockets on the same machine.

2. UFW Firewall Configuration: Exit back to the root user to enforce system-level packet filtering:

   Bash Copy

   
   exit # Exits minecraft user shell back to root
   sudo ufw default deny incoming
   sudo ufw default allow outgoing
   sudo ufw allow 22/tcp
   sudo ufw allow 25565/tcp
   sudo ufw enable
                                           

Multi-Server Note: If your backend Paper servers run on separate dedicated physical servers from your proxy, leave server-ip=0.0.0.0 on the backends and enforce firewall whitelist rules allowing incoming traffic on ports 25566/25567 only from the Velocity Proxy's private IP address:

sudo ufw allow proto tcp from <VELOCITY_PROXY_IP> to any port 25566
                                

Create background systemd unit files to automatically launch, monitor, and manage your proxy and server nodes on system boot.

1. 1. Velocity Proxy Service: Create the service unit file:

   Bash Copy

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

   TOML Copy

   
   [Unit]
   Description=Velocity Minecraft Proxy Service
   After=network.target
   
   [Service]
   User=minecraft
   Group=minecraft
   WorkingDirectory=/opt/minecraft/proxy
   ExecStart=/usr/bin/java -Xms1024M -Xmx1024M -XX:+UseG1GC -jar velocity.jar
   Restart=on-failure
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
                                           

2. 2. Paper Lobby Service: Create the Lobby service unit file:

   Bash Copy

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

   TOML Copy

   
   [Unit]
   Description=Paper Minecraft Lobby Server
   After=network.target minecraft-proxy.service
   
   [Service]
   User=minecraft
   Group=minecraft
   WorkingDirectory=/opt/minecraft/lobby
   ExecStart=/usr/bin/java -Xms2048M -Xmx2048M -XX:+UseG1GC -jar paper.jar --nogui
   Restart=on-failure
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
                                           

3. 3. Paper Survival Service: Create the Survival service unit file:

   Bash Copy

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

   TOML Copy

   
   [Unit]
   Description=Paper Minecraft Survival Server
   After=network.target minecraft-proxy.service
   
   [Service]
   User=minecraft
   Group=minecraft
   WorkingDirectory=/opt/minecraft/survival
   ExecStart=/usr/bin/java -Xms4096M -Xmx4096M -XX:+UseG1GC -jar paper.jar --nogui
   Restart=on-failure
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
                                           

4. Reload systemd daemon, enable, and start all services:

   Bash Copy

   
   sudo systemctl daemon-reload
   sudo systemctl enable --now minecraft-proxy minecraft-lobby minecraft-survival
   sudo systemctl status minecraft-proxy minecraft-lobby minecraft-survival
                                           

To ensure your bare-metal hardware delivers maximum single-core clock throughput without lag or micro-stutters, apply kernel and Garbage Collector optimizations.

CPU Governor Set to Performance

Lock CPU cores to high performance to prevent dynamic frequency scaling latency during chunk generation:

sudo apt install -y cpupowerutils
sudo cpupower frequency-set -g performance
                                

Advanced Aikar JVM Flags

For Paper backend servers allocating 4GB or more RAM, update your systemd ExecStart line to use optimized Aikar's Flags for low-latency G1GC execution:

ExecStart=/usr/bin/java -Xms4096M -Xmx4096M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=15 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurviorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true -jar paper.jar --nogui
                                

Verification

Launch your Minecraft client, connect to your-server-ip:25565, and confirm that you join the Lobby server. Execute /server survival in-game to test cross-server switching via Velocity proxy.

Why use Velocity instead of BungeeCord?

Velocity is a modern, high-throughput proxy engineered to utilize multi-core server processors efficiently while offering superior packet handling and native DDoS resilience, unlike legacy BungeeCord setups.

Why must backend Paper servers run in offline mode?

The Velocity proxy handles authentication with Mojang servers. Backend Paper servers must run in offline mode internally, with security enforced via modern secret-based forwarding to prevent unauthorized access.

What Java version is required for modern Minecraft servers?

Modern Minecraft versions (1.20.5 and above) require Java 21 LTS.