docker-easy-haproxy/docs/reference/container-labels.md

sidebar_position	sidebar_label
3	Container Labels

Container Labels

Container (Docker or Swarm) labels

Label	Description	Default	Example
easyhaproxy.[definition].host	Host(s) HAProxy is listening. More than one host use comma as delimiter	required	somehost.com OR host1.com,host2.com
easyhaproxy.[definition].mode	(Optional) Is this http or tcp mode in HAProxy.	http	http or tcp
easyhaproxy.[definition].port	(Optional) Port HAProxy will listen for the host.	80	3000
easyhaproxy.[definition].localport	(Optional) Port container is listening.	80	8080
easyhaproxy.[definition].redirect	(Optional) JSON containing key/value pair from host/to URL redirect.	empty	{"foo.com":"https://bla.com", "bar.com":"https://bar.org"}
easyhaproxy.[definition].sslcert	(Optional) Cert PEM Base64 encoded. Do not use this if certbot is enabled.	empty	base64 cert + key
easyhaproxy.[definition].ssl	(Optional) If true you need to provide certificate as a file. See below. Do not use with sslcert.	false	true or false
easyhaproxy.[definition].ssl-check	(Optional) ssl, enable health check via SSL in mode tcp	empty	ssl
easyhaproxy.[definition].certbot	(Optional) Generate certificate with certbot. Do not use with sslcert parameter. More info here.	false	true OR false
easyhaproxy.[definition].redirect_ssl	(Optional) Redirect all requests to https	false	true OR false
easyhaproxy.[definition].clone_to_ssl	(Optional) It copies the configuration to HTTPS(443) and disable SSL from the current config. Do not use this with ssl or certbot parameters	false	true OR false
easyhaproxy.[definition].balance	(Optional) HAProxy balance algorithm. See HAProxy documentation	roundrobin	roundrobin, source, uri, url_param, hdr, rdp-cookie, leastconn, first, static-rr, rdp-cookie, hdr_dom, map-based
easyhaproxy.[definition].proto	(Optional) Backend server protocol (e.g., fcgi for PHP-FPM, h2 for HTTP/2)	empty	fcgi, h2
easyhaproxy.[definition].socket	(Optional) Unix socket path for backend connection (alternative to host:port)	empty	/run/php/php-fpm.sock

:::info Understanding Definitions The [definition] is a string identifier that groups related configuration labels together. Different definitions create separate HAProxy configurations.

A single container can have multiple definitions to expose different services or ports. :::

Configurations

Single Definition

docker run \
    --label easyhaproxy.webapi.port=80\
    --label easyhaproxy.webapi.host=byjg.com.br \
    ....

Multiple Definitions on the same container

docker run \
    --label easyhaproxy.express.port=80 \
    --label easyhaproxy.express.localport=3000 \
    --label easyhaproxy.express.host=express.byjg.com.br \

    --label easyhaproxy.admin.port=80 \
    --label easyhaproxy.admin.localport=3001 \
    --label easyhaproxy.admin.host=admin.byjg.com.br \
    .... \
    some/myimage

Multiple hosts on the same container

docker run \
    --label easyhaproxy.express.port=80 \
    --label easyhaproxy.express.localport=3000 \
    --label easyhaproxy.express.host=express.byjg.com.br,admin.byjg.com.br \
    .... \
    some/myimage

If you are using docker-compose you can use this way:

services:
  mycontainer:
    image: some/myimage
    labels:
      easyhaproxy.express.port: 80
      easyhaproxy.express.localport: 3000
      easyhaproxy.express.host: >-
        express.byjg.com.br,
        admin.byjg.com.br

TCP Mode

Set easyhaproxy.[definition].mode=tcp if your application uses TCP protocol instead of HTTP.

docker run \
    --label easyhaproxy.example.mode=tcp \
    --label easyhaproxy.example.port=3306
    --label easyhaproxy.example.localport=3306
    .... \
    some/tcp-service

FastCGI (PHP-FPM) Support

EasyHAProxy supports FastCGI protocol for PHP-FPM and other FastCGI applications.

Using Unix Socket

services:
  php-fpm:
    image: php:8.2-fpm
    labels:
      easyhaproxy.fcgi.host: phpapp.local
      easyhaproxy.fcgi.port: 80
      easyhaproxy.fcgi.socket: /run/php/php-fpm.sock
      easyhaproxy.fcgi.proto: fcgi
    volumes:
      - /run/php:/run/php

Using TCP Connection

services:
  php-fpm:
    image: php:8.2-fpm
    labels:
      easyhaproxy.fcgi.host: phpapp.local
      easyhaproxy.fcgi.port: 80
      easyhaproxy.fcgi.localport: 9000
      easyhaproxy.fcgi.proto: fcgi

Generated HAProxy Configuration:

backend srv_phpapp_local_80
    balance roundrobin
    mode http
    option forwardfor
    http-request set-header X-Forwarded-Port %[dst_port]
    http-request add-header X-Forwarded-Proto https if { ssl_fc }
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    http-request set-header X-Request-ID %[uuid()]
    server srv-0 /run/php/php-fpm.sock check weight 1 proto fcgi

Redirect Domains

docker run \
    --label easyhaproxy.[definition].redirect='{"www.byjg.com.br":"http://byjg.com.br","byjg.com":"http://byjg.com.br"}'

---

Kubernetes Ingress Annotations

When using Kubernetes, configure EasyHAProxy behavior with these annotations on your Ingress resources. Annotations apply to all hosts in the ingress configuration.

Annotation	Description	Default	Example
kubernetes.io/ingress.class	(deprecated) Activate EasyHAProxy. Use spec.ingressClassName instead.	optional	easyhaproxy-ingress
easyhaproxy.redirect_ssl	(optional) Boolean. Force redirect all endpoints to HTTPS.	false	true or false
easyhaproxy.certbot	(optional) Boolean. Request certbot certificates for the ingress domains.	false	true or false
easyhaproxy.redirect	(optional) JSON. Key pair with a domain and its destination.	empty	{"domain":"redirect_url"}
easyhaproxy.mode	(optional) Set the HTTP mode for that connection.	http	http or tcp
easyhaproxy.listen_port	(optional) Override the HTTP listen port created for that ingress.	80	8081
easyhaproxy.plugins	(optional) Comma-separated list of plugins to enable for this ingress.	empty	cloudflare,deny_pages
easyhaproxy.plugin.{name}.{key}	(optional) Plugin-specific configuration (see Using Plugins)	varies	See plugin docs

For annotation usage examples, see the Kubernetes getting started guide.

---

Open source ByJG