# Minecraft Server + Velocity Proxy

> Scalable Minecraft network with proxy, multiple servers, and web management.

- Category: Home Lab & Self-Hosting
- Difficulty: advanced
- Components: velocity, paper-mc, mysql, pterodactyl-panel, phpmyadmin
- Tags: minecraft, gaming, proxy, velocity, pterodactyl
- Source: https://docker.recipes/homelab/minecraft-server-complete

## Overview

Velocity is a high-performance Minecraft proxy server developed as a modern alternative to BungeeCord, designed to handle multiple Minecraft servers behind a single connection point. Unlike traditional proxies, Velocity focuses on security, performance, and modern Minecraft protocol support, offering features like modern forwarding, better plugin APIs, and improved network handling. This stack combines Velocity with Paper MC servers, MySQL database, and optional Pterodactyl panel management to create a scalable Minecraft network infrastructure. The architecture allows players to connect through a single IP address while being dynamically routed between different game servers like lobby, survival, creative, or minigame servers. MySQL serves as the central database for cross-server player data, statistics, and plugin information, while Paper MC provides optimized server performance with extensive plugin compatibility. This combination is ideal for Minecraft network operators who need to manage multiple game modes, handle large player counts, or provide a professional gaming experience with features like cross-server chat, shared economies, and centralized player management.

## Features

- Velocity's modern forwarding system with cryptographic player information verification
- Paper MC's advanced anti-cheat integration and performance optimizations
- Cross-server player data synchronization through MySQL database
- Dynamic server switching without disconnection using Velocity's seamless transfer
- Plugin data sharing between servers via centralized MySQL storage
- Paper MC's improved redstone mechanics and reduced lag from optimization patches
- Velocity's connection throttling and DDoS protection for network security
- Multi-server chat and messaging system coordination through proxy

## Use cases

- Multi-gamemode networks with separate survival, creative, and minigame servers
- Large Minecraft communities requiring load distribution across multiple servers
- Gaming networks with cross-server economies and player progression systems
- Educational Minecraft servers with separate worlds for different classes or subjects
- Tournament and event hosting with dedicated competition and lobby servers
- Modded Minecraft networks where different servers run different modpack configurations
- Professional Minecraft hosting services offering multiple server types to clients

## Prerequisites

- Minimum 8GB RAM (2GB for Velocity, 2GB lobby server, 4GB survival server)
- Port 25565 available for external player connections
- Understanding of Minecraft server administration and plugin management
- Knowledge of Velocity configuration files and forwarding secrets
- Familiarity with Paper MC server optimization and plugin installation
- MySQL database administration skills for cross-server data management

## docker-compose.yml

```yaml
services:
  velocity:
    image: itzg/bungeecord:latest
    environment:
      - TYPE=VELOCITY
      - VELOCITY_VERSION=LATEST
    volumes:
      - velocity-data:/server
    ports:
      - "25565:25577"
    networks:
      - minecraft-network
    restart: unless-stopped

  lobby:
    image: itzg/minecraft-server:latest
    environment:
      - EULA=TRUE
      - TYPE=PAPER
      - VERSION=${MC_VERSION:-1.20.4}
      - MEMORY=2G
      - SERVER_NAME=Lobby
      - ONLINE_MODE=FALSE
    volumes:
      - lobby-data:/data
    networks:
      - minecraft-network
    restart: unless-stopped

  survival:
    image: itzg/minecraft-server:latest
    environment:
      - EULA=TRUE
      - TYPE=PAPER
      - VERSION=${MC_VERSION:-1.20.4}
      - MEMORY=4G
      - SERVER_NAME=Survival
      - DIFFICULTY=normal
      - ONLINE_MODE=FALSE
    volumes:
      - survival-data:/data
    networks:
      - minecraft-network
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=minecraft
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - minecraft-network
    restart: unless-stopped

volumes:
  velocity-data:
  lobby-data:
  survival-data:
  mysql-data:

networks:
  minecraft-network:
    driver: bridge
```

## .env

```bash
# Minecraft Network
MC_VERSION=1.20.4
MYSQL_ROOT_PASSWORD=secure_mysql_password

# Server memory allocation configured in compose
```

## Usage notes

- Proxy at port 25565
- Configure velocity forwarding secrets
- Each server in separate container
- Scale by adding more servers
- MySQL for plugin data sharing

## Troubleshooting

- Players can't join servers behind proxy: Verify ONLINE_MODE=FALSE on backend servers and configure Velocity forwarding secrets
- Cross-server data not syncing: Check MySQL connection strings in plugin configurations and ensure database permissions are correct
- High memory usage on Paper servers: Adjust view-distance, simulation-distance, and enable Paper's optimization settings in paper-global.yml
- Velocity proxy disconnecting players: Increase read-timeout and connection-timeout values in velocity.toml configuration
- Plugins not recognizing player data across servers: Ensure plugins support Velocity's modern forwarding and are configured for cross-server operation
- Server switching causes inventory loss: Configure inventory synchronization plugins with MySQL backend and proper cross-server data handling

