Migrating from BungeeCord to Velocity: A Modern Proxy Upgrade Guide

The landscape of Minecraft server proxies has seen significant evolution. For years, BungeeCord and its fork, Waterfall, served as the backbone for many server networks, enabling seamless player movement between multiple Minecraft servers. However, with Waterfall reaching its end-of-life in March 2024, and BungeeCord's development slowing, the time has come for server owners to consider a more modern, actively maintained alternative: Velocity.

This guide will walk you through the essential steps to migrate your existing BungeeCord or Waterfall setup to Velocity, ensuring your network benefits from enhanced performance, security, and long-term stability.

The Case for Velocity

Velocity, developed by the PaperMC team, represents the next generation of Minecraft proxy software. It offers a compelling set of advantages that make it the superior choice for modern server networks:

- Performance Advantages: Velocity is built from the ground up with asynchronous networking, meaning it can handle many connections simultaneously without blocking. This translates to lower latency, higher throughput, and a more responsive experience for players, even under heavy load.

- Enhanced Security: Velocity includes robust features for connection throttling, IP forwarding, and built-in DDoS mitigation, helping to protect your backend servers from malicious attacks and ensuring real player IP addresses are passed through correctly.

- Modern Development: Being actively maintained by the PaperMC team, Velocity receives regular updates, bug fixes, and new features. This ensures compatibility with the latest Minecraft versions and provides a stable platform for future growth.

- BungeeCord/Waterfall End-of-Life: The cessation of official support and updates for Waterfall means that server owners continuing to use it risk security vulnerabilities, compatibility issues with newer Minecraft versions, and a lack of bug fixes. Migrating to Velocity is a proactive step to future-proof your network.

Key Differences Between BungeeCord and Velocity

While both serve the same fundamental purpose, there are key differences that impact migration:

- Configuration File Structure: Velocity uses a `velocity.toml` file, which is more organised and often easier to manage than BungeeCord's `config.yml`. The parameters are logically grouped and well-documented.

- Plugin Compatibility: Most BungeeCord plugins have direct Velocity equivalents, or in many cases, are designed to be cross-compatible. However, always verify compatibility for each plugin you use.

- Security Settings: Velocity handles IP forwarding and player information more robustly, requiring specific configurations on both the proxy and backend servers to ensure player UUIDs and IP addresses are correctly transmitted and secured.

Pre-Migration Checklist

Before you begin the migration, thorough preparation is crucial to minimise downtime and potential issues:

- Backup Everything: Create full backups of your BungeeCord/Waterfall configuration files, plugin data, and all backend Minecraft servers. This is your safety net.

- Update Backend Servers: Ensure all your backend Minecraft servers (Paper, Purpur, Fabric, NeoForge) are running the latest stable versions for your chosen Minecraft release. This ensures optimal compatibility with Velocity.

- Identify BungeeCord Plugins: List all plugins currently running on your BungeeCord/Waterfall proxy. Research and locate their Velocity-compatible counterparts or verify cross-compatibility. Pay special attention to permissions, chat, and server selector plugins.

- Choose Your Java Version: Velocity typically requires a modern Java version (e.g., Java 17 or newer) for optimal performance and security. Ensure your server host supports this, or upgrade your local Java environment if self-hosting.

The Migration Process: Step-by-Step

This process assumes you have a basic understanding of server administration and file management.

1. Server Setup

- Download Velocity: Obtain the latest stable Velocity JAR file from its official download page.

- Initial Configuration: Create a new directory for your Velocity proxy. Place the downloaded JAR inside. Run Velocity once to generate the default `velocity.toml` configuration file.

- Edit `velocity.toml`: Open `velocity.toml` and configure the following essential settings:

- `bind`: Set this to your public IP address and the port you want players to connect to (e.g., `0.0.0.0:25565`).
- `servers`: Define your backend Minecraft servers. Each entry needs a unique name, an address (IP:port), and optionally a restricted status.
- `forced-hosts`: Configure which backend server players are sent to initially when connecting via a specific domain name.
- `player-info-forwarding`: Set `mode` to `MODERN` and `secret` to a strong, randomly generated string. This is critical for security and IP forwarding.

