Add environment variable documentation for all plugins, reorganize plugin files for consistency

- Introduced environment variable support in documentation for Cloudflare, Cleanup, Deny Pages, IP Whitelist, JWT Validator, and FastCGI plugins. - Updated plugin files with consistent headings, examples, and tables for easier configuration reference. - Adjusted `README.md` and `plugins.md` to reflect updated plugin paths and environment variable usage.
2025-12-02 11:47:19 -05:00 · 2025-12-02 11:47:19 -05:00 · 50ffb4fe16
commit 50ffb4fe16
parent b4944ac544
8 changed files with 122 additions and 29 deletions
--- a/README.md
+++ b/README.md
@ -89,12 +89,12 @@ Detailed configuration guides for advanced setups:
 - [Environment Variables](docs/environment-variable.md) - Configure EasyHAProxy behavior
 - [Volumes](docs/volumes.md) - Map volumes for certificates, config, and custom files
 - [Plugins](docs/plugins.md) - Extend HAProxy with plugins ([Development Guide](docs/plugin-development.md))
-  - [Cloudflare](docs/plugins/cloudflare.md) - Restore visitor IP from Cloudflare CDN
-  - [Cleanup](docs/plugins/cleanup.md) - Automatic cleanup of temporary files
-  - [Deny Pages](docs/plugins/deny-pages.md) - Block access to specific paths
-  - [IP Whitelist](docs/plugins/ip-whitelist.md) - Restrict access to IPs/CIDR ranges
-  - [JWT Validator](docs/plugins/jwt-validator.md) - JWT authentication validation
-  - [FastCGI](docs/plugins/fastcgi.md) - PHP-FPM and FastCGI application support
+  - [JWT Validator](docs/Plugins/jwt-validator.md) - JWT authentication validation
+  - [FastCGI](docs/Plugins/fastcgi.md) - PHP-FPM and FastCGI application support
+  - [Cloudflare](docs/Plugins/cloudflare.md) - Restore visitor IP from Cloudflare CDN
+  - [IP Whitelist](docs/Plugins/ip-whitelist.md) - Restrict access to IPs/CIDR ranges
+  - [Deny Pages](docs/Plugins/deny-pages.md) - Block access to specific paths
+  - [Cleanup](docs/Plugins/cleanup.md) - Automatic cleanup of temporary files
 - [Other Configurations](docs/other.md) - Additional configurations (ports, custom errors, etc.)
 - [Limitations](docs/limitations.md) - Important limitations and considerations

--- a/docs/Plugins/cleanup.md
+++ b/docs/Plugins/cleanup.md
@ -39,10 +39,16 @@ plugins:

 ### Environment Variables

-```bash
-EASYHAPROXY_PLUGINS_ENABLED=cleanup
-EASYHAPROXY_PLUGIN_CLEANUP_MAX_IDLE_TIME=600
-```
+Configure the Cleanup plugin globally:
+
+| Environment Variable                            | Config Key           | Type     | Default | Description                                  |
+|-------------------------------------------------|----------------------|----------|---------|----------------------------------------------|
+| `EASYHAPROXY_PLUGINS_ENABLED`                   | -                    | string   | -       | Enable cleanup plugin (value: `cleanup`)     |
+| `EASYHAPROXY_PLUGIN_CLEANUP_ENABLED`            | `enabled`            | boolean  | `true`  | Enable/disable plugin                        |
+| `EASYHAPROXY_PLUGIN_CLEANUP_MAX_IDLE_TIME`      | `max_idle_time`      | integer  | `300`   | Maximum age in seconds before deleting files |
+| `EASYHAPROXY_PLUGIN_CLEANUP_CLEANUP_TEMP_FILES` | `cleanup_temp_files` | boolean  | `true`  | Enable temp file cleanup                     |
+
+**Note:** This is a global plugin - configuration applies to the entire system.

 ### Custom Idle Time (1 hour)

