Installation

Install HAProxy Enterprise on Docker

On this page

Complete the pre-install checklist first

Before installing HAProxy Enterprise, complete the pre-install checklist. This will help you minimize downtime and ensure that the installation process runs smoothly.

Using HAProxy Fusion?

If you’re using HAProxy Fusion, then see the HAProxy Fusion - Nodes topic instead.

The HAProxy Enterprise Docker image lets you run the load balancer as a container.

Install the HAProxy Enterprise Docker container Jump to heading

The haproxy-enterprise Docker image hosts HAProxy Enterprise and HAProxy Data Plane API. Follow these steps to install it.

  1. If you don’t have a HAProxy Enterprise license key, get one by registering and requesting a free trial of HAProxy Enterprise at https://www.haproxy.com/downloads/hapee-trial/.

  2. Log into the HAProxy Docker registry using your HAProxy Enterprise license key as both the username and password. You can also view this registry in your browser.

    nix
    sudo docker login https://registry.haproxy.com
    nix
    sudo docker login https://registry.haproxy.com

    Our registry has moved!

    In previous versions of this guide, we used the URL https://hapee-registry.haproxy.com.

  3. Pull the HAProxy Enterprise image from the haproxytech repository.

    Install the Docker container
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1
    nix
    sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1

  4. Create an HAProxy Enterprise configuration file, hapee-lb.cfg, that defines your load balancer settings.

    You can run a container temporarily, just to get the HAProxy Enterprise configuration files from it to use as a starting point. The following command saves a copy of the HAProxy Enterprise configuration files to a local folder. It also creates a folder named hapee-extras, which contains the HAProxy Data Plane API configuration files. We sleep for 10 seconds to give the container enough time to initialize before copying the files.

    Create a starter configuration file
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-3.4 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-3.4 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-3.3 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-3.3 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-3.2 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-3.2 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-3.0 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-3.0 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-2.8 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-2.8 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-2.6 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config
    nix
    sudo docker run --rm -d --name hapee-config registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1
    sleep 10
    sudo docker cp hapee-config:/etc/hapee-2.6 ./
    sudo docker cp hapee-config:/etc/hapee-extras/ ./
    sudo docker stop hapee-config

  5. Start the Docker container, referencing the directories containing your configuration files as volume mounts by using the -v flag.

    Start the Docker container
    nix
    sudo docker run \
      --name hapee-3.4 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-3.4:/etc/hapee-3.4  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    nix
    sudo docker run \
      --name hapee-3.4 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-3.4:/etc/hapee-3.4  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    nix
    sudo docker run \
      --name hapee-3.3 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-3.3:/etc/hapee-3.3  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    nix
    sudo docker run \
      --name hapee-3.3 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-3.3:/etc/hapee-3.3  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    nix
    sudo docker run \
      --name hapee-3.2 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-3.2:/etc/hapee-3.2  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    nix
    sudo docker run \
      --name hapee-3.2 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-3.2:/etc/hapee-3.2  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    nix
    sudo docker run \
      --name hapee-3.0 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-3.0:/etc/hapee-3.0  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    nix
    sudo docker run \
      --name hapee-3.0 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-3.0:/etc/hapee-3.0  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    nix
    sudo docker run \
      --name hapee-2.8 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-2.8:/etc/hapee-2.8  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    nix
    sudo docker run \
      --name hapee-2.8 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-2.8:/etc/hapee-2.8  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    nix
    sudo docker run \
      --name hapee-2.6 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-2.6:/etc/hapee-2.6  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1
    nix
    sudo docker run \
      --name hapee-2.6 \
      -d \
      -p 80:80 \
      -p 443:443 \
      -p 5555:5555 \
      -p 5108-5118:5108-5118 \
      -v $(pwd)/hapee-2.6:/etc/hapee-2.6  \
      -v $(pwd)/hapee-extras:/etc/hapee-extras \
      --restart=unless-stopped \
      registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1

For next steps on accessing HAProxy Data Plane API, see its installation guide.

Other Docker images Jump to heading

The HAProxy Docker registry at https://registry.haproxy.com has these HAProxy Enterprise images:

Image Description
haproxytech/haproxy-enterprise

This image runs HAProxy Enterprise and HAProxy Data Plane API.

There is a related Docker image that packages OpenSSL 1.1.1 (haproxytech/haproxy-enterprise-ssl111). Another related image uses RHEL Universal Base Image (UBI) (haproxytech/haproxy-enterprise-ubi).

