brycelarge/haproxy repository overview

⁠HAProxy Docker Image

A high-performance HAProxy Docker image with QUIC support, automated SSL/TLS certificate management, and flexible configuration options.

⁠Table of Contents

1. Features⁠
2. Quick Start⁠
3. Configuration⁠
   • YAML Structure⁠
   • Full YAML Example⁠
4. Environment Variables⁠
5. Volumes⁠
6. Ports⁠
7. Security Configuration⁠
   • Required Secrets⁠
   • Optional Settings⁠
8. ACME Configuration⁠
   • DNS Challenge Setup⁠
   • HTTP Challenge Setup⁠
9. Advanced Usage⁠
   • Custom Certificates⁠
   • Healthcheck Configuration⁠
10. Building the Image⁠
11. Troubleshooting⁠

⁠Features

• HAProxy 2.4+ with QUIC protocol support
• Automatic SSL/TLS certificate management via acme.sh
• Support for both Cloudflare DNS and HTTP ACME challenges
• YAML-based configuration system
• Dynamic backend configuration
• Comprehensive healthcheck system
• Alpine Linux base for minimal footprint
• s6-overlay for reliable process management
• Real-time SSL certificate updates without restart
• Support for multiple domains and certificates
• Automatic certificate renewal

⁠Quick Start

⁠Using Docker Run

docker run -d \
  --name haproxy \
  -p 80:80 \
  -p 443:443 \
  -v /path/to/config:/config \
  -e CF_Token=your-cloudflare-api-token \
  -e CF_Account_ID=your-cloudflare-account-id \
  -e CF_Zone_ID=your-cloudflare-zone-id \
  -e [email protected] \
  yourusername/haproxy:latest

⁠Using Docker Compose

version: '3.8'
services:
  haproxy:
    image: yourusername/haproxy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./config:/config
    environment:
      - CF_Token=${CF_Token}
      - CF_Account_ID=${CF_Account_ID}
      - CF_Zone_ID=${CF_Zone_ID}
      - ACME_EMAIL=${ACME_EMAIL}
      - ACME_CHALLENGE_TYPE=dns_cf
      - CONFIG_AUTO_GENERATE_DEBUG=false
    restart: unless-stopped

⁠Environment Variables

⁠Cloudflare API Authentication Methods

You can use either the newer API Token method or the legacy API Key method:

1. API Token Method (Recommended):

   • Requires: CF_Token, CF_Account_ID, CF_Zone_ID
   • More secure with granular permissions
   • Can be easily revoked if compromised

2. Legacy API Key Method:

   • Requires: CF_Email, CF_Key
   • Full account access
   • Less secure but simpler setup

⁠Volumes

⁠Ports

⁠Security Configuration

⁠Optional Settings

security_options:
  - no-new-privileges:true
  - seccomp=unconfined

⁠ACME Configuration

⁠DNS Challenge Setup

1. Create Cloudflare API Token:

   • Go to Cloudflare Dashboard → Profile → API Tokens
   • Create token with Zone:DNS:Edit permissions
   • Note down the token, Account ID, and Zone ID

2. Configure Environment:

   • Take the information from steps taken above and add it to your config/acme/acme.sh.env file.

⁠config/acme/acme.sh.env file will be generated on the first boot when acme is installed, then shutdown the container and add the above to the file in the format shown below.

export CF_Token=your_token
export CF_Account_ID=your_cf_account_id
export export CF_Zone_ID=your_cf_zone_id

# Alternative Cloudflare settings
export CF_Key=your_cf_key
export CF_Email=your_cf_email

⁠HTTP Challenge Setup

1. Configure Environment:

   -e ACME_CHALLENGE_TYPE=http \
   -e [email protected]
   

   Copy

2. Ensure Port 80 is Accessible:

   -p 80:80
   

   Copy

⁠Advanced Usage

⁠Custom Certificates

Place custom certificates in /config/acme/certs/:

/config/acme/certs/
├── example.com.pem
├── example.com.key
└── example.com.chain

⁠Healthcheck Configuration

Default healthcheck configuration:

HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
    CMD /usr/local/bin/healthcheck.sh

⁠Troubleshooting

⁠Common Issues

1. Certificate Issues:

   # Check ACME logs
   docker exec haproxy cat /var/log/acme-renewals.log
   

   Copy

2. HAProxy Startup Failures:

   # Check HAProxy logs
   docker exec haproxy cat /var/log/haproxy/haproxy.log
   

   Copy

3. Configuration Errors:

   # Validate configuration
   docker exec haproxy haproxy -c -f /config/haproxy.cfg
   

   Copy

⁠Debug Mode

Enable debug logging:

-e DEBUG=true