2. Backend Server Configuration

For each backend Minecraft server, you must adjust its `server.properties` and `paper.yml` (or `purpur.yml`):

- `server.properties`:

- Set `online-mode=false`. Velocity handles authentication, so backend servers should not attempt to do so.
- Set `server-port` to an internal port (e.g., 25566, 25567, etc.) that is not publicly accessible and is consistent with your `velocity.toml`.

- `paper.yml` (or `purpur.yml`):

- Set `settings.bungeecord.enabled=true`. Despite the name, this setting enables modern proxy forwarding for Velocity. Ensure the `player-info-forwarding.secret` in Velocity matches the corresponding `settings.bungeecord.secret` in your backend configuration.

3. Plugin Migration

- Remove Old Plugins: Delete all BungeeCord/Waterfall-specific plugins from your old proxy's plugin folder.

- Install Velocity Plugins: Download and install the Velocity-compatible versions of your essential plugins (e.g., permissions, chat management, server selectors) into Velocity's `plugins` folder.

- Data Transfer: If plugins store data outside their JAR files (e.g., SQL databases, YAML files), ensure this data is compatible with the Velocity version of the plugin. You may need to copy or migrate specific data files.

4. Testing

- Local Testing: Start Velocity and your backend servers. Try connecting directly to Velocity's IP:port to ensure basic functionality.

- Staging Environment: If possible, deploy your Velocity setup to a separate staging environment for more extensive testing with a small group of trusted players. This allows you to catch issues without impacting your main player base.

- Player Testing: Once confident, announce a testing phase for your community, gathering feedback on any anomalies.

5. DNS/Firewall Updates

- DNS Records: Update your domain's A/SRV records to point to the IP address of your new Velocity proxy server.

- Firewall Configuration: Ensure your firewall allows incoming connections to Velocity's public port (e.g., 25565) and that your backend servers' internal ports are not publicly exposed, only accessible by the Velocity proxy.

Post-Migration Optimisation and Monitoring

After a successful migration, continue to monitor your network closely:

- Review Velocity Configuration: Periodically revisit Velocity's `velocity.toml` to fine-tune settings. Velocity offers extensive options for connection throttling, compression, and more.

- Monitor Logs: Keep an eye on Velocity's console and log files for any errors, warnings, or performance issues. These can indicate misconfigurations or plugin conflicts.

- Utilise Metrics: Velocity can integrate with monitoring tools to provide real-time data on player counts, CPU usage, and network traffic, helping you identify and address bottlenecks.

Common Pitfalls and Troubleshooting

- Incorrect IP Forwarding: If backend servers are not showing real player IPs, double-check that `player-info-forwarding.mode` is set to `MODERN` in `velocity.toml` and `settings.bungeecord.enabled=true` with a matching `secret` on your backend servers.

- Firewall Issues: Ensure your firewall is correctly configured to allow Velocity's incoming connections and block public access to backend server ports.

- Plugin Incompatibility: A common cause of issues. Always verify that your plugins are compatible with Velocity and the specific Minecraft version your backend servers are running.

- Java Version Mismatches: Ensure Velocity and your backend servers are running on compatible and recommended Java versions.

Conclusion

Migrating from BungeeCord or Waterfall to Velocity is a crucial step for any server owner looking to maintain a high-performance, secure, and stable Minecraft network. While it requires careful planning and execution, the benefits of Velocity's modern architecture and active development far outweigh the effort. For those seeking reliable, high-performance infrastructure to run their Velocity-powered networks, PixelRaid Hosting offers managed solutions designed to meet the demands of even the largest communities.

Sources and further reading

- Velocity Documentation: https://docs.papermc.io/velocity/getting-started
- PaperMC Documentation: https://docs.papermc.io/paper/getting-started