--- a/docs/Plugins/cloudflare.md
+++ b/docs/Plugins/cloudflare.md
@ -80,6 +80,18 @@ plugins:
      use_builtin_ips: true  # Uses built-in Cloudflare IPs (default)
 ```

+### Environment Variables
+
+Configure Cloudflare plugin defaults for all domains:
+
+| Environment Variable                            | Config Key        | Type     | Default                           | Description                           |
+|-------------------------------------------------|-------------------|----------|-----------------------------------|---------------------------------------|
+| `EASYHAPROXY_PLUGIN_CLOUDFLARE_ENABLED`         | `enabled`         | boolean  | `true`                            | Enable/disable plugin for all domains |
+| `EASYHAPROXY_PLUGIN_CLOUDFLARE_USE_BUILTIN_IPS` | `use_builtin_ips` | boolean  | `true`                            | Use built-in Cloudflare IP ranges     |
+| `EASYHAPROXY_PLUGIN_CLOUDFLARE_IP_LIST_PATH`    | `ip_list_path`    | string   | `/etc/haproxy/cloudflare_ips.lst` | Path to Cloudflare IP list file       |
+
+**Note:** Environment variables set defaults for ALL domains. To enable/disable per-domain, use container labels or Kubernetes annotations.
+
 ## Generated HAProxy Configuration

 ```haproxy
--- a/docs/Plugins/deny-pages.md
+++ b/docs/Plugins/deny-pages.md
@ -96,6 +96,18 @@ labels:
  easyhaproxy.http.plugin.deny_pages.status_code: 403
 ```

+### Environment Variables
+
+Configure Deny Pages plugin defaults for all domains:
+
+| Environment Variable                        | Config Key    | Type    | Default | Description                            |
+|---------------------------------------------|---------------|---------|---------|----------------------------------------|
+| `EASYHAPROXY_PLUGIN_DENY_PAGES_ENABLED`     | `enabled`     | boolean | `true`  | Enable/disable plugin for all domains  |
+| `EASYHAPROXY_PLUGIN_DENY_PAGES_PATHS`       | `paths`       | string  | -       | Comma-separated list of paths to block |
+| `EASYHAPROXY_PLUGIN_DENY_PAGES_STATUS_CODE` | `status_code` | integer | `403`   | HTTP status code to return             |
+
+**Note:** Environment variables set defaults for ALL domains. To configure per-domain, use container labels or Kubernetes annotations.
+
 ## Generated HAProxy Configuration

 ```haproxy
--- a/docs/Plugins/fastcgi.md
+++ b/docs/Plugins/fastcgi.md
@ -115,6 +115,20 @@ easymapping:
        path_info: true
 ```

+### Environment Variables
+
+Configure FastCGI plugin defaults for all domains:
+
+| Environment Variable                         | Config Key        | Type     | Default         | Description                           |
+|----------------------------------------------|-------------------|----------|-----------------|---------------------------------------|
+| `EASYHAPROXY_PLUGIN_FASTCGI_ENABLED`         | `enabled`         | boolean  | `true`          | Enable/disable plugin for all domains |
+| `EASYHAPROXY_PLUGIN_FASTCGI_DOCUMENT_ROOT`   | `document_root`   | string   | `/var/www/html` | Document root path                    |
+| `EASYHAPROXY_PLUGIN_FASTCGI_SCRIPT_FILENAME` | `script_filename` | string   | `%[path]`       | Custom pattern for SCRIPT_FILENAME    |
+| `EASYHAPROXY_PLUGIN_FASTCGI_INDEX_FILE`      | `index_file`      | string   | `index.php`     | Default index file                    |
+| `EASYHAPROXY_PLUGIN_FASTCGI_PATH_INFO`       | `path_info`       | boolean  | `true`          | Enable PATH_INFO support              |
+
+**Note:** Environment variables set defaults for ALL domains. To configure per-domain, use container labels or Kubernetes annotations. Custom params (`custom_params`) cannot be configured via environment variables - use YAML or labels instead.
+
 ## Generated HAProxy Configuration

 The plugin generates a top-level `fcgi-app` section and a `use-fcgi-app` directive in the backend:
--- a/docs/Plugins/ip-whitelist.md
+++ b/docs/Plugins/ip-whitelist.md
@ -85,6 +85,18 @@ easymapping:
        status_code: 403
 ```

