Audit and organize Docusaurus documentation structure

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.
@@ -80,6 +81,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)

docs/acme.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 10
+---
+
 # SSL - Automatic Certificate Management Environment (ACME)
 
 The Automatic Certificate Management Environment (ACME) protocol 
@@ -13,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
 
@@ -69,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)                                                                         |
@@ -104,16 +110,18 @@ docker run \
     byjg/easy-haproxy
 ```
 
-Notes:
-
-- 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/)
+:::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/)
+:::
 
-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:
 
@@ -134,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)

docs/container-labels.md

@@ -1,8 +1,12 @@
+---
+sidebar_position: 11
+---
+
 # Container Labels
 
 ## 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                                                                                                      |
@@ -14,27 +18,29 @@
 | 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 |
 
-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
+## Configurations
 
 ### 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 \
@@ -47,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 \
@@ -76,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
@@ -89,10 +95,10 @@ 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"}'
 ```
 
 ----
-[Open source ByJG](http://opensource.byjg.com)
+[Open source ByJG](http://opensource.byjg.com)

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.

docs/docker.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 3
+---
+
 # Docker
 
 ## Setup Docker EasyHAProxy
@@ -12,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 \
@@ -41,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 \

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.

docs/environment-variable.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 12
+---
+
 # Docker environment variables
 
 | Environment Variable     | Description                                                                                                                                                                                    | Default       |
@@ -15,6 +19,9 @@
 | 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)

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.
@@ -6,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
@@ -18,15 +24,15 @@ node-02   Ready    <none>   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
@@ -39,7 +45,7 @@ helm upgrade --install ingress byjg/easyhaproxy \
 
 Customizing Helm Values:
 
-```yaml
+```yaml title="values.yaml"
 easyhaproxy:
   stats:
     username: admin