Configure HAProxy as a Reverse Proxy for HighByte Intelligence Hub
Set Up HAProxy to Distribute Traffic to Intelligence Hub
Introduction
HAProxy is a tool that can load-balance and intelligently reverse-proxy IP Layer network traffic. HighByte Intelligence Hub can often take advantage of state and order of incoming messages, so load-balancing is not always beneficial, but the smart reverse-proxy capabilities of HAProxy can be very useful when setting up Redundancy or High Availability for Intelligence Hub. This article will demonstrate the setup of HAProxy to route Intelligence Hub traffic to a primary hub, and conditionally, a backup hub.
Installing HAProxy
HAProxy may be acquired and installed from the associated downloads page. It is also available as a container image on Docker Hub, and can be accessed by most major Linux package managers. Where network applications like HAProxy are most commonly run in Linux server environments, installing on Linux is generally simpler. However it is possible to download HAProxy files and install on Windows using Python.
This example will follow installing HAProxy on Ubuntu. In many cases, the simplest installation pattern may be to use an Ubuntu container image and then to install HAProxy on the image.
On Ubuntu, HAProxy is installed by running the command apt install haproxy
Configuring HAProxy
Notice: The services available on port 45345 is being transitioned to port 8885. Please update your configurations to use port 8885, as port 45345 will be discontinued with v4.4+.
Once installed or available, HA Proxy must be configured to route relevant traffic to the Intelligence Hub. In the case of configuring HAProxy to manage traffic between the primary and backup instances for High Availability, it is important to consider that the host - either machine, virtual machine, or container - has ports mapped and available through a firewall to accept these connections.
Making Configurations
When installed on Ubuntu, HAProxy's configuration file lives at /etc/haproxy/haproxy.cfg.
A basic configuration file will be installed in place, and this configuration file may be adjusted to suit your installation. A starter haproxy.cfg file can be downloaded here and observed below.
# /etc/haproxy/haproxy.cfg
global
log /dev/log local0
log /dev/log local1 notice
chroot /var/lib/haproxy
stats socket /run/haproxy/admin.sock mode 660 level admin
stats timeout 30s
user haproxy
group haproxy
daemon
# Default SSL material locations
ca-base /etc/ssl/certs
crt-base /etc/ssl/private
# See: https://ssl-config.mozilla.org/#server=haproxy&server-version=2.0.3&config=intermediate
ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets
defaults
log global
mode http
option httplog
option dontlognull
timeout connect 5000
timeout client 50000
timeout server 50000
errorfile 400 /etc/haproxy/errors/400.http
errorfile 403 /etc/haproxy/errors/403.http
errorfile 408 /etc/haproxy/errors/408.http
errorfile 500 /etc/haproxy/errors/500.http
errorfile 502 /etc/haproxy/errors/502.http
errorfile 503 /etc/haproxy/errors/503.http
errorfile 504 /etc/haproxy/errors/504.http
listen highbyte_gui
bind :45245
mode http
option httpchk GET /v1/info
server primary mainHub:45245 check
server backup backupHub:45245 check backup
listen highbyte_REST
bind :8885
mode http
option httpchk GET /data/doc/index.html
server primary mainHub:8885 check
server backup backupHub:8885 check backup
listen highbyte_MQTT
bind :1885
mode tcp
option tcplog
server primary mainHub:1885 check
server backup backupHub:1885 check backup
listen highbyte_MCP
bind :45345
mode http
option httpchk GET /mcp
server primary mainHub:45345 check
server backup backupHub:45345 check backup
listen highbyte_webhook
bind :9001
mode http
# Send an empty POST request to "/"
option httpchk
http-check send meth POST uri / ver HTTP/1.1 hdr Host localhost
http-check expect status 200
server primary mainHub:9001 check
server backup backupHub:9001 check backup
The "global" and "defaults" blocks are unchanged from the distribution. A quick overview of these blocks and their functions can be gained from HAProxy's introductory video on the configuration file.
Configuring HAProxy to work with HighByte Intelligence Hub involves adding the subsequent "listen" blocks. One block is added for each of the ports forwarded to the Intelligence Hub. This may be JUST the highbyte_gui port 45245, or may also include ports for the REST data server, MQTT, MCP, and Webhook. If your installation is not using these services, the listen blocks are not necessary.
In the provided configuration above, each of these blocks includes the port HAProxy will listen on (bind), the mode of that port, instructions to check the health of the destination servers, and then the servers to route traffic for that port as either a primary or backup. These servers ("mainHub" and "backupHub" in the configuration above) can be defined either with IP addresses or with domain names. Even though these services are all bundled under a single runtime of Intelligence Hub, HAProxy doesn't necessarily expect each primary/backup to be the same server - as they could be routed to services on different servers. As a result, HAProxy evaluates the health of each port/service individually, and we will need to specify a mechanism to check health on each port and ensure that failover happens properly to the backup hub.
Replace "mainHub" and "backupHub" in the above configuration with the name or IP address of your HighByte Intelligence Hub servers. Ensure ports on 'bind' lines align with accessing HAproxy, and ports in 'server' lines align with accessing Intelligence Hub.
Listen highbyte_gui
The highbyte_gui port is 45245 by default. This binds port 45245 with a mode of http. The line option httpchk GET /v1/info says to check the endpoint /v1/info on port 45245 of each server to see if the server returns a 200 code. This is the same endpoint that Redundancy mode uses to check heartbeats. HAProxy will periodically check this endpoint automatically to evaluate health.
Marking one server as "backup" ensures that the server will ONLY get traffic after the primary is unreachable.
Listen highbyte_REST
The highbyte_REST port - 8885 by default - will function similarly to the highbyte_gui port. /data/doc/index.html is a webpage hosted on Intelligence Hub that provides interactive documentation for the REST server. It will serve as a reliable health check.
Listen highbyte_MQTT
The highbyte_MQTT port - 1885 by default - is a bit different from the http ports. MQTT does not use MQTT, but rather raw TCP binary. HAProxy can still manage this with the "tcp" mode. HAProxy will also be able to test and evaluate this port without a provided endpoint, which is convenient. No health check needs to be specified. However, the default block defines that we will be logging http with option httplog. To override this for tcp, we add the line option tcplog.
Listen highbyte_MCP
The highbyte_MCP port - 45345 by default - is another http port that doesn't require much special treatment. The HighByte Intelligence Hub MCP server will respond with a 200 code when available at the endpoint /mcp.
Listen highbyte_webhook
The first highbyte_webhook port is 9001 by default. Additional webhooks can be generated on additional ports, and one entry will be necessary per webhook. To minimize the updating and synchronizing needed in HAProxy, it may be advantageous to ingest under a single webhook and branch a pipeline based on content.
The webhook uses an http mode, but uses a different method of health check. Because the webhook does not support the GET http method, a different http check function is used to test with an empty POST request. If the webhook is set up to event into a pipeline, these checks WILL be counted as triggers, but HAProxy will not add a POST body, and Intelligence Hub will not inject an event from the trigger if no body is present.
Testing Configuration
After having made changes, it would be beneficial to validate the configuration before restarting the HAProxy service. This can be accomplished with the command haproxy -c -f /etc/haproxy/haproxy.cfg assuming the default configuration file location of /etc/haproxy/haproxy.cfg.
Applying Configuration and Restarting HAProxy
To apply this configuration and to restart the HAProxy service, run the command:systemctl haproxy restart
Or, if running in a container:service haproxy restart
This configuration was validated using HAProxy 2.8.16 (LTS) installed from the default Ubuntu 24.04 repository (no custom build).
Additional Resources