ravenscott-blog/markdown/Minecraft Cluster Deployment with Velocity Proxy and Holesail Integration.md

<!-- lead -->
Setting up a scalable, secure, and modular Minecraft server system is no easy feat.

In this post we will look into how to deploy a Minecraft cluster using Docker, orchestrate the servers with PM2, and manage secure peer-to-peer connections with Holesail. 

Whether you're a hobbyist or managing servers for a community, this system provides everything you need to run a robust setup.



# Cluster Source Code:  

## https://git.ssh.surf/snxraven/mc-cluster

## Why Build a Minecraft Cluster:

Running a single Minecraft server can be sufficient for small groups, but as player numbers grow, or if you want to offer different experiences (e.g., creative, survival, or modded servers), a clustered setup becomes invaluable. The key benefits include:

1. **Scalability**: Add or remove servers based on demand.
2. **Flexibility**: Host different game modes or mods on separate servers.
3. **Performance**: Distribute player loads across multiple servers.
4. **Security**: Use Holesail for end-to-end encrypted peer-to-peer communication.



## Overview of the System

This system consists of three major components:

1. **Minecraft Server Cluster**: A group of Minecraft servers running FabricMC for mod support, deployed with Docker Compose and orchestrated using PM2.
2. **Velocity Proxy**: A lightweight proxy that routes player connections to the appropriate Minecraft server.
3. **Holesail Networking**: Secure peer-to-peer networking for managing connections between servers and the proxy.

Here’s a simplified architecture:

```
Players → Velocity Proxy (JUMP Node) → Minecraft Cluster (MC Host Node)
```



## Component Breakdown

### 1. **Minecraft Cluster**

The cluster is built using Docker Compose, allowing multiple Minecraft servers to run in isolated containers. Each server has:

- **FabricMC**: For modding support.
- **PM2**: Process manager to ensure stability and logs.
- **Holesail Integration**: Secure connections using predefined connection strings.

**How It Works**:
- The `docker-compose.yml` defines the services (servers) in the cluster.
- Each server is configured with its own Holesail connection string and port.
- PM2 ensures the servers restart automatically if they crash.



### 2. **Velocity Proxy**

Velocity is a Minecraft proxy designed for performance and flexibility. It routes player traffic to the appropriate backend Minecraft servers.

**Features**:
- **Customizable MOTD**: Tailor the server’s welcome message.
- **Player Forwarding**: Seamlessly switch players between servers.
- **Holesail Integration**: Secure backend connections.

**How It Works**:
- The `velocity.toml` configuration file specifies backend servers and ports.
- Players connect to the Velocity proxy, which uses Holesail to route traffic to the appropriate server in the cluster.



### 3. **Holesail Networking**

Holesail provides secure peer-to-peer networking using connection strings. This ensures encrypted communication between the Velocity proxy and Minecraft servers.

**Key Points**:
- Each server is assigned a unique connection string and port.
- The `pm2-setup.sh` script initializes Holesail connections.
- Holesail manages end-to-end encryption, ensuring secure traffic.



## Step-by-Step Deployment Guide

### **Step 1: Set Up the Minecraft Host Node**

This node hosts the Minecraft server cluster.

1. **Clone the Repository**:
   ```bash
   git clone https://git.ssh.surf/snxraven/mc-cluster.git
   cd mc-cluster/mc-cluster-image
   ```

2. **Build the Minecraft Cluster Image**:
   ```bash
   docker build . -t mc:cluster
   ```

3. **Navigate Back to the Main Directory**:
   ```bash
   cd ..
   ```

4. **Start the Cluster**:
   ```bash
   docker-compose up -d
   ```

This command deploys a cluster of Minecraft servers, each with its own connection string and port defined in `pm2-setup.sh`.



### **Step 2: Set Up the JUMP Node**

The JUMP node hosts the Velocity proxy, managing player connections and routing traffic to the Minecraft cluster. The docker compose also starts up the holesail connections to bind the remote Minecraft servers to the local JUMP Server. All connections within velocity are configured within localhost. 

1. **Clone the Repository**:
   ```bash
   git clone https://git.ssh.surf/snxraven/mc-cluster.git
   cd mc-cluster/velocity-image
   ```

2. **Build the Velocity Proxy Image**:
   ```bash
   docker build . -t velocity:proxy
   ```

3. **Start the Proxy**:
   ```bash
   docker-compose up -d
   ```

## Customization and Advanced Configuration

### Minecraft Cluster Customization

- **Add/Remove Servers**:
  Edit the `docker-compose.yml` file and modify the `services` section.

  Example:
  ```yaml
  services:
    mc-server-1:
      image: mc:cluster
      environment:
        CONNECTION_STRING: "mc-server-1"
        PORT: "5000"
    mc-server-2:
      image: mc:cluster
      environment:
        CONNECTION_STRING: "mc-server-2"
        PORT: "5001"
  ```

### Velocity Proxy Customization

- **MOTD and Server List**:
  Modify `velocity.toml` to change the MOTD and backend server settings.

  Example:
  ```toml
  motd = "&aWelcome to our Minecraft Cluster!"
  [servers]
    lobby = "mc-server-1"
    survival = "mc-server-2"
  ```

- **Secure Player Forwarding**:
  Update the `forwarding.secret` file for secure player forwarding.



## Troubleshooting

### Common Issues

1. **Holesail Connection Error**:
   - Ensure the `CONNECTION_STRING` and `PORT` values are correctly set.

2. **Mod Manager Problems**:
   - Check the initialization logs:
     ```bash
     docker exec -it mc-server-1 cat /var/log/mod-manager.log
     ```

3. **Velocity Not Forwarding Players**:
   - Ensure the `velocity.toml` file has the correct backend server configurations.



## Future Enhancements

- **Auto-Scaling**:
  Add or remove Minecraft servers dynamically based on player load.
- **Integrated Monitoring**:
  Use tools like Netdata to monitor server performance and health.
- **Web Dashboard**:
  Develop a web interface for managing the cluster, viewing logs, and deploying updates.