badblocks/docker-easy-haproxy
1
0
Fork 0
Code Activity

Enhance documentation with Docusaurus features and fix inaccuracies

Browse source 
Verified against source code and enhanced with Docusaurus markdown features:

Documentation Accuracy Fixes:
- Fixed acme.md: Added "letsencrypt" as valid AUTOCONFIG value (was incorrectly shown as "-")
- Added reference to ACME docs from environment-variable.md
- Verified all features against actual implementation in /src

Docusaurus Enhancements Added:
- Admonitions (:::note, :::tip, :::warning, :::danger, :::info) for important callouts
- Code block titles for all bash/yaml examples (e.g., title="Install EasyHAProxy")
- Better structured warnings and notes for limitations
- Improved formatting and readability throughout

Files Enhanced:
- kubernetes.md: Added info boxes, warnings, code titles
- docker.md: Added limitation warnings, code titles
- swarm.md: Added advantage tips, limitation warnings
- acme.md: Fixed Let's Encrypt autoconfig, enhanced requirements with admonitions
- ssl.md: Added code block titles for all examples
- static.md: Added live reload tip, SSL certificate note
- container-labels.md: Added definition explanation, code titles
- limitations.md: Restructured with clear warnings and explanations
- helm.md: Added warnings, code titles
- microk8s.md: Added ingress controller warning, code titles
- volumes.md: Added info box about volume purposes
- other.md: Added code block titles
- environment-variable.md: Added ACME reference note

All changes verified against actual Python source code implementation.
This commit is contained in:
Claude 2025-11-09 23:50:44 +00:00
parent 96120d4554
commit aee9645b43
No known key found for this signature in database
13 changed files with 140 additions and 105 deletions
Download patch file Download diff file Expand all files Collapse all files

38
docs/acme.md
View file

@ -17,9 +17,11 @@ Easy HAProxy supports the following ACME challenge types:
- **HTTP-01 Challenge (Default and Only)**
The ACME server validates ownership by making an HTTP request to a temporary endpoint served on port 80. Easy HAProxy provisions a standalone Certbot responder on an internal port and routes `/.well-known/acme-challenge/` traffic to it.
> Note:
> - TLS-ALPN-01 is not supported natively by Easy HAProxy.
> - DNS-01 (often used for wildcard certificates) is not supported natively. If you need DNS-01, obtain certificates externally and mount them via `sslcert` as static certificates.
:::info Challenge Support
- **HTTP-01**: Fully supported (default)
- **TLS-ALPN-01**: Not supported natively by Easy HAProxy
- **DNS-01**: Not supported natively. If you need DNS-01 for wildcard certificates, obtain certificates externally and mount them via `sslcert` as static certificates.
:::
## How ACME works with Easy HAProxy
@ -73,7 +75,7 @@ Possible values for: `EASYHAPROXY_CERTBOT_AUTOCONFIG`
| CA | Auto Config | Free? | Account Required? | EAB KID? | EAB HMAC Key? | More Info |
|----------------------|------------------|-------|--------------------|----------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Let's Encrypt | - | Yes | No | No | No | - |
| Let's Encrypt | letsencrypt | Yes | No | No | No | Default when no AUTOCONFIG is set |
| Let's Encrypt (Test) | letsencrypt_test | Yes | No | No | No | - |
| ZeroSSL | zerossl | Yes | No | No | No | [Link](https://zerossl.com/documentation/acme/) |
| BuyPass | buypass | Yes | No | No | No | [Link](https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints-updated-14-05-2020) |
@ -108,16 +110,18 @@ docker run \
byjg/easy-haproxy
```
Notes:
:::note Configuration Notes
- The `EASYHAPROXY_CERTBOT_AUTOCONFIG` is not required for Let's Encrypt (it's the default). In this example, the certificate will be issued by ZeroSSL.
- If you don't set the `EASYHAPROXY_CERTBOT_EMAIL` environment variable, EasyHAProxy will fail silently and **will not request** certificates.
- Ports 80 and 443 must be accessible through the internet as a [Let's Encrypt requirement](https://letsencrypt.org/docs/allow-port-80/)
:::
- The `EASYHAPROXY_CERTBOT_AUTOCONFIG` is not required for Let's Encrypt. In this example, the certificate will be issued by ZeroSSL.
- If you don't setup `EASYHAPROXY_CERTBOT_EMAIL` environment variable, EasyHAProxy will fail silently and **will not request** a certificate.
- The ports 80 and 443 needs to accessible through the internet as [Let's Encrypt requirement](https://letsencrypt.org/docs/allow-port-80/)
In order to avoid several certificate issuing,
**It is required you to persist the container folder `/certs/certbot` outside the container.**
You cannot delete or change it contents.
If you do not persist, or change/delete the contents, Issue a certificate might not work properly and hit rate limit.
:::danger Important: Persist Certbot Certificates
To avoid hitting rate limits and certificate issuing problems:
- **You must persist** the container folder `/certs/certbot` outside the container
- **Never delete or modify** its contents manually
- If you don't persist this folder, or if you delete/modify its contents, certificate issuing may not work properly and you may hit rate limits
:::
If you are using Let's Encrypt, be aware of it rate limits:
@ -138,10 +142,10 @@ docker run \
some/myimage
```
Requirements:
- Your container **must** listen to port 80. The CA will not issue the certificate if `easyhaproxy.<definition>.port` is in another port, and EasyHAProxy will fail silently.
- You cannot set port 443 for the container with the Letsencrypt because EasyHAProxy will create this port automatically once the certificate is issued.
:::warning ACME Requirements
- Your container **must** be configured to listen on port 80 (`easyhaproxy.<definition>.port=80`). The CA will not issue certificates if using another port, and EasyHAProxy will fail silently.
- Do not set port 443 for the container when using ACME, because EasyHAProxy will create the HTTPS binding automatically once the certificate is issued.
:::
----
[Open source ByJG](http://opensource.byjg.com)