Pterodactyl HAProxy Egg

This repository provides a production-ready HAProxy Docker image and Pterodactyl Egg for easy reverse-proxying, load balancing, and high-availability setups directly from your Pterodactyl panel.

This egg is heavily optimized for Minecraft Server routing (Java Edition).

Features

• Minecraft Optimized: Pre-configured with long TCP timeouts (12h) to prevent players from timing out during large resource pack downloads or server lag spikes.
• Proxy Protocol Support: Built-in toggle to enable send-proxy-v2, allowing backend servers (Velocity, BungeeCord, Paper) to see real player IPs.
• Alpine Based: Extremely lightweight Docker image based on haproxy:alpine.
• Non-Root Execution: Runs securely as the container user.
• Auto-Installation: Automatically generates a functional boilerplate haproxy.cfg when the server is installed.
• Multi-Architecture: Supports both amd64 and arm64 systems.

Minecraft Server Proxying

Warning

No UDP Proxying HAProxy is a TCP proxy. It cannot proxy UDP traffic. Therefore, this egg works perfectly for Minecraft Java Edition, but it cannot be used to proxy Bedrock/Geyser traffic.

When using this egg to proxy traffic to a Minecraft network (like Velocity or BungeeCord):

1. Backend Host / Port: Set these variables to the IP and Port of your Velocity/BungeeCord proxy.
2. Enable Proxy Protocol: Set this variable to 1. This will automatically append send-proxy-v2 to your HAProxy configuration during installation.
3. Backend Setup: Ensure your backend proxy (e.g., Velocity) is configured to accept HAProxy connections. In velocity.toml, set haproxy-protocol = true.

Installation

1. Download the egg-h-a-proxy.json file from this repository.
2. In your Pterodactyl Admin Panel, go to Nests -> Import Egg.
3. Select the egg-h-a-proxy.json file and assign it to a Nest of your choice.
4. When creating a new server, simply select the HAProxy egg.
5. During creation, configure the Backend Host, Backend Port, and Proxy Protocol settings.

Configuration

Upon installation, a default haproxy.cfg is generated in your server's root directory. It automatically reads your server's assigned port (${SERVER_PORT}) and routes traffic to the backend host and port you defined (${BACKEND_HOST}:${BACKEND_PORT}).

You can customize haproxy.cfg freely to utilize HAProxy's advanced features, such as multiple frontends/backends, SSL termination, or complex load-balancing algorithms. Note: The proxy protocol variable only affects the configuration generated during the initial install. If you need to enable it later, you must manually add send-proxy-v2 to your haproxy.cfg.

Building Locally

If you wish to build the Docker image yourself instead of using the provided GitHub Container Registry image:

docker build -t your-registry/haproxy-pterodactyl:latest .