Metadata-Version: 2.4
Name: easyhaproxy
Version: 6.0.0
Summary: HAProxy label based routing with service discovery for Docker, Swarm, and Kubernetes
License: MIT License
        
        Copyright (c) 2018 Joao Gilberto Magalhães
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: docker,haproxy,kubernetes,load-balancer,service-discovery
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: deepdiff>=6.0.0
Requires-Dist: docker>=7.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: kubernetes>=28.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyopenssl>=24.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# EasyHAProxy

[![Sponsor](https://img.shields.io/badge/Sponsor-%23ea4aaa?logo=githubsponsors&logoColor=white&labelColor=0d1117)](https://github.com/sponsors/byjg)
[![Opensource ByJG](https://img.shields.io/badge/opensource-byjg-success.svg)](http://opensource.byjg.com)
[![Build Status](https://github.com/byjg/docker-easy-haproxy/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/byjg/docker-easy-haproxy/actions/workflows/build.yml)
[![GitHub source](https://img.shields.io/badge/Github-source-informational?logo=github)](https://github.com/byjg/docker-easy-haproxy/)
[![GitHub license](https://img.shields.io/github/license/byjg/docker-easy-haproxy.svg)](https://opensource.byjg.com/opensource/licensing.html)
[![GitHub release](https://img.shields.io/github/release/byjg/docker-easy-haproxy.svg)](https://github.com/byjg/docker-easy-haproxy/releases/)
[![Helm Version](https://img.shields.io/badge/dynamic/yaml?color=blue&label=Helm&query=%24.entries.easyhaproxy%5B0%5D.version&url=http%3A%2F%2Fopensource.byjg.com%2Fhelm%2Findex.yaml)](https://opensource.byjg.com/helm)
[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/byjg)](https://artifacthub.io/packages/search?repo=byjg)

![EasyHAProxy](docs/easyhaproxy_logo.png)

## Service discovery for HAProxy

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
- MicroK8s
- DigitalOcean Marketplace

See detailed instructions on how to install below.

## EasyHAProxy Mission

Easy to set up and low configuration to numerous features. 

## 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 other CAs.
- Set your custom SSL certificates
- Balance traffic between multiple replicas
- 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.
- Enable/disable custom errors.

Also, it is possible to set up HAProxy from a simple Yaml file instead of creating `haproxy.cfg` file.

## How Does It Work?

You don't need to change your current infrastructure and don't need to learn the HAProxy configuration.

The steps are:

- Run the EasyHAProxy container;
- Add some labels to the containers you want to be parsed by EasyHAProxy (see detailed instructions below);
- EasyHAProxy will automatically detect the containers, set up, and reload the HAProxy configurations for you without downtime.

## Detailed Instructions

For detailed instructions on how to use EasyHAProxy, follow the instructions for the platform you want to use:

[![Kubernetes](docs/easyhaproxy_kubernetes.png)](docs/kubernetes.md)
[![Docker Swarm](docs/easyhaproxy_swarm.png)](docs/swarm.md)
[![Docker](docs/easyhaproxy_docker.png)](docs/docker.md)
[![Static](docs/easyhaproxy_static.png)](docs/static.md)

Or you can install using tools:

[![Helm](docs/easyhaproxy_helm.png)](docs/helm.md)
[![MicroK8s](docs/easyhaproxy_microk8s.png)](docs/microk8s.md)
[![Dokku](docs/easyhaproxy_dokku.png)](docs/dokku.md)
[![DigitalOcean](docs/easyhaproxy_digitalocean.png)](docs/digitalocean.md)

## Special Topics

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
- [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

## Development

### Requirements

- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv) package manager

### Installation for Development

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/byjg/docker-easy-haproxy.git
cd docker-easy-haproxy

# Install dependencies (creates virtual environment automatically)
uv sync --dev

# Run tests
make test
# or directly: uv run pytest tests/ -vv

# Run linting
make lint

# Format code
make format
```

### Installing the Package

```bash
# Install with uv
uv pip install easymapping

# Or install from source
uv pip install -e ".[dev]"
```

## See EasyHAProxy in action

Click on the image to see the videos (use HD for better visualization)

[![Docker In Action](docs/video-docker.png)](https://youtu.be/ar8raFK0R1k)
[![Docker and Letsencrypt](docs/video-docker-ssl.png)](https://youtu.be/xwIdj9mc2mU)
[![K8s In Action](docs/video-kubernetes.png)](https://youtu.be/uq7TuLIijks)
[![K8s and Letsencrypt](docs/video-kubernetes-letsencrypt.png)](https://youtu.be/v9Q4M5Al7AQ)
[![Static Configuration](docs/video-static.png)](https://youtu.be/B_bYZnRTGJM)
[![TCP Mode](docs/video-tcp-mysql.png)](https://youtu.be/JHqcq9crbDI)

[Here is the code](https://gist.github.com/byjg/e125e478a0562190176d69ea795fd3d4) applied in the test examples above.


----
[Open source ByJG](http://opensource.byjg.com)
