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

Improve SSL and ACME documentation

Browse source 
- Clarify that EASYHAPROXY_CERTBOT_AUTOCONFIG or CERTBOT_SERVER is required
- Add complete docker-compose.yml examples for ACME setup
- Explain SSL termination at HAProxy level vs backend containers
- Reorganize SSL docs to emphasize volume method over label method
- Add troubleshooting section for common ACME warnings
- Clarify certificate storage paths and selection priority
- Add examples showing both ACME and manual certificates together

Resolves confusion about ACME configuration requirements and makes
it clear that volume-mounted certificates are the recommended method
for manual SSL certificates.
This commit is contained in:
Joao Gilberto Magalhaes 2026-02-16 15:53:55 -05:00
parent c340de1d9d
commit 4aba68dd37
3 changed files with 244 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

128
docs/ssl.md
View file

@ -4,42 +4,31 @@ sidebar_position: 9
# Setup custom certificates
You can use your own certificates with EasyHAProxy. You just need to let EasyHAProxy know that certificate.
You can use your own certificates with EasyHAProxy instead of (or in addition to) automatic ACME/Certbot certificates.
There are two ways to do that.
:::info How SSL Termination Works
SSL termination happens at the **HAProxy level**, NOT in your backend containers.
- Your backend containers should **only** expose HTTP (port 80), not HTTPS
- HAProxy handles all SSL/TLS encryption and decryption
- Backend containers receive plain HTTP traffic from HAProxy
- Do NOT configure SSL in your backend application when using EasyHAProxy
This is the **correct design** - it centralizes SSL management at the proxy layer.
:::
:::info Certificate Types
EasyHAProxy supports two certificate sources:
- **ACME/Certbot automatic certificates** - Issued automatically via Let's Encrypt or other ACME providers (see [ACME documentation](./acme.md))
- **Manual/custom certificates** - Your own certificates loaded via volume mount (recommended) or labels (this page)
Both can be used simultaneously. Per domain, ACME certificates (if `certbot=true` label is set) take precedence over manual certificates.
:::
There are two ways to provide custom certificates:
- [Setup certificate as a label definition in docker container](#setup-certificate-as-a-label-definition-in-docker-container)
- [Map the certificate as a docker volume](#map-the-certificate-as-a-docker-volume)
## Setup certificate as a label definition in docker container
1. Create a single PEM from the certificate and key.
```bash title="Combine certificate and key"
cat example.com.crt example.com.key > single.pem
cat single.pem
-----BEGIN CERTIFICATE-----
MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC5ZheHqmBnEJP+
U9r1gxYWKLzdqrMrcxtQN6M1hIH9n0peuJeIrybdcV7sMbStMXI=
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL
3j4wz8/I5fdsk090j4s5KA==
-----END PRIVATE KEY-----
```
2. Convert the `single.pem` to BASE64 in a single line:
```bash title="Convert to BASE64"
cat single.pem | base64 -w0
```
3. Define a label in yout container
Add the Base64 string you generated before to the label `easyhaproxy.[definition].sslcert`
- [Setup certificate as a label definition](#setup-certificate-as-a-label-definition-in-docker-container)
## Map the certificate as a docker volume
@ -77,8 +66,79 @@ MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL
3. Copy this certificate to EasyHAProxy volume:
```bash title="Copy certificate to container"
docker cp single.pem easyhaproxy:/etc/easyhaproxy/certs/haproxy
# IMPORTANT: Filename must match the domain!
docker cp single.pem easyhaproxy:/etc/easyhaproxy/certs/haproxy/example.com.pem
```
:::warning Important Notes
- The filename **must match the domain name**: `example.com.pem` for domain `example.com`
- When using volume-mounted certificates, **do NOT** use the `easyhaproxy.[definition].sslcert` label
- The volume mount method and the label method are **mutually exclusive** per domain
- SSL termination happens at HAProxy - your backend containers should only serve HTTP
:::
4. Configure your backend container (no sslcert label needed):
```yaml
services:
easyhaproxy:
image: byjg/easy-haproxy:5.0.0
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- certs_haproxy:/etc/easyhaproxy/certs/haproxy
ports:
- "80:80"
- "443:443"
myapp:
image: nginx
labels:
easyhaproxy.web.host: example.com
easyhaproxy.web.port: 80 # Frontend port (HAProxy listens here)
easyhaproxy.web.localport: 80 # Backend port (your container)
# NO sslcert label when using volume method!
volumes:
certs_haproxy:
```
## Setup certificate as a label definition in docker container
:::info Alternative Method
This method embeds certificates directly in container labels. Use it when you want certificates in version control or don't want to manage external files. **Volume method is recommended for most use cases.**
:::
1. Create a single PEM from the certificate and key:
```bash title="Combine certificate and key"
cat example.com.crt example.com.key > single.pem
```
2. Convert the `single.pem` to BASE64 in a single line:
```bash title="Convert to BASE64"
cat single.pem | base64 -w0
```
3. Add the Base64 string to your container label:
```yaml
services:
myapp:
image: nginx
labels:
easyhaproxy.web.host: example.com
easyhaproxy.web.port: 80
easyhaproxy.web.localport: 80
easyhaproxy.web.sslcert: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..." # Base64 certificate
```
:::warning When Using Label Method
- **There is no necessary to** mount the `/etc/easyhaproxy/certs/haproxy` volume for this domain
- Using `sslcert` label means the volume-mounted certificate will be **ignored**
- Certificate is visible in `docker inspect` output (less secure)
- Updating requires container redeployment
:::
----
[Open source ByJG](http://opensource.byjg.com)