From 96120d4554e199424d924acea094cdce2881bc95 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 9 Nov 2025 23:44:14 +0000 Subject: [PATCH 1/3] Add Docusaurus frontmatter and improve documentation structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add sidebar_position to all documentation files (1-15) - Add "Configuration Reference" section to README.md with links to: - Container Labels - Environment Variables - Volumes - Other Configurations - Limitations - Ensure sidebar_position values match README.md link order exactly - Order follows logical flow: Platform installation → Tool installation → Special topics → Configuration reference - All documentation now properly configured for Docusaurus --- README.md | 10 ++++++++++ docs/acme.md | 4 ++++ docs/container-labels.md | 4 ++++ docs/digitalocean.md | 4 ++++ docs/docker.md | 4 ++++ docs/dokku.md | 4 ++++ docs/environment-variable.md | 4 ++++ docs/helm.md | 4 ++++ docs/kubernetes.md | 4 ++++ docs/limitations.md | 4 ++++ docs/microk8s.md | 4 ++++ docs/other.md | 4 ++++ docs/ssl.md | 4 ++++ docs/static.md | 4 ++++ docs/swarm.md | 4 ++++ docs/volumes.md | 4 ++++ 16 files changed, 70 insertions(+) diff --git a/README.md b/README.md index e66b7d0..a74c2af 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,16 @@ If you already set up the EasyHAProxy, is time to go deeper: - [Custom SSL](docs/ssl.md) - [Automatic Certificate Issuing](docs/acme.md) (e.g. Letsencrypt) +## Configuration Reference + +Detailed configuration guides for advanced setups: + +- [Container Labels](docs/container-labels.md) - Configure Docker/Swarm containers with labels +- [Environment Variables](docs/environment-variable.md) - Configure EasyHAProxy behavior +- [Volumes](docs/volumes.md) - Map volumes for certificates, config, and custom files +- [Other Configurations](docs/other.md) - Additional configurations (ports, custom errors, etc.) +- [Limitations](docs/limitations.md) - Important limitations and considerations + ## See EasyHAProxy in action Click on the image to see the videos (use HD for better visualization) diff --git a/docs/acme.md b/docs/acme.md index 8e43d3e..a92d3eb 100644 --- a/docs/acme.md +++ b/docs/acme.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 10 +--- + # SSL - Automatic Certificate Management Environment (ACME) The Automatic Certificate Management Environment (ACME) protocol diff --git a/docs/container-labels.md b/docs/container-labels.md index fea51a8..443de2f 100644 --- a/docs/container-labels.md +++ b/docs/container-labels.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 11 +--- + # Container Labels ## Container (Docker or Swarm) labels diff --git a/docs/digitalocean.md b/docs/digitalocean.md index ff1edec..de48e9f 100644 --- a/docs/digitalocean.md +++ b/docs/digitalocean.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 8 +--- + # DigitalOcean DigitalOcean is a cloud infrastructure provider focused on simplifying web infrastructure for software developers. diff --git a/docs/docker.md b/docs/docker.md index ffa139c..f3eae41 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 3 +--- + # Docker ## Setup Docker EasyHAProxy diff --git a/docs/dokku.md b/docs/dokku.md index a8c2e25..9b5490c 100644 --- a/docs/dokku.md +++ b/docs/dokku.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 7 +--- + # Dokku Dokku is a Docker powered mini-Heroku in around 100 lines of Bash. It is the smallest PaaS implementation you've ever seen, weighing in at a little over 100 MB of memory usage and about 80 MB of disk space. diff --git a/docs/environment-variable.md b/docs/environment-variable.md index 661438d..ab841af 100644 --- a/docs/environment-variable.md +++ b/docs/environment-variable.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 12 +--- + # Docker environment variables | Environment Variable | Description | Default | diff --git a/docs/helm.md b/docs/helm.md index ae35f59..9a9b28a 100644 --- a/docs/helm.md +++ b/docs/helm.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 5 +--- + # Helm 3 Helm is a package manager for Kubernetes. It allows you to install and manage applications on Kubernetes. diff --git a/docs/kubernetes.md b/docs/kubernetes.md index 4305df1..3bc9e71 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 1 +--- + # Kubernetes ## Setup Kubernetes EasyHAProxy diff --git a/docs/limitations.md b/docs/limitations.md index 309ea52..da77984 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 15 +--- + # Limitations and Considerations ## EasyHAProxy will not work with --network=host diff --git a/docs/microk8s.md b/docs/microk8s.md index b4880f5..2d5c9ad 100644 --- a/docs/microk8s.md +++ b/docs/microk8s.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 6 +--- + # Microk8s Add-ons Microk8s is a lightweight Kubernetes distribution that can run on a single machine. It is very easy to install and use. diff --git a/docs/other.md b/docs/other.md index 37fea53..6466a0a 100644 --- a/docs/other.md +++ b/docs/other.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 14 +--- + # Other configurations ## Exposing Ports diff --git a/docs/ssl.md b/docs/ssl.md index 9b49e0c..d4c13a3 100644 --- a/docs/ssl.md +++ b/docs/ssl.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 9 +--- + # Setup custom certificates You can use your own certificates with EasyHAProxy. You just need to let EasyHAProxy know that certificate. diff --git a/docs/static.md b/docs/static.md index 4f7c3a1..ab03363 100644 --- a/docs/static.md +++ b/docs/static.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 4 +--- + # Static File ## Setup Docker EasyHAProxy diff --git a/docs/swarm.md b/docs/swarm.md index 5c0b8c2..ec93886 100644 --- a/docs/swarm.md +++ b/docs/swarm.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 2 +--- + # Swarm ## Setup Docker EasyHAProxy diff --git a/docs/volumes.md b/docs/volumes.md index 47daa02..945ef17 100644 --- a/docs/volumes.md +++ b/docs/volumes.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 13 +--- + # Volumes You can map the following volumes: From aee9645b4354b57f00d02ab507315f33857e3bd7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 9 Nov 2025 23:50:44 +0000 Subject: [PATCH 2/3] Enhance documentation with Docusaurus features and fix inaccuracies 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. --- docs/acme.md | 38 ++++++++++++++++++++---------------- docs/container-labels.md | 22 +++++++++++---------- docs/docker.md | 19 +++++++++--------- docs/environment-variable.md | 3 +++ docs/helm.md | 14 +++++++------ docs/kubernetes.md | 26 +++++++++++++----------- docs/limitations.md | 36 +++++++++++++++++++++------------- docs/microk8s.md | 18 +++++++++-------- docs/other.md | 8 ++++---- docs/ssl.md | 14 ++++++------- docs/static.md | 15 ++++++++------ docs/swarm.md | 28 ++++++++++++++------------ docs/volumes.md | 4 ++++ 13 files changed, 140 insertions(+), 105 deletions(-) diff --git a/docs/acme.md b/docs/acme.md index a92d3eb..1e1765f 100644 --- a/docs/acme.md +++ b/docs/acme.md @@ -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..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..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) \ No newline at end of file diff --git a/docs/container-labels.md b/docs/container-labels.md index 443de2f..ae05902 100644 --- a/docs/container-labels.md +++ b/docs/container-labels.md @@ -21,24 +21,26 @@ sidebar_position: 11 | 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](https://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4.2-balance) | roundrobin | roundrobin, source, uri, url_param, hdr, rdp-cookie, leastconn, first, static-rr, rdp-cookie, hdr_dom, map-based | -The `definition` is a string that will group all configurations togethers. Different `definition` will create different configurations. +:::info Understanding Definitions +The `[definition]` is a string identifier that groups related configuration labels together. Different definitions create separate HAProxy configurations. -The container can have more than one definition. +A single container can have multiple definitions to expose different services or ports. +::: ## Configuations ### Single Definition -```bash +```bash title="Single service configuration" docker run \ --label easyhaproxy.webapi.port=80\ --label easyhaproxy.webapi.host=byjg.com.br \ .... ``` -### Multiples Definitions on the same container +### Multiple Definitions on the same container -```bash +```bash title="Multiple services on one container" docker run \ --label easyhaproxy.express.port=80 \ --label easyhaproxy.express.localport=3000 \ @@ -51,9 +53,9 @@ docker run \ some/myimage ``` -### Multiples hosts on the same container +### Multiple hosts on the same container -```bash +```bash title="Multiple hosts for one service" docker run \ --label easyhaproxy.express.port=80 \ --label easyhaproxy.express.localport=3000 \ @@ -80,9 +82,9 @@ services: ### TCP Mode -Set `easyhaproxy.[definition].mode=tcp` if your application uses TCP protocol instead of HTTP. +Set `easyhaproxy.[definition].mode=tcp` if your application uses TCP protocol instead of HTTP. -```bash +```bash title="TCP mode configuration" docker run \ --label easyhaproxy.example.mode=tcp \ --label easyhaproxy.example.port=3306 @@ -93,7 +95,7 @@ docker run \ ### Redirect Domains -```bash +```bash title="Domain redirect configuration" docker run \ --label easyhaproxy.[definition].redirect='{"www.byjg.com.br":"http://byjg.com.br","byjg.com":"http://byjg.com.br"}' ``` diff --git a/docs/docker.md b/docs/docker.md index f3eae41..508df98 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -16,19 +16,20 @@ To accomplish this, EasyHAProxy may need to attach the same network to its conta It's recommended to create a network external to EasyHAProxy, although it's not mandatory. -Limitations: - - You cannot mix Docker containers with Swarm containers. - - This method does not work with containers that use the '--network=host' option. (see [limitations](limitations.md)) +:::warning Limitations +- You cannot mix Docker containers with Swarm containers. +- This method does not work with containers that use the `--network=host` option. See [limitations](limitations.md) for details. +::: -e.g.: +For example: -```bash +```bash title="Create EasyHAProxy network" docker network create easyhaproxy ``` -And then run the EasyHAProxy +And then run the EasyHAProxy: -```bash +```bash title="Run EasyHAProxy container" docker run -d \ --name easy-haproxy-container \ -v /var/run/docker.sock:/var/run/docker.sock \ @@ -45,9 +46,9 @@ Mapping to `/var/run/docker.sock` is necessary to discover the docker containers ## Running containers -To make your containers "discoverable" by EasyHAProxy, that is the minimum configuration you need: +To make your containers "discoverable" by EasyHAProxy, this is the minimum configuration you need: -```bash +```bash title="Run container with EasyHAProxy labels" docker run -d \ --label easyhaproxy.http.host=example.org \ --label easyhaproxy.http.port=80 \ diff --git a/docs/environment-variable.md b/docs/environment-variable.md index ab841af..8b52806 100644 --- a/docs/environment-variable.md +++ b/docs/environment-variable.md @@ -19,6 +19,9 @@ sidebar_position: 12 | HAPROXY_STATS_PORT | (Optional) The HAProxy port to the statistics. If set to `false`, disable statistics | `1936` | | HAPROXY_CUSTOMERRORS | (Optional) If HAProxy will use custom HTML errors. true/false. | `false` | +:::note ACME/Certbot Environment Variables +For ACME/Certbot configuration (Let's Encrypt, ZeroSSL, etc.), see the [ACME documentation](acme.md#environment-variables) for the complete list of `EASYHAPROXY_CERTBOT_*` variables. +::: ---- [Open source ByJG](http://opensource.byjg.com) diff --git a/docs/helm.md b/docs/helm.md index 9a9b28a..9e61d5e 100644 --- a/docs/helm.md +++ b/docs/helm.md @@ -10,9 +10,11 @@ Helm is a package manager for Kubernetes. It allows you to install and manage ap ### 1) Identify the node where your EasyHAProxy container will run -EasyHAProxy will be limited to a single node. To understand that see [limitations](limitations.md) page. +:::warning Single Node Deployment +EasyHAProxy will be limited to a single node. To understand why, see the [limitations](limitations.md) page. +::: -```bash +```bash title="List available nodes" $ kubectl get nodes NAME STATUS ROLES AGE VERSION @@ -22,15 +24,15 @@ node-02 Ready 561d v1.21.13-3 Add the EasyHAProxy label to the node. -```bash +```bash title="Label the node for EasyHAProxy" kubectl label nodes node-01 "easyhaproxy/node=master" ``` ### 2) Install EasyHAProxy -Minimal configuration +Minimal configuration: -```bash +```bash title="Install with Helm (minimal)" helm repo add byjg https://opensource.byjg.com/helm helm repo update byjg kubectl create namespace easyhaproxy @@ -43,7 +45,7 @@ helm upgrade --install ingress byjg/easyhaproxy \ Customizing Helm Values: -```yaml +```yaml title="values.yaml" easyhaproxy: stats: username: admin diff --git a/docs/kubernetes.md b/docs/kubernetes.md index 3bc9e71..a8921ed 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -6,9 +6,11 @@ sidebar_position: 1 ## Setup Kubernetes EasyHAProxy -EasyHAProxy for Kubernetes operates by querying all ingress definitions with the annotation -`kubernetes.io/ingress.class: easyhaproxy-ingress`. Upon finding this annotation, +:::info How it works +EasyHAProxy for Kubernetes operates by querying all ingress definitions with the annotation +`kubernetes.io/ingress.class: easyhaproxy-ingress`. Upon finding this annotation, EasyHAProxy immediately sets up HAProxy and begins serving traffic. +::: For Kubernetes installations, there are three available installation modes: - DaemonSet: This mode exposes ports 80, 443, and 1936. @@ -21,9 +23,11 @@ To install EasyHAProxy in your Kubernetes cluster, follow these steps: ### 1) Identify the node where your EasyHAProxy container will run -EasyHAProxy will be limited to a single node. To understand that see [limitations](limitations.md) page. +:::warning Single Node Deployment +EasyHAProxy will be limited to a single node. To understand why, see the [limitations](limitations.md) page. +::: -```bash +```bash title="List available nodes" $ kubectl get nodes NAME STATUS ROLES AGE VERSION @@ -33,13 +37,13 @@ node-02 Ready 561d v1.21.13-3 Add the EasyHAProxy label to the node. -```bash +```bash title="Label the node for EasyHAProxy" kubectl label nodes node-01 "easyhaproxy/node=master" ``` ### 2) Install EasyHAProxy with Kubernetes Manifest -```bash +```bash title="Install EasyHAProxy" kubectl create namespace easyhaproxy kubectl apply -f \ @@ -78,11 +82,11 @@ Once the container is running, EasyHAProxy will detect automatically and start t You don't need to expose any port in your container. -Notes: - -- At this point, the implementation doesn't support all ingress properties or wildcard domains. -- The ingress will publish the ports 80 and 443, plus 1936 if stats are enabled. -- EasyHAProxy will read all `spec.rules[].host` spec, however it will parse only the first path `spec.rules[].http.paths[0].port.number` for each rule, and ignore the other paths. +:::note Important Limitations +- The implementation doesn't support all ingress properties or wildcard domains at this time. +- The ingress will publish ports 80 and 443, plus 1936 if stats are enabled. +- EasyHAProxy will read all `spec.rules[].host` specifications, however it will parse only the **first path** `spec.rules[].http.paths[0].port.number` for each rule, and ignore the other paths. +::: ## Kubernetes annotations diff --git a/docs/limitations.md b/docs/limitations.md index da77984..53c2549 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -6,25 +6,33 @@ sidebar_position: 15 ## EasyHAProxy will not work with --network=host -The --network=host option cannot be used with EasyHAProxy due to its networking requirements. -EasyHAProxy needs to inspect and interact with Docker containers from within the Docker network -where it's running. Using the --network=host option bypasses Docker networking, -preventing EasyHAProxy from accessing and configuring containers effectively. +:::danger Network Mode Incompatibility +The `--network=host` option **cannot** be used with EasyHAProxy due to its networking requirements. + +EasyHAProxy needs to inspect and interact with Docker containers from within the Docker network where it's running. Using the `--network=host` option bypasses Docker networking, preventing EasyHAProxy from accessing and configuring containers effectively. +::: ## Considerations for Multiple Replica Deployments in EasyHAProxy -EasyHAProxy currently operates under the assumption of a single replica deployment. +:::warning Single Replica Deployment Recommended +EasyHAProxy is designed for single replica deployment. +::: + +### What happens with multiple replicas? + +EasyHAProxy can still operate with multiple replicas; however: + +1. **Service Discovery**: Each replica will independently discover services, which may lead to temporary inconsistencies among replicas (out-of-sync for a few seconds). -In the event of multiple replicas, EasyHAProxy can still operate; however, each replica will independently -discover services. This may lead to temporary inconsistencies among replicas as they may be out-of-sync -for a few seconds due to separate service discovery processes. +2. **ACME/Certificate Issues**: Running multiple replicas creates significant problems with Let's Encrypt and other ACME certificate issuance: + - Each replica will attempt to obtain its own certificate + - ACME challenges may be directed to different replicas, causing failures + - You may quickly hit certificate issuance rate limits + - Certificate renewal may fail unpredictably -However, it's crucial to highlight that running multiple replicas of EasyHAProxy can significantly -impact Letsencrypt certificate issuance. Each replica will possess its own Letsencrypt certificate, -potentially leading to challenges with certificate issuance. Challenges may be directed to different replicas, -leading to potential failures in issuing new certificates and encountering certificate issuance limits. -Therefore, if you intend to run multiple replicas, it's advised to avoid activating Letsencrypt to mitigate -these issues. +:::danger Recommendation +If you need to run multiple replicas for high availability, **do not activate ACME/Let's Encrypt**. Instead, use manually managed certificates or an external certificate management solution. +::: ---- [Open source ByJG](http://opensource.byjg.com) \ No newline at end of file diff --git a/docs/microk8s.md b/docs/microk8s.md index 2d5c9ad..316cf1a 100644 --- a/docs/microk8s.md +++ b/docs/microk8s.md @@ -13,9 +13,9 @@ Here are the steps to install EasyHAProxy on your Microk8s. EasyHAProxy is being part of official MicroK8s Community edition since MicroK8s version 1.27. -Just enable the community add-on +Just enable the community add-on: -``` +```bash title="Enable community addons" microk8s enable community ``` @@ -34,7 +34,7 @@ addons: However, if you are using MicroK8s before 1.27 you need to enable it directly from the ByJG repository by accessing the microk8s host machine and run: -```shell +```bash title="Add ByJG addon repository" microk8s addons repo add byjg https://github.com/byjg/microk8s-addons.git ``` @@ -58,19 +58,21 @@ Once you have enable the EasyHAProxy from the community repository or from ByJG Usage: -Install as a Daemonset +Install as a Daemonset: -```shell +```bash title="Install as DaemonSet" microk8s enable easyhaproxy ``` -Install as a NodePort +Install as a NodePort: -```shell +```bash title="Install as NodePort" microk8s enable easyhaproxy --nodeport ``` -**Remember**: you need to disable any ingress controller you have previously installed, for example, nginx, traefik, etc. before install EasyHaProxy. +:::warning Disable Other Ingress Controllers +You need to disable any ingress controller you have previously installed (e.g., nginx, traefik, etc.) before installing EasyHAProxy to avoid conflicts. +::: For more parameters you can refer to the [Kubernetes](kubernetes.md) page. diff --git a/docs/other.md b/docs/other.md index 6466a0a..f376e13 100644 --- a/docs/other.md +++ b/docs/other.md @@ -12,9 +12,9 @@ Some ports on the EasyHAProxy container and in the firewall are required to be o - If you enable the HAProxy statistics, you must also expose the port defined in `HAPROXY_STATS_PORT` environment variable (default 1936). Be aware that statistics are enabled by default with no password. - Every port defined in `easyhaproxy.[definitions].port` also should be exposed. -e.g. +For example: -```bash +```bash title="Expose required ports" docker run \ /* other parameters */ -p 80:80 \ @@ -27,7 +27,7 @@ docker run \ The docker volume or a way to call the API needs to pass to the EasyHAProxy container. -```bash +```bash title="Mount Docker socket" docker run \ /* other parameters */ -v /var/run/docker.sock:/var/run/docker.sock \ @@ -38,7 +38,7 @@ docker run \ You can concatenate valid HAProxy `.cfg` files to the dynamically generated `haproxy.cfg` by mapping the folder `/etc/haproxy/conf.d`. -```bash +```bash title="Mount custom config directory" docker run \ /* other parameters */ -v /your/local/conf.d:/etc/haproxy/conf.d \ diff --git a/docs/ssl.md b/docs/ssl.md index d4c13a3..0c50b01 100644 --- a/docs/ssl.md +++ b/docs/ssl.md @@ -13,9 +13,9 @@ There are two ways to do that. ## Setup certificate as a label definition in docker container -1. Create a single PEM from the certificate and key. +1. Create a single PEM from the certificate and key. -```bash +```bash title="Combine certificate and key" cat example.com.crt example.com.key > single.pem cat single.pem @@ -33,7 +33,7 @@ MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL 2. Convert the `single.pem` to BASE64 in a single line: -```bash +```bash title="Convert to BASE64" cat single.pem | base64 -w0 ``` @@ -47,7 +47,7 @@ EasyHAProxy stores the certificates inside the container folder `/certs/haproxy` 1. Run EasyHAProxy with the volume for the certificates: -```bash +```bash title="Create and mount certificate volume" docker volume create certs_haproxy docker run \ @@ -58,7 +58,7 @@ docker run \ 2. Create a single PEM from the certificate and the key. -```bash +```bash title="Combine certificate and key" cat example.com.crt example.com.key > single.pem cat single.pem @@ -74,9 +74,9 @@ MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL -----END PRIVATE KEY----- ``` -3. Copy this certificate to EasyHAProxy volume +3. Copy this certificate to EasyHAProxy volume: -```bash +```bash title="Copy certificate to container" docker cp single.pem easyhaproxy:/certs/haproxy ``` diff --git a/docs/static.md b/docs/static.md index ab03363..11189f0 100644 --- a/docs/static.md +++ b/docs/static.md @@ -10,9 +10,11 @@ This method will use a static configuration, which is simpler and easier than cr You can use this configuration to set up external servers unrelated to docker or Kubernetes. -Another advantage is that EasyHAProxy will monitor for changes in this file and automatically reconfigure HAProxy when any changes are detected. +:::tip Live Reload +EasyHAProxy monitors this file for changes and automatically reconfigures HAProxy when any changes are detected. +::: -First, Create a YAML: +First, create a YAML configuration: ```yaml stats: @@ -60,9 +62,9 @@ easymapping: - domain:8181 ``` -Then map this file to `/etc/haproxy/static/config.yml` in your EasyHAProxy container as: +Then map this file to `/etc/haproxy/static/config.yml` in your EasyHAProxy container: -```bash +```bash title="Run EasyHAProxy with static configuration" docker run -d \ --name easy-haproxy-container \ -v /var/run/docker.sock:/var/run/docker.sock \ @@ -119,8 +121,9 @@ easymapping: www.host1.com.br: http://host1.com.br ``` -**Note**: The only way to pass SSL certificates in the static configuration file is to map the certificates -to EasyHAProxy as a docker volume. Refer to the [SSL documentation](ssl.md) to learn how to do it. +:::note SSL Certificates in Static Mode +The only way to provide SSL certificates in static configuration mode is to map the certificates to EasyHAProxy as a docker volume. Refer to the [SSL documentation](ssl.md) to learn how to configure this. +::: ---- [Open source ByJG](http://opensource.byjg.com) diff --git a/docs/swarm.md b/docs/swarm.md index ec93886..9a133c8 100644 --- a/docs/swarm.md +++ b/docs/swarm.md @@ -10,21 +10,21 @@ This method involves using a Docker Swarm installation to discover containers an EasyHAProxy inspects Docker containers within the Swarm and retrieves labels to configure HAProxy. Once it identifies a container with at least the label 'easyhaproxy.http.host,' it configures HAProxy to redirect traffic to that container. To accomplish this, EasyHAProxy may need to attach the same network to its container. -Utilizing Docker Swarm offers several advantages, including: - - Container Discovery: Docker Swarm facilitates the discovery of containers within the cluster, - streamlining the process of identifying services for HAProxy configuration. - - Remote Node Management: Docker Swarm allows for the management of containers across multiple nodes, - providing flexibility and scalability in deploying services while ensuring seamless HAProxy configuration across the cluster. +:::tip Docker Swarm Advantages +- **Container Discovery**: Docker Swarm facilitates the discovery of containers within the cluster, streamlining the process of identifying services for HAProxy configuration. +- **Remote Node Management**: Docker Swarm allows for the management of containers across multiple nodes, providing flexibility and scalability in deploying services while ensuring seamless HAProxy configuration across the cluster. +::: It's recommended to create a network external to EasyHAProxy. -Limitations: - - You cannot mix Docker containers with Swarm containers. - - This method does not work with containers that use the '--network=host' option. (see [limitations](limitations.md)) +:::warning Limitations +- You cannot mix Docker containers with Swarm containers. +- This method does not work with containers that use the `--network=host` option. See [limitations](limitations.md) for details. +::: -e.g.: +For example: -```bash +```bash title="Create overlay network" docker network create -d overlay --attachable easyhaproxy ``` @@ -59,15 +59,17 @@ networks: external: true ``` -And then: +Deploy the stack: -```bash +```bash title="Deploy EasyHAProxy stack" docker stack deploy --compose-file docker-compose.yml easyhaproxy ``` Mapping to `/var/run/docker.sock` is necessary to discover the docker containers and get the labels; -**Do not** add more than one replica for EasyHAProxy. To understand that see [limitations](limitations.md) page. +:::danger Single Replica Only +**Do not** add more than one replica for EasyHAProxy. To understand why, see the [limitations](limitations.md) page. +::: ## Running containers diff --git a/docs/volumes.md b/docs/volumes.md index 945ef17..c738523 100644 --- a/docs/volumes.md +++ b/docs/volumes.md @@ -4,6 +4,10 @@ sidebar_position: 13 # Volumes +:::info Volume Mapping +These volumes allow you to persist certificates, provide custom configurations, and extend EasyHAProxy functionality. +::: + You can map the following volumes: | Volume | Description | From facbaaabb6ce463b017d73943bace9174285d23b Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Mon, 10 Nov 2025 16:36:05 -0500 Subject: [PATCH 3/3] Update documentation and examples - Improved container labels documentation formatting and fixed typos. - Clarified static discovery mode requirements in static.md. - Updated Kubernetes annotations explanations. - Enhanced README.md with details about supported platforms and features. - Bumped Swarm example image to version 4.6.0. --- README.md | 11 ++++++----- docs/container-labels.md | 8 ++++---- docs/kubernetes.md | 4 ++-- docs/static.md | 7 +++++-- docs/swarm.md | 2 +- 5 files changed, 18 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a74c2af..e5b916a 100644 --- a/README.md +++ b/README.md @@ -11,18 +11,19 @@ ## Service discovery for HAProxy -EasyHAProxy dynamically creates the `haproxy.cfg` based on the labels defined in docker containers. +EasyHAProxy dynamically creates the `haproxy.cfg` based on metadata collected from your workloads (Docker labels, Swarm service labels, or Kubernetes ingress annotations). EasyHAProxy can detect and configure HAProxy automatically on the following platforms: - Docker - Docker Swarm - Kubernetes +- Static YAML definitions (`EASYHAPROXY_DISCOVER=static`) ## Who is using? EasyHAProxy is part of some projects: -- Dokku +- Dokku - MicroK8s - DigitalOcean Marketplace @@ -34,12 +35,12 @@ Easy to set up and low configuration to numerous features. ## Features -EasyHAProxy will discover the services based on the Docker Tags of the containers running on a Docker host or Docker Swarm cluster and dynamically set up the `haproxy.cfg`. Below, EasyHAProxy main features: +EasyHAProxy will discover services based on Docker (or Swarm) labels and Kubernetes ingress annotations, then dynamically build the `haproxy.cfg`. Below, EasyHAProxy main features: -- Support Automatic Certificate Management Environment (ACME) protocol compatible with Let's encrypt and others CA. +- Support Automatic Certificate Management Environment (ACME) protocol compatible with Let's Encrypt and other CAs. - Set your custom SSL certificates - Balance traffic between multiple replicas -- Set SSL with three different levels of validations and according to the most recent definitions. +- Set SSL policies (`strict`, `default`, `loose`) via `EASYHAPROXY_SSL_MODE`. - Set up HAProxy to listen to TCP. - Add redirects. - Enable/disable Stats on port 1936 with a custom password. diff --git a/docs/container-labels.md b/docs/container-labels.md index ae05902..9b9bfe2 100644 --- a/docs/container-labels.md +++ b/docs/container-labels.md @@ -6,7 +6,7 @@ sidebar_position: 11 ## Container (Docker or Swarm) labels -| Tag | Description | Default | Example | +| 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 | @@ -18,7 +18,7 @@ sidebar_position: 11 | 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](acme.md). | 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].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](https://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4.2-balance) | roundrobin | roundrobin, source, uri, url_param, hdr, rdp-cookie, leastconn, first, static-rr, rdp-cookie, hdr_dom, map-based | :::info Understanding Definitions @@ -27,7 +27,7 @@ The `[definition]` is a string identifier that groups related configuration labe A single container can have multiple definitions to expose different services or ports. ::: -## Configuations +## Configurations ### Single Definition @@ -101,4 +101,4 @@ docker run \ ``` ---- -[Open source ByJG](http://opensource.byjg.com) \ No newline at end of file +[Open source ByJG](http://opensource.byjg.com) diff --git a/docs/kubernetes.md b/docs/kubernetes.md index a8921ed..c4b8b67 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -97,7 +97,7 @@ You don't need to expose any port in your container. | easyhaproxy.certbot | (optional) Boolean. It will request certbot certificates for the ingresses 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) Set the an additional port for that ingress | http | http or tcp | +| easyhaproxy.listen_port | (optional) Override the HTTP listen port created for that ingress | 80 | 8081 | **Important**: The annotations are per ingress and applied to all hosts in that ingress configuration. @@ -155,4 +155,4 @@ spec: ``` ---- -[Open source ByJG](http://opensource.byjg.com) \ No newline at end of file +[Open source ByJG](http://opensource.byjg.com) diff --git a/docs/static.md b/docs/static.md index 11189f0..f81077c 100644 --- a/docs/static.md +++ b/docs/static.md @@ -67,7 +67,6 @@ Then map this file to `/etc/haproxy/static/config.yml` in your EasyHAProxy conta ```bash title="Run EasyHAProxy with static configuration" docker run -d \ --name easy-haproxy-container \ - -v /var/run/docker.sock:/var/run/docker.sock \ -v /my/static/:/etc/haproxy/static/ \ -e EASYHAPROXY_DISCOVER="static" \ # + Environment Variables \ @@ -78,7 +77,11 @@ docker run -d \ byjg/easy-haproxy ``` -You can find other informations on [docker label configuration](container-labels.md) and [environment variable guide](environment-variable.md) +:::tip Docker Socket Optional +Mounting `/var/run/docker.sock` is not required in static discovery mode. Add it only if you are simultaneously discovering Docker containers. +::: + +You can find other information on [docker label configuration](container-labels.md) and [environment variable guide](environment-variable.md) ## Yaml Definition diff --git a/docs/swarm.md b/docs/swarm.md index 9a133c8..348224e 100644 --- a/docs/swarm.md +++ b/docs/swarm.md @@ -35,7 +35,7 @@ version: "3" services: haproxy: - image: byjg/easy-haproxy:4.3.1-rc1 + image: byjg/easy-haproxy:4.6.0 volumes: - /var/run/docker.sock:/var/run/docker.sock deploy: