HAProxy Load Balancer

Key Features

• Layer 4 TCP and Layer 7 HTTP load balancing with multiple algorithms including round-robin, least connections, and source IP hashing
• Advanced health checking with customizable HTTP, TCP, and MySQL health check methods
• SSL/TLS termination with SNI support and certificate management for HTTPS traffic
• Built-in statistics dashboard accessible on port 8404 for real-time monitoring of backend servers
• Session persistence using stick tables and cookie insertion for stateful applications
• Advanced ACLs for traffic routing based on headers, URLs, source IPs, and custom conditions
• Zero-downtime configuration reloads using HUP signal without dropping existing connections
• Rate limiting and connection queuing to protect backend servers from traffic spikes

Common Use Cases

• 1High-traffic web applications requiring distribution across multiple backend web servers
• 2Database connection pooling and load balancing for PostgreSQL or MySQL clusters
• 3API gateway functionality for microservices with path-based routing and health monitoring
• 4SSL termination proxy to offload encryption processing from backend application servers
• 5Blue-green deployments with traffic switching between different application versions
• 6Geographic or datacenter-based traffic routing using HAProxy's advanced ACL capabilities
• 7Legacy application modernization by adding load balancing without code changes

Prerequisites

• Minimum 256MB RAM recommended for production workloads (64MB minimum for testing)
• Valid HAProxy configuration file at ./haproxy/haproxy.cfg with frontend and backend sections defined
• Backend servers accessible from the HAProxy container network with health check endpoints
• Ports 80, 443, and 8404 available on the host system for HTTP, HTTPS, and statistics dashboard
• Understanding of HAProxy configuration syntax including frontend, backend, and listen sections
• SSL certificates properly mounted if HTTPS termination is required

docker-compose.yml

1services: 
2  haproxy: 
3    image: haproxy:2.8-alpine
4    container_name: haproxy
5    restart: unless-stopped
6    volumes: 
7      - ./haproxy/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
8    ports: 
9      - "80:80"
10      - "443:443"
11      - "8404:8404"
12    networks: 
13      - haproxy-network
14
15networks: 
16  haproxy-network: 
17    driver: bridge

.env Template

1# HAProxy stats
2HAPROXY_STATS_USER=admin
3HAPROXY_STATS_PASSWORD=changeme

Usage Notes

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  haproxy:
5    image: haproxy:2.8-alpine
6    container_name: haproxy
7    restart: unless-stopped
8    volumes:
9      - ./haproxy/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
10    ports:
11      - "80:80"
12      - "443:443"
13      - "8404:8404"
14    networks:
15      - haproxy-network
16
17networks:
18  haproxy-network:
19    driver: bridge
20EOF
21
22# 2. Create the .env file
23cat > .env << 'EOF'
24# HAProxy stats
25HAPROXY_STATS_USER=admin
26HAPROXY_STATS_PASSWORD=changeme
27EOF
28
29# 3. Start the services
30docker compose up -d
31
32# 4. View logs
33docker compose logs -f

One-Liner

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

1curl -fsSL https://docker.recipes/api/recipes/haproxy/run | bash

Troubleshooting