This image contains these modules:

  • 51Degrees module
  • 51Degrees Update module
  • AD FS Web Proxy module
  • Bot Management module
  • Captcha module
  • DeviceAtlas module
  • DeviceAtlas Update module
  • Digital Element module
  • Fingerprint module
  • JavaScript Challenge module
  • MaxMind module
  • OpenID Connect module
  • Response Body Injection module
  • Route Health Injection module
  • SAML module
  • Send Metrics module
  • SSL-CRL module
  • TLS Fingerprint module
  • Traffic Mirroring module
  • UDP module
  • Update module
  • WAF module
haproxytech/haproxy-enterprise-rhi

Deprecated. This image runs HAProxy Enterprise and HAProxy Data Plane API. It contains the same modules as the haproxytech/haproxy-enterprise image, plus the legacy Route Health Injection module.

There is a related Docker image that packages OpenSSL 1.1.1 (haproxytech/haproxy-enterprise-rhi-ssl111).
haproxytech/haproxy-enterprise-vrrp

This image runs HAProxy Enterprise and HAProxy Data Plane API. It contains the same modules as the haproxytech/haproxy-enterprise image, plus the VRRP module.

There is a related Docker image that packages OpenSSL 1.1.1 (haproxytech/haproxy-enterprise-vrrp-ssl111).
haproxytech/hapee-business

Deprecated. This image runs a base version of HAProxy Enterprise without any modules.

There is a related Docker image that packages OpenSSL 1.1.1 (haproxytech/hapee-business-ssl111). Another related image uses RHEL Universal Base Image (UBI) (haproxytech/hapee-business-ubi).
haproxytech/hapee-business-plus

Deprecated. This image runs HAProxy Enterprise with all modules.

There is a related Docker image that packages OpenSSL 1.1.1 (haproxytech/hapee-business-plus-ssl111). Another related image uses RHEL Universal Base Image (UBI) (haproxytech/hapee-business-plus-ubi).
haproxytech/hapee-gpe

Deprecated. This image runs the older 0.x version of the HAProxy Enterprise Global Profiling Engine.

There is a related Docker image that packages OpenSSL 1.1.1 (haproxytech/hapee-gpe-ssl111). Another related image uses RHEL Universal Base Image (UBI) (haproxytech/hapee-gpe-ubi).
haproxytech/hapee-gpe10

This image runs the HAProxy Enterprise Global Profiling Engine version 1.0.

There is a related Docker image that uses RHEL Universal Base Image (UBI) (haproxytech/hapee-gpe10-ubi).
haproxytech/hapee-stkagg

Deprecated. This image runs the legacy Stick Table Aggregator. You should use the Global Profiling Engine image instead.

There is a related Docker image that packages OpenSSL 1.1.1 (haproxytech/hapee-stkagg-ssl111). Another related image uses RHEL Universal Base Image (UBI) (haproxytech/hapee-stkagg-ubi).

Environment variables Jump to heading

You can set the following environment variables when running the haproxy-enterprise Docker image.

Variable Description
BOOTSTRAP_KEY The HAProxy Fusion bootstrap key; when set, HAProxy Data Plane API starts in cluster mode instead of single mode.
ADVERTISED_IP The address HAProxy Data Plane API advertises to HAProxy Fusion.
ADVERTISED_PORT The TCP port HAProxy Data Plane API advertises to HAProxy Fusion. It defaults to 5555.

Example:

nix
sudo docker run --env ADVERTISED_PORT=5252 ...
nix
sudo docker run --env ADVERTISED_PORT=5252 ...

Install with a custom Dockerfile Jump to heading

To install a modified HAProxy Enterprise environment, create a custom Dockerfile. For information on creating Dockerfiles, see the Docker guide Writing a Dockerfile.

  1. In your Dockerfile, specify the desired HAProxy Enterprise base image as in the following example:

    Install with a custom Dockerfile
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1

  2. Add any further Dockerfile commands as needed. The following example starts from the HAProxy Enterprise image, then includes a custom set of tools. The custom tool installation script, install_mytools-4.3.sh, must reside in the current directory and have executable permissions.

    Customize the Dockerfile
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.4r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh
    docker
    FROM registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1
    # install internal tools
    WORKDIR /tmp
    ARG mytools_version="4.3"
    COPY install_mytools-"$mytools_version".sh .
    RUN  /tmp/install_mytools-"$mytools_version".sh

See also Jump to heading

Do you have any suggestions on how we can improve the content of this page? Please leave feedback!

Previous page Azure Next page Install the VM image