Implement Plugin System with Built-in Plugins and Comprehensive Examples

.github/workflows/build.yml

@@ -170,6 +170,7 @@ jobs:
             sed -i "s#easy-haproxy:[a-zA-Z0-9\.-]*#easy-haproxy:$TAG#g" deploy/kubernetes/easyhaproxy-*.yml
 
             sed -i "s#easy-haproxy/[a-zA-Z0-9\.-]*/#easy-haproxy/$TAG/#g" docs/kubernetes.md
+            sed -i "s#easy-haproxy:[a-zA-Z0-9\.-]*#easy-haproxy:$TAG#g" docs/swarm.md
             sed -i "s#appVersion: \"[a-zA-Z0-9\.-]*\"#appVersion: \"$TAG\"#g" helm/easyhaproxy/Chart.yaml
 
             find examples -type f -name '*.yml' -exec sed -i "s#\(byjg/easy-haproxy:\)[a-zA-Z0-9\.-]*#\1$TAG#g" {} \; -print

.gitignore

@@ -6,3 +6,12 @@ __pycache__
 .pytest_cache
 *.pyc
 .env
+/examples/static/conf/config.yml
+/examples/docker/certs/haproxy/.place_holder_cert.pem
+/examples/static/host1.local.pem
+/examples/swarm/certs/host1.local.pem
+/examples/docker/host2.local.pem
+/examples/swarm/certs/host2.local.pem
+/examples/docker/jwt_private.pem
+/examples/docker/jwt_pubkey.pem
+/examples/docker/cloudflare_ips.lst

Makefile

@@ -6,4 +6,4 @@ build:
 
 .PHONY: test
 test:
-	pytest tests/
+	cd src/ && pytest tests/ -vv

README.md