+### Environment Variables
+
+Configure IP Whitelist plugin defaults for all domains:
+
+| Environment Variable                          | Config Key    | Type     | Default | Description                                      |
+|-----------------------------------------------|---------------|----------|---------|--------------------------------------------------|
+| `EASYHAPROXY_PLUGIN_IP_WHITELIST_ENABLED`     | `enabled`     | boolean  | `true`  | Enable/disable plugin for all domains            |
+| `EASYHAPROXY_PLUGIN_IP_WHITELIST_ALLOWED_IPS` | `allowed_ips` | string   | -       | Comma-separated list of IPs/CIDR ranges to allow |
+| `EASYHAPROXY_PLUGIN_IP_WHITELIST_STATUS_CODE` | `status_code` | integer  | `403`   | HTTP status code to return for blocked IPs       |
+
+**Note:** Environment variables set defaults for ALL domains. To configure per-domain, use container labels or Kubernetes annotations.
+
 ## Generated HAProxy Configuration

 ```haproxy
--- a/docs/Plugins/jwt-validator.md
+++ b/docs/Plugins/jwt-validator.md
@ -157,6 +157,24 @@ easymapping:
        pubkey_path: /etc/haproxy/jwt_keys/api_pubkey.pem
 ```

+### Environment Variables
+
+Configure JWT Validator plugin defaults for all domains:
+
+| Environment Variable                               | Config Key        | Type    | Default | Description                                 |
+|----------------------------------------------------|-------------------|---------|---------|---------------------------------------------|
+| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ENABLED`         | `enabled`         | boolean | `true`  | Enable/disable plugin for all domains       |
+| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ALGORITHM`       | `algorithm`       | string  | `RS256` | JWT signing algorithm                       |
+| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ISSUER`          | `issuer`          | string  | -       | Expected JWT issuer (optional)              |
+| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_AUDIENCE`        | `audience`        | string  | -       | Expected JWT audience (optional)            |
+| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PUBKEY_PATH`     | `pubkey_path`     | string  | -       | Path to public key file                     |
+| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PUBKEY`          | `pubkey`          | string  | -       | Public key as base64-encoded string         |
+| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PATHS`           | `paths`           | string  | -       | Comma-separated paths requiring JWT         |
+| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ONLY_PATHS`      | `only_paths`      | boolean | `false` | If true, only specified paths accessible    |
+| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ALLOW_ANONYMOUS` | `allow_anonymous` | boolean | `false` | Allow requests without Authorization header |
+
+**Note:** Environment variables set defaults for ALL domains. To configure per-domain, use container labels or Kubernetes annotations.
+
 ## Generated HAProxy Configuration

 ### All Paths Protected
--- a/docs/plugins.md
+++ b/docs/plugins.md
@ -44,12 +44,12 @@ Execute **once for each discovered domain/host**.

 EasyHAProxy includes several built-in plugins ready to use:

- [Cloudflare](plugins/cloudflare.md) - Restore visitor IP from Cloudflare CDN
- [Cleanup](plugins/cleanup.md) - Cleanup temporary files
- [Deny Pages](plugins/deny-pages.md) - Block specific paths
- [IP Whitelist](plugins/ip-whitelist.md) - Restrict access to IPs/CIDR ranges
- [JWT Validator](plugins/jwt-validator.md) - Validate JWT tokens
- [FastCGI](plugins/fastcgi.md) - Configure PHP-FPM and FastCGI applications
+- [Cloudflare](Plugins/cloudflare.md) - Restore visitor IP from Cloudflare CDN
+- [Cleanup](Plugins/cleanup.md) - Cleanup temporary files
+- [Deny Pages](Plugins/deny-pages.md) - Block specific paths
+- [IP Whitelist](Plugins/ip-whitelist.md) - Restrict access to IPs/CIDR ranges
+- [JWT Validator](Plugins/jwt-validator.md) - Validate JWT tokens
+- [FastCGI](Plugins/fastcgi.md) - Configure PHP-FPM and FastCGI applications

 ## Configuration Methods

@ -124,49 +124,68 @@ services:

 ### 3. Static YAML Configuration

-Configure plugins globally in `/etc/haproxy/static/config.yaml`:
+Configure plugins in `/etc/haproxy/static/config.yaml`:

 ```yaml
 plugins:
  # Global settings
  abort_on_error: false  # Log and continue on errors (recommended)

