Docker HAProxy ACME

A Docker image that combines haproxy and acme.sh.

Motivation

The combination of haproxy and acme.sh provides a lightweight alternative to Traefik to implement SSL (TLS) termination for public facing Docker services. A main advantage is the decentralized organization of certificates and the implementation of the Zero Trust principle within a container group.

`haproxy-acme-http01`

The haproxy-acme-http01 image is a ready-to-run image for local SSL termination and has the following core features:

HAProxy listening on port 80 and 443
- Port 80 is used for the HTTP-01 ACME certificate challenge and otherwise redirects to https by default
- Port 443 redirects traffic to a configurable host:port and provides SSL termination
Issues a SSL certificate on startup
- Configurable ACME provider (Let's Encrypt, ZeroSSL, ...)
- Configurable key length (2048, 4096, ec-256, ...)
- Supports SAN certificates
Automatic certificate renewal
- HAProxy Hitless Reload (zero downtime)
- Configurable certificate renewal notifications (WiP)

Example

docker run -d --name haproxy-acme-http01 \
    -e "ACME_MAIL=mail@domain.com" \
    -e "ACME_DOMAIN=domain.com" \
    -e "SERVER_ADDRESS=whoami" \
    -e "SERVER_PORT=80" \
    -v /docker_data/acme:/var/lib/acme:rw \
    -p 80:80 \
    -p 443:443 \
    --sysctl net.ipv4.ip_unprivileged_port_start=0 \
    ghcr.io/flobernd/haproxy-acme-http01

Docker Compose Example

services:
  haproxy-acme:
    image: ghcr.io/flobernd/haproxy-acme-http01:latest
    container_name: haproxy-acme-http01
    restart: unless-stopped
    environment:
      - ACME_MAIL=mail@domain.com
      - ACME_DOMAIN=domain.com
      - SERVER_ADDRESS=whoami
      - SERVER_PORT=80
    volumes:
      - /docker_data/acme:/var/lib/acme:rw
    ports:
      - 80:80
      - 443:443
    sysctls:
      - net.ipv4.ip_unprivileged_port_start = 0

  whoami:
    image: traefik/whoami
    container_name: whoami
    restart: unless-stopped

Persistence

It is strongly recommended to specify an external volume for the /var/lib/acme directory. Most ACME servers enforce a rate limit for issuing and renewing certificates. If you recreate the container without preserving the internal state of acme.sh, a new certificate will also be created each time.

HAProxy Configuration

The container creates a default configuration file haproxy.cfg in the /usr/local/etc/haproxy directory.

By mapping the aforementioned path, the primary haproxy.cfg can be freely customized. Alternatively, additional configurations can be placed in the include directory, which are then loaded after the primary configuration in alphabetical order.

As long as the default config has not been modified or overwritten, the SERVER_ADDRESS (required), SERVER_PORT (default 80), HAPROXY_HTTP_PORT (default 80) and HAPROXY_HTTPS_PORT (default 443) environment variables must be set. Otherwise the container will fail to start.

Important

When overwriting the default configuration, make sure that the stats socket directive is retained. Otherwise, the deployment of certificates will fail.

global
  # Allow 'acme.sh' to deploy new certificates without reloading
  stats socket /var/lib/haproxy/admin.sock level admin mode 660

Important

When overwriting the default configuration, make sure that the http frontend correctly responds to the http-01 challenge. Otherwise, the issuing of certificates will fail.

frontend http
  mode http
  [...]
  # Respond to ACME HTTP-01 challenge
  http-request return status 200 content-type text/plain lf-string "%[path,field(-1,/)].${ACME_ACCOUNT_THUMBPRINT}\n" if { path_beg '/.well-known/acme-challenge/' }

Environment

`ACME_DEBUG`

Set to 1 in order to enable verbose acme.sh debug output.

`ACME_UPGRADE`

Set to 1 in order to automatically update acme.sh to the latest version on container startup. This requires an active internet connection (default: 0).

`ACME_CRON`

Set to 1 in order to enable the certificate renewal cronjob (default: 1).

`ACME_SERVER`

The ACME server to use (default: letsencrypt).

Supported values: letsencrypt, letsencrypt_test, buypass, buypass_test, zerossl, sslcom, google, googletest or an explicit ACME server directory URL like e.g. https://acme-v02.api.letsencrypt.org/directory

See also: https://github.com/acmesh-official/acme.sh/wiki/Server

`ACME_MAIL`

The mail address for the ACME account registration (required).

`ACME_DOMAIN`

The domain to issue the certificate for (required). To issue a multi-domain certificate (SAN), enter additional domains separated by a space character after the primary domain.

For example: sub.domain.com (single), domain.com *.domain.com (SAN)

`ACME_KEYLENGTH`

The desired domain key length (default: ec-256).

Supported values (depending on the ACME server capabilities): 2048, 3072, 4096, 8192, ec-256, ec-384, ec-521.

`HAPROXY_HTTP_PORT`

The internal haproxy HTTP listening port. Allows changing the internal port to a non-privileged one (default: 80). Do not forget to adjust the Docker port mapping accordingly (e.g. -p 80:8080).

`HAPROXY_HTTPS_PORT`

The internal haproxy HTTPS listening port. Allows changing the internal port to a non-privileged one (default: 443). Do not forget to adjust the Docker port mapping accordingly (e.g. -p 443:8443).

`SERVER_ADDRESS`

The hostname or IP-address of the internal service for which SSL terminiation should be provided (required).

`SERVER_PORT`

The port of the internal service for which SSL terminiation should be provided (default: 80).

`SERVER_DIRECTIVES`

Optional directives for communicating with the internal service. For example ssl must be specified here, if the internal service uses HTTPS. Check the haproxy documentation for more directives.

`haproxy-acme-dns01`

The haproxy-acme-dns01 image is a ready-to-run image for local SSL termination and has the following core features:

Issues a SSL certificate on startup
- Configurable ACME provider (Let's Encrypt, ZeroSSL, ...)
- Configurable key length (2048, 4096, ec-256, ...)
- Supports SAN certificates
- Supports wildcard certificates
Automatic certificate renewal
- HAProxy Hitless Reload (zero downtime)
- Configurable certificate renewal notifications (WiP)

Example

docker run -d --name haproxy-acme-dns01 \
    -e "ACME_MAIL=mail@domain.com" \
    -e "ACME_DOMAIN=domain.com *.domain.com" \
    -e "ACME_DNS_API=dns_cf" \
    -e "CF_Token=<redacted>" \
    -e "CF_Zone_ID=<redacted>" \
    -v /docker_data/acme:/var/lib/acme:rw \
    -p 80:80 \
    -p 443:443 \
    ghcr.io/flobernd/haproxy-acme-dns01

Docker Compose Example

services:
  haproxy-acme:
    image: ghcr.io/flobernd/haproxy-acme-dns01:latest
    container_name: haproxy-acme-dns01
    restart: unless-stopped
    environment:
      - "ACME_MAIL=mail@domain.com"
      - "ACME_DOMAIN=domain.com *.domain.com"
      - "ACME_DNS_API=dns_cf"
      - "CF_Token=<redacted>"
      - "CF_Zone_ID=<redacted>"
    volumes:
      - /docker_data/acme:/var/lib/acme:rw
    ports:
      - 80:80
      - 43:443

Persistence

It is strongly recommended to specify an external volume for the /var/lib/acme directory. Most ACME servers enforce a rate limit for issuing and renewing certificates. If you recreate the container without preserving the internal state of acme.sh, a new certificate will also be created each time.

HAProxy Configuration

The container creates a default configuration file haproxy.cfg in the /usr/local/etc/haproxy directory.

By mapping the aforementioned path, the primary haproxy.cfg can be freely customized. Alternatively, additional configurations can be placed in the include directory, which are then loaded after the primary configuration in alphabetical order.

As long as the default config has not been modified or overwritten, the SERVER_ADDRESS (required), SERVER_PORT (default 80), HAPROXY_HTTP_PORT (default 80) and HAPROXY_HTTPS_PORT (default 443) environment variables must be set. Otherwise the container will fail to start.

Important

When overwriting the default configuration, make sure that the stats socket directive is retained. Otherwise, the deployment of certificates will fail.

global
  # Allow 'acme.sh' to deploy new certificates without reloading
  stats socket /var/lib/haproxy/admin.sock level admin mode 660

Environment

`ACME_DEBUG`

Set to 1 in order to enable verbose acme.sh debug output.

`ACME_UPGRADE`

Set to 1 in order to automatically update acme.sh to the latest version on container startup. This requires an active internet connection (default: 0).

`ACME_CRON`

Set to 1 in order to enable the certificate renewal cronjob (default: 1).

`ACME_SERVER`

The ACME server to use (default: letsencrypt).

Supported values: letsencrypt, letsencrypt_test, buypass, buypass_test, zerossl, sslcom, google, googletest or an explicit ACME server directory URL like e.g. https://acme-v02.api.letsencrypt.org/directory

See also: https://github.com/acmesh-official/acme.sh/wiki/Server

`ACME_MAIL`

The mail address for the ACME account registration (required).

`ACME_DOMAIN`

The domain to issue the certificate for (required). To issue a multi-domain certificate (SAN), enter additional domains separated by a space character after the primary domain.

For example: sub.domain.com (single), domain.com *.domain.com (SAN)

`ACME_KEYLENGTH`

The desired domain key length (default: ec-256).

Supported values (depending on the ACME server capabilities): 2048, 3072, 4096, 8192, ec-256, ec-384, ec-521.

`ACME_DNS_API`

The DNS API to use (required).

Supported values (incomplete): dns_cf (Cloudflare), dns_azure (Azure), dns_gcloud (Google Cloud), ...

Depending on the DNS API, additional environment variables must be passed to the container. For example, dns_cf requires the CF_Token and CF_Zone_ID/CF_Account_ID environment variables to be set.

See also: https://github.com/acmesh-official/acme.sh/wiki/dnsapi

`ACME_DNS_SLEEP`

The time in seconds to wait for all the TXT records to propagate in DNS API mode. It's not necessary to use this by default, acme.sh polls DNS status by DOH automatically.

`HAPROXY_HTTP_PORT`

The internal haproxy HTTP listening port. Allows changing the internal port to a non-privileged one (default: 80). Do not forget to adjust the Docker port mapping accordingly (e.g. -p 80:8080).

`HAPROXY_HTTPS_PORT`

The internal haproxy HTTPS listening port. Allows changing the internal port to a non-privileged one (default: 443). Do not forget to adjust the Docker port mapping accordingly (e.g. -p 443:8443).

`SERVER_ADDRESS`

The hostname or IP-address of the internal service for which SSL terminiation should be provided (required).

`SERVER_PORT`

The port of the internal service for which SSL terminiation should be provided (default: 80).

`SERVER_DIRECTIVES`

Optional directives for communicating with the internal service. For example ssl must be specified here, if the internal service uses HTTPS. Check the haproxy documentation for more directives.

`haproxy-acme`

The base image haproxy-acme is based on the Docker "Official Image" for haproxy and the acme.sh Bash script. It serves as a generic template, providing some hook points for customization:

`/usr/local/bin/acmeinit.early.sh`

This script is executed before haproxy starts. Environment variables exported by this script can be used in the haproxy configuration file.

`/usr/local/bin/acmeinit.late.sh`

This script is executed after haproxy started.

`/usr/local/bin/initialize.sh`

This script is executed as root before switching to the haproxy user context.

`/usr/local/etc/haproxy`

The default location of the main haproxy configuration file haproxy.cfg and the includes directory.

License

Docker HAProxy ACME is licensed under the MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
haproxy-acme-dns01		haproxy-acme-dns01
haproxy-acme-http01		haproxy-acme-http01
haproxy-acme		haproxy-acme
.editorconfig		.editorconfig
.gitattributes		.gitattributes
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh

License

flobernd/docker-haproxy-acme

Folders and files

Latest commit

History

Repository files navigation

Docker HAProxy ACME

Motivation

haproxy-acme-http01

Example

Docker Compose Example

Persistence

HAProxy Configuration

Environment

ACME_DEBUG

ACME_UPGRADE

ACME_CRON

ACME_SERVER

ACME_MAIL

ACME_DOMAIN

ACME_KEYLENGTH

HAPROXY_HTTP_PORT

HAPROXY_HTTPS_PORT

SERVER_ADDRESS

SERVER_PORT

SERVER_DIRECTIVES

haproxy-acme-dns01

Example

Docker Compose Example

Persistence

HAProxy Configuration

Environment

ACME_DEBUG

ACME_UPGRADE

ACME_CRON

ACME_SERVER

ACME_MAIL

ACME_DOMAIN

ACME_KEYLENGTH

ACME_DNS_API

ACME_DNS_SLEEP

HAPROXY_HTTP_PORT

HAPROXY_HTTPS_PORT

SERVER_ADDRESS

SERVER_PORT

SERVER_DIRECTIVES

haproxy-acme

/usr/local/bin/acmeinit.early.sh

/usr/local/bin/acmeinit.late.sh

/usr/local/bin/initialize.sh

/usr/local/etc/haproxy

License

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages

`haproxy-acme-http01`

`ACME_DEBUG`

`ACME_UPGRADE`

`ACME_CRON`

`ACME_SERVER`

`ACME_MAIL`

`ACME_DOMAIN`

`ACME_KEYLENGTH`

`HAPROXY_HTTP_PORT`

`HAPROXY_HTTPS_PORT`

`SERVER_ADDRESS`

`SERVER_PORT`

`SERVER_DIRECTIVES`

`haproxy-acme-dns01`

`ACME_DEBUG`

`ACME_UPGRADE`

`ACME_CRON`

`ACME_SERVER`

`ACME_MAIL`

`ACME_DOMAIN`

`ACME_KEYLENGTH`

`ACME_DNS_API`

`ACME_DNS_SLEEP`

`HAPROXY_HTTP_PORT`

`HAPROXY_HTTPS_PORT`

`SERVER_ADDRESS`

`SERVER_PORT`

`SERVER_DIRECTIVES`

`haproxy-acme`

`/usr/local/bin/acmeinit.early.sh`

`/usr/local/bin/acmeinit.late.sh`

`/usr/local/bin/initialize.sh`

`/usr/local/etc/haproxy`

Packages