@@ -88,6 +88,13 @@ 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
+- [Plugins](docs/plugins.md) - Extend HAProxy with plugins ([Development Guide](docs/plugin-development.md))
+  - [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
 

RELEASE.md

@@ -0,0 +1,350 @@
+# EasyHAProxy Release Guide
+
+This guide explains how to create a new release of EasyHAProxy, including Docker images, Helm charts, and documentation updates.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Release Process](#release-process)
+- [Automated Release (Recommended)](#automated-release-recommended)
+- [Manual Release](#manual-release)
+- [Helm Chart Release](#helm-chart-release)
+- [Post-Release Checklist](#post-release-checklist)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+The EasyHAProxy release process uses GitHub Actions to automatically:
+- Run tests
+- Build multi-architecture Docker images (amd64, arm64)
+- Publish Docker images to Docker Hub
+- Update Helm chart versions
+- Publish Helm charts
+- Update documentation
+
+## Prerequisites
+
+Before creating a release, ensure you have:
+
+1. **Permissions:**
+   - Write access to the GitHub repository
+   - Docker Hub credentials (for maintainers)
+   - Access to GitHub secrets (for CI/CD)
+
+2. **Local Setup:**
+   - Git configured with your credentials
+   - Docker installed (for local testing)
+   - Python 3.x with pytest (for running tests)
+
+3. **Repository Secrets (for maintainers):**
+   - `DOCKER_REGISTRY`: Docker Hub registry URL
+   - `DOCKER_REGISTRY_USER`: Docker Hub username
+   - `DOCKER_REGISTRY_TOKEN`: Docker Hub access token
+   - `DOC_TOKEN`: GitHub token for documentation updates
+
+## Release Process
+
+### Version Numbering
+
+EasyHAProxy follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR.MINOR.PATCH** (e.g., `4.6.0`)
+  - **MAJOR**: Breaking changes or major architectural updates
+  - **MINOR**: New features, plugin additions, backward-compatible changes
+  - **PATCH**: Bug fixes, documentation updates, minor improvements
+
+**Current Version:** `4.6.0` (as of Chart.yaml)
+
+## Automated Release (Recommended)
+
+The automated release process is triggered by pushing a semantic version tag.
+
+### Step 1: Prepare the Release
+
+1. **Ensure all changes are committed and pushed:**
+   ```bash
+   git status
+   git add .
+   git commit -m "Prepare release X.Y.Z"
+   git push origin master
+   ```
+
+2. **Run tests locally:**
+   ```bash
+   cd src/
+   pytest tests/ -vv
+   ```
+
+3. **Build and test Docker image locally:**
+   ```bash
+   make build
+   # Or manually:
+   docker build -t byjg/easy-haproxy:local -f build/Dockerfile .
+   ```
+
+### Step 2: Create and Push a Release Tag
+
+1. **Create a new semantic version tag:**
+   ```bash
+   # For a new minor version (new features)
+   git tag 4.7.0
+
+   # For a patch version (bug fixes)
+   git tag 4.6.1
+
+   # For a major version (breaking changes)
+   git tag 5.0.0
+   ```
+
+2. **Push the tag to GitHub:**
+   ```bash
+   git push origin 4.7.0
+   ```
+
+3. **Monitor the GitHub Actions workflow:**
+   - Go to: https://github.com/byjg/docker-easy-haproxy/actions
+   - Watch the "Docker" workflow progress
+   - Verify all jobs complete successfully:
+     - ✅ Test
+     - ✅ Build (multi-arch)
+     - ✅ Helm
+     - ✅ HelmDeploy
+     - ✅ Documentation
+
+### Step 3: What Happens Automatically
+
+When you push a semantic version tag, GitHub Actions will:
+
+1. **Run Tests** (`Test` job):
+   - Install Python dependencies
+   - Run pytest on all tests
+
+2. **Build Multi-Arch Docker Images** (`Build` job):
+   - Build for `linux/amd64` and `linux/arm64`
+   - Tag image with version number (e.g., `byjg/easy-haproxy:4.7.0`)
+   - Push to Docker Hub
+
+3. **Update Versions** (`Helm` job):
+   - Update `helm/easyhaproxy/Chart.yaml`:
+     - `appVersion`: Set to new version (e.g., `4.7.0`)
+     - `version`: Auto-increment patch version (e.g., `0.1.9` → `0.1.10`)
+   - Update all version references in:
+     - `deploy/docker/docker-compose.yml`
+     - `deploy/kubernetes/easyhaproxy-*.yml`
+     - `docs/kubernetes.md`
+     - `examples/*/*.yml`
+   - Commit and push changes with message: `[skip ci] Update from X.Y.Z to A.B.C`
+
+4. **Publish Helm Chart** (`HelmDeploy` job):
+   - Package Helm chart
+   - Publish to Helm repository at https://opensource.byjg.com/helm/
+
+5. **Update Documentation** (`Documentation` job):
+   - Publish documentation updates
+
+### Step 4: Verify the Release
+
+1. **Check Docker Hub:**
+   ```bash
+   docker pull byjg/easy-haproxy:4.7.0
+   docker images | grep easy-haproxy
+   ```
+
+2. **Verify Helm chart:**
+   ```bash
+   helm repo add byjg https://opensource.byjg.com/helm
+   helm repo update
+   helm search repo easyhaproxy
+   ```
+
+3. **Create GitHub Release:**
+   - Go to: https://github.com/byjg/docker-easy-haproxy/releases/new
+   - Select the tag you created
+   - Generate release notes
+   - Add highlights of changes
+   - Publish release
+
+## Manual Release
+
+For emergency releases or when CI/CD is unavailable.
+
+### Manual Docker Build (Multi-Arch)
+
+1. **Set up environment:**
+   ```bash
+   export DOCKER_USERNAME=your-username
+   export DOCKER_PASSWORD=your-token
+   export DOCKER_REGISTRY=docker.io
+   export VERSIONS="4.7.0"
+   ```
+
+2. **Run multi-arch build:**
+   ```bash
+   ./build-multiarch.sh
+   ```
+
+   This script uses `buildah` and `podman` to create multi-architecture images.
+
+### Manual Helm Chart Update
+
+1. **Update Chart.yaml:**
+   ```bash
+   cd helm/easyhaproxy/
+
+   # Update appVersion
+   sed -i 's/appVersion: ".*"/appVersion: "4.7.0"/' Chart.yaml
+
+   # Increment chart version
+   # From: version: 0.1.9
+   # To:   version: 0.1.10
+   nano Chart.yaml
+   ```
+
+2. **Package and publish Helm chart:**
+   ```bash
+   helm package helm/easyhaproxy/
+   # Follow your Helm repository's publishing process
+   ```
+
+## Helm Chart Release
+
+The Helm chart version is automatically managed by CI/CD, but you can manually control it:
+
+### Helm Chart Version Strategy
+
+- **Chart version** (`version` in Chart.yaml):
+  - Auto-incremented by CI/CD (patch version)
+  - Format: `0.1.X` where X increments with each Docker release
+  - Manual override: Edit Chart.yaml before tagging
+
+- **App version** (`appVersion` in Chart.yaml):
+  - Set to Docker image version (e.g., `4.7.0`)
+  - Automatically updated by CI/CD
+
+### Current Helm Chart
+
+- **Chart Version:** `0.1.9`
+- **App Version:** `4.6.0`
+- **Repository:** https://opensource.byjg.com/helm/
+
+## Post-Release Checklist
+
+After a successful release:
+
+- [ ] Verify Docker image on Docker Hub
+- [ ] Test Docker image: `docker run byjg/easy-haproxy:X.Y.Z --version`
+- [ ] Verify Helm chart availability
+- [ ] Test Helm installation
+- [ ] Create GitHub Release with changelog
+- [ ] Update project README if needed
+- [ ] Announce release (if major/minor)
+- [ ] Update dependent projects (if applicable)
+
+## Troubleshooting
+
+### Build Fails
+
+**Problem:** GitHub Actions build job fails
+
+**Solutions:**
+1. Check test output in GitHub Actions logs
+2. Run tests locally: `cd src/ && pytest tests/ -vv`
+3. Fix failing tests and push changes
+4. Delete and recreate tag:
+   ```bash
+   git tag -d 4.7.0
+   git push origin :refs/tags/4.7.0
+   git tag 4.7.0
+   git push origin 4.7.0
+   ```
+
+### Docker Push Fails
+
+**Problem:** Cannot push to Docker Hub
+
+**Solutions:**
+1. Verify Docker Hub credentials in GitHub secrets
+2. Check Docker Hub token permissions
+3. Ensure image name matches: `byjg/easy-haproxy`
+
+### Helm Chart Not Published
+
+**Problem:** Helm chart doesn't appear in repository
+
+**Solutions:**
+1. Check `HelmDeploy` job logs in GitHub Actions
+2. Verify `DOC_TOKEN` secret is valid
+3. Wait a few minutes for chart to propagate
+4. Clear Helm cache: `helm repo update`
+
+### Version Not Updated
+
+**Problem:** Version references not updated in docs/examples
+
+**Solutions:**
+1. Check `Helm` job logs for sed command errors
+2. Verify commit was pushed with `[skip ci]` message
+3. Manually update version references if needed:
+   ```bash
+   find examples -type f -name '*.yml' -exec sed -i "s/\(byjg\/easy-haproxy:\)[0-9\.]*/\1X.Y.Z/g" {} \;
+   ```
+
+### Multi-Arch Build Issues
+
+**Problem:** ARM64 build fails
+
+**Solutions:**
+1. Verify QEMU is set up in GitHub Actions
+2. Check build logs for architecture-specific errors
+3. Test locally with Docker Buildx:
+   ```bash
+   docker buildx create --use
+   docker buildx build --platform linux/amd64,linux/arm64 -t test .
+   ```
+
+## Quick Reference
+
+### Commands
+
+```bash
+# Local build
+make build
+
+# Run tests
+cd src/ && pytest tests/ -vv
+
+# Create release tag
+git tag 4.7.0 && git push origin 4.7.0
+
+# Pull specific version
+docker pull byjg/easy-haproxy:4.7.0
+
+# Install Helm chart
+helm install easyhaproxy byjg/easyhaproxy --version 0.1.10
+
+# Check Helm chart info
+helm show chart byjg/easyhaproxy
+```
+
+### Important URLs
+
+- **GitHub Repository:** https://github.com/byjg/docker-easy-haproxy
+- **Docker Hub:** https://hub.docker.com/r/byjg/easy-haproxy
+- **Helm Repository:** https://opensource.byjg.com/helm/
+- **Documentation:** https://opensource.byjg.com/devops/docker-easy-haproxy/
+- **GitHub Actions:** https://github.com/byjg/docker-easy-haproxy/actions
+
+### Version History
+
+| Version | Release Date | Type | Highlights |
+|---------|-------------|------|------------|
+| 4.6.0   | 2024-11-27  | Minor | FastCGI plugin, JWT enhancements |
+| 4.5.0   | 2024-XX-XX  | Minor | Previous release |
+| ...     | ...         | ...   | ... |
+
+---
+
+**Need Help?**
+- Open an issue: https://github.com/byjg/docker-easy-haproxy/issues
+- Check documentation: https://opensource.byjg.com/devops/docker-easy-haproxy/

deploy/docker/docker-compose.yml

@@ -1,5 +1,3 @@
-version: "3"
-
 services:
   easyhaproxy:
     image: byjg/easy-haproxy:4.6.0