Minecraft Server + Velocity Proxy

advanced

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

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.

Key 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

Common Use Cases

1Multi-gamemode networks with separate survival, creative, and minigame servers
2Large Minecraft communities requiring load distribution across multiple servers
3Gaming networks with cross-server economies and player progression systems
4Educational Minecraft servers with separate worlds for different classes or subjects
5Tournament and event hosting with dedicated competition and lobby servers
6Modded Minecraft networks where different servers run different modpack configurations
7Professional 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  velocity: 
3    image: itzg/bungeecord:latest
4    environment: 
5      - TYPE=VELOCITY
6      - VELOCITY_VERSION=LATEST
7    volumes: 
8      - velocity-data:/server
9    ports: 
10      - "25565:25577"
11    networks: 
12      - minecraft-network
13    restart: unless-stopped
14
15  lobby: 
16    image: itzg/minecraft-server:latest
17    environment: 
18      - EULA=TRUE
19      - TYPE=PAPER
20      - VERSION=${MC_VERSION:-1.20.4}
21      - MEMORY=2G
22      - SERVER_NAME=Lobby
23      - ONLINE_MODE=FALSE
24    volumes: 
25      - lobby-data:/data
26    networks: 
27      - minecraft-network
28    restart: unless-stopped
29
30  survival: 
31    image: itzg/minecraft-server:latest
32    environment: 
33      - EULA=TRUE
34      - TYPE=PAPER
35      - VERSION=${MC_VERSION:-1.20.4}
36      - MEMORY=4G
37      - SERVER_NAME=Survival
38      - DIFFICULTY=normal
39      - ONLINE_MODE=FALSE
40    volumes: 
41      - survival-data:/data
42    networks: 
43      - minecraft-network
44    restart: unless-stopped
45
46  mysql: 
47    image: mysql:8.0
48    environment: 
49      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
50      - MYSQL_DATABASE=minecraft
51    volumes: 
52      - mysql-data:/var/lib/mysql
53    networks: 
54      - minecraft-network
55    restart: unless-stopped
56
57volumes: 
58  velocity-data: 
59  lobby-data: 
60  survival-data: 
61  mysql-data: 
62
63networks: 
64  minecraft-network: 
65    driver: bridge

.env Template

.env

1# Minecraft Network
2MC_VERSION=1.20.4
3MYSQL_ROOT_PASSWORD=secure_mysql_password
4
5# Server memory allocation configured in compose

Usage Notes

1Proxy at port 25565
2Configure velocity forwarding secrets
3Each server in separate container
4Scale by adding more servers
5MySQL for plugin data sharing

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

velocity

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

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

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  velocity:
5    image: itzg/bungeecord:latest
6    environment:
7      - TYPE=VELOCITY
8      - VELOCITY_VERSION=LATEST
9    volumes:
10      - velocity-data:/server
11    ports:
12      - "25565:25577"
13    networks:
14      - minecraft-network
15    restart: unless-stopped
16
17  lobby:
18    image: itzg/minecraft-server:latest
19    environment:
20      - EULA=TRUE
21      - TYPE=PAPER
22      - VERSION=${MC_VERSION:-1.20.4}
23      - MEMORY=2G
24      - SERVER_NAME=Lobby
25      - ONLINE_MODE=FALSE
26    volumes:
27      - lobby-data:/data
28    networks:
29      - minecraft-network
30    restart: unless-stopped
31
32  survival:
33    image: itzg/minecraft-server:latest
34    environment:
35      - EULA=TRUE
36      - TYPE=PAPER
37      - VERSION=${MC_VERSION:-1.20.4}
38      - MEMORY=4G
39      - SERVER_NAME=Survival
40      - DIFFICULTY=normal
41      - ONLINE_MODE=FALSE
42    volumes:
43      - survival-data:/data
44    networks:
45      - minecraft-network
46    restart: unless-stopped
47
48  mysql:
49    image: mysql:8.0
50    environment:
51      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
52      - MYSQL_DATABASE=minecraft
53    volumes:
54      - mysql-data:/var/lib/mysql
55    networks:
56      - minecraft-network
57    restart: unless-stopped
58
59volumes:
60  velocity-data:
61  lobby-data:
62  survival-data:
63  mysql-data:
64
65networks:
66  minecraft-network:
67    driver: bridge
68EOF
69
70# 2. Create the .env file
71cat > .env << 'EOF'
72# Minecraft Network
73MC_VERSION=1.20.4
74MYSQL_ROOT_PASSWORD=secure_mysql_password
75
76# Server memory allocation configured in compose
77EOF
78
79# 3. Start the services
80docker compose up -d
81
82# 4. View logs
83docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/minecraft-server-complete/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

velocitypaper-mcmysqlpterodactyl-panelphpmyadmin

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download