From d43c7572d2a290375aba81c79457fc336071e9e4 Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Fri, 30 Jun 2023 13:35:12 -0500 Subject: [PATCH] Working on issue #41 --- docs/letsencrypt.md | 53 +++++++++++++++++++++++++-------------------- docs/ssl.md | 17 +++++++++------ 2 files changed, 39 insertions(+), 31 deletions(-) diff --git a/docs/letsencrypt.md b/docs/letsencrypt.md index 0e8c86b..d44c87b 100644 --- a/docs/letsencrypt.md +++ b/docs/letsencrypt.md @@ -2,49 +2,54 @@ EasyHAProxy can issue a letsencrypt certificate. Follow the steps below: -Run the EasyHAProxy: +## Setting up EasyHAProxy + +Run the EasyHAProxy container: ```bash docker run \ - -e EASYHAPROXY_LETSENCRYPT_EMAIL=john@doe.com - .... \ + ... \ + -e EASYHAPROXY_LETSENCRYPT_EMAIL=john@doe.com \ + -p 80:80 \ + -p 443:443 \ + -v /path/to/guest/lestencrypt/certs:/certs/letsencrypt \ + ... \ byjg/easy-haproxy ``` -Run your container: +Notes: + +- If you don't setup `EASYHAPROXY_LETSENCRYPT_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/) + +Be aware of Letsencrypt issue rate limits: + +- https://letsencrypt.org/docs/duplicate-certificate-limit/ +- https://letsencrypt.org/docs/rate-limits/ + +In order to avoid several certificate issuing, +**It is required you to persist the container folder `/certs/letsencrypt` outside the container.** +You cannot delete or change it contents. +If you do not persist, or change/delete the contents, Let's encrypt will not work properly. + + +## Setting up your container to use Let's Encrypt ```bash docker run \ + ... \ --label easyhaproxy.express.port=80 \ --label easyhaproxy.express.localport=3000 \ --label easyhaproxy.express.host=example.org \ --label easyhaproxy.express.letsencrypt=true \ - .... \ + ... \ some/myimage ``` Requirements: -- Your container **must** listen to port 80. Letsencrypt will not issue the certificate if `easyhaproxy.express.port` is in another port, and EasyHAProxy will fail silently. +- Your container **must** listen to port 80. Letsencrypt will not issue the certificate if `easyhaproxy..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. -- `EASYHAPROXY_LETSENCRYPT_EMAIL` environment variable is required to be set. If you don't set it up, EasyHAProxy **will not request** a certificate. - -Be aware of Letsencrypt issue limits - https://letsencrypt.org/docs/duplicate-certificate-limit/ and https://letsencrypt.org/docs/rate-limits/ - -## Persist your Letsencrypt certificates - -It is a good idea to store the letsencrypt certificate in persistent storage because of the limit on how many certificates can be issued for the same domain in a period. - -To do this, map the folder `/certs/letsencrypt` to a docker volume. - -```bash -docker volume create certs_letsencrypt - -docker run \ - /* other parameters */ - -v certs_letsencrypt:/certs/letsencrypt \ - -d byjg/easy-haproxy -``` ---- [Open source ByJG](http://opensource.byjg.com) diff --git a/docs/ssl.md b/docs/ssl.md index 4384bbf..c2f551d 100644 --- a/docs/ssl.md +++ b/docs/ssl.md @@ -4,9 +4,12 @@ You can use your certificates with EasyHAProxy. There are two ways to do that. +- [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 -### Create a single PEM from the certificate and key. +1. Create a single PEM from the certificate and key. ```bash cat example.com.crt example.com.key > single.pem @@ -24,21 +27,21 @@ MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL -----END PRIVATE KEY----- ``` -### Convert the `single.pem` to BASE64 in a single line: +2. Convert the `single.pem` to BASE64 in a single line: ```bash cat single.pem | base64 -w0 ``` -### Map the BASE64 to your container +3. Define a label in yout container Add the Base64 string you generated before to the label `easyhaproxy.[definition].sslcert` ## Map the certificate as a docker volume -EasyHAProxy stores the certificates inside the folder `/certs/haproxy`. +EasyHAProxy stores the certificates inside the container folder `/certs/haproxy`. -### Run EasyHAProxy with the volume for the certificates: +1. Run EasyHAProxy with the volume for the certificates: ```bash docker volume create certs_haproxy @@ -49,7 +52,7 @@ docker run \ -d byjg/easy-haproxy ``` -### Create a single PEM from the certificate and the key. +2. Create a single PEM from the certificate and the key. ```bash cat example.com.crt example.com.key > single.pem @@ -67,7 +70,7 @@ MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL -----END PRIVATE KEY----- ``` -### Copy this certificate to EasyHAProxy volume +3. Copy this certificate to EasyHAProxy volume ```bash docker cp single.pem easyhaproxy:/certs/haproxy