-  # Enable global plugins
+  # Enable GLOBAL plugins (run once per discovery cycle)
  enabled: [cleanup]

-  # Configure individual plugins
+  # Configure plugins (both global and domain plugins)
  config:
-    cloudflare:
-      enabled: true
-      ip_list_path: /etc/haproxy/cloudflare_ips.lst
-
+    # Global plugin configuration (cleanup runs once per cycle)
    cleanup:
      enabled: true
      max_idle_time: 600

+    # Domain plugin configuration (applies to ALL domains by default)
+    cloudflare:
+      enabled: true           # Apply to all domains
+      use_builtin_ips: true   # Use built-in Cloudflare IPs
+
+    # Domain plugin disabled by default (enable per-domain via labels/annotations)
    deny_pages:
-      enabled: false  # Disable globally, enable per-container via labels
+      enabled: false
 ```

+**Important distinctions:**
+
+- **Global plugins** (like `cleanup`): Run once per discovery cycle, configured here only
+- **Domain plugins** (like `cloudflare`, `deny_pages`, `jwt_validator`):
+  - Configuration here sets **defaults for ALL domains**
+  - Can be enabled/disabled per-domain via container labels or Kubernetes annotations
+  - Per-domain configuration overrides these defaults
+
 ### 4. Environment Variables

-Configure plugins via environment variables:
+Configure plugins via environment variables. **Note:** Environment variables set system-wide defaults and cannot configure plugins per-domain.

 ```bash
-# Global settings
+# Enable GLOBAL plugins (run once per discovery cycle)
 EASYHAPROXY_PLUGINS_ENABLED=cleanup
 EASYHAPROXY_PLUGINS_ABORT_ON_ERROR=false

-# Plugin-specific configuration
+# Configure GLOBAL plugins
 EASYHAPROXY_PLUGIN_CLEANUP_ENABLED=true
 EASYHAPROXY_PLUGIN_CLEANUP_MAX_IDLE_TIME=600
-EASYHAPROXY_PLUGIN_CLOUDFLARE_IP_LIST_PATH=/etc/haproxy/cloudflare_ips.lst
+
+# Configure DOMAIN plugins (sets defaults for ALL domains)
+EASYHAPROXY_PLUGIN_CLOUDFLARE_ENABLED=true
+EASYHAPROXY_PLUGIN_CLOUDFLARE_USE_BUILTIN_IPS=true
 ```

 **Variable format:**
- Enable plugins: `EASYHAPROXY_PLUGINS_ENABLED=plugin1,plugin2`
+- Enable global plugins: `EASYHAPROXY_PLUGINS_ENABLED=plugin1,plugin2`
 - Configure plugin: `EASYHAPROXY_PLUGIN_<PLUGIN_NAME>_<CONFIG_KEY>=value`

+**Scope limitations:**
+- **Global plugins**: Environment variables configure the single instance
+- **Domain plugins**: Environment variables set defaults for ALL domains
+- **Per-domain configuration**: Use container labels (Docker) or annotations (Kubernetes) instead
+
 ## Common Use Cases

 ### Protect API with JWT Authentication