diff --git a/README.md b/README.md index ac2d6a0..d03b23c 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,93 @@ # Easy HAProxy -This Docker image will create dynamically the `haproxy.cfg` based on very simple Yaml. +This Docker image will create dynamically the `haproxy.cfg` based on the labels defined in docker containers or from +a simple Yaml instead docker # Features - Enable or disable Stats on port 1936 with custom password - Discover and setup haproxy from Docker Tag - Discover and setup haproxy redirect from Docker Tag +- Setup HAProxy CFG from a Yaml file. # Basic Usage -Docker run: +The Easy HAProxy will create the `haproxy.cfg` automatically based on the containers or from a YAML provided. + +The basic command line to run is: ```bash -docker run \ - -p 80:80 \ - -p 8080:8080 \ - -p 1936:1936 \ - --name easy-haproxy-instance \ - -e DISCOVER=swarm \ - -e HAPROXY_USERNAME=admin \ - -e HAPROXY_PASSWORD=password \ - -e HAPROXY_STATS_PORT=1936 \ +docker run -d \ + --name easy-haproxy-container \ -v /var/run/docker.sock:/var/run/docker.sock \ - -d byjg/easy-haproxy + # + Environment Variables \ + # + ports mapped to the host \ + byjg/easy-haproxy ``` -The `DISCOVER` environment variable will define where is located your containers (see below more details): -- swarm -- static (maps to /etc/haproxy/easyconfig.yml) +The mapping to `/var/run/docker.sock` is necessary to discover the docker containers and get the labels; -# Tags to defined: +The environment variables will setup the HAProxy. + +| Environment Variable | Description | +|----------------------|------------------------------------------------------------------| +| DISCOVER | How `haproxy.cfg` will be created: `static`, `docker` or `swarm` | +| HAPROXY_USERNAME | The HAProxy username to the statistics | +| HAPROXY_PASSWORD | The HAProxy password to the statistics | +| HAPROXY_STATS_PORT | The HAProxy port to the statistics | +| HAPROXY_CUSTOMERRORS | If HAProxy will use custom HTML errors. true/false | + + + +The environment variable `DISCOVER` will define where is located your containers (see below more details): +- docker +- swarm +- static + +# DISCOVER: `docker` + +This method will use a regular docker installation to discover the containers and configure the HAProxy. + +The only requirement is that containers and easy-haproxy must be in the same docker network. + +The discover will occur every minute. + +e.g.: + +```bash +docker create networkd easyhaproxy + +docker run --network easyhaproxy byjg/easyhaproxy + +docker run --network easyhaproxy myimage +``` + +# DISCOVER: `swarm` + +This method requires a functional Docker Swarm Cluster. The system will search for the labels in all containers on all +swarm nodes. + +The discover will occur every minute. + +Important: easyhaproxy needs to be in the same network of the containers or otherwise will not access. + +## Tags to be attached in the Docker Container | Tag | Description | |---------------------------------------------|---------------------------------------------------------------------------------------------------------| | com.byjg.easyhaproxy.definitions | A Comma delimited list with the definitions. Each name requires the definition of the parameters below. | | com.byjg.easyhaproxy.port. | What is the port that the HAProxy will listen to. | -| com.byjg.easyhaproxy.localport. | What is the port that the container is listening. | -| com.byjg.easyhaproxy.host. | What is the host that the HAProxy will listen to. (Defaults to 80) | +| com.byjg.easyhaproxy.localport. | What is the port that the container is listening. (Defaults to 80) | +| com.byjg.easyhaproxy.host. | What is the host that the HAProxy will listen to. | | com.byjg.easyhaproxy.redirect. | Host redirects from connections in the port defined above. | | com.byjg.easyhaproxy.sslcert. | Cert PEM Base64 encoded. | E.g. -``` +### Single Definition: + +```bash docker run \ -l com.byjg.easyhaproxy.definitions=http \ -l com.byjg.easyhaproxy.port.http=80\ @@ -52,16 +95,70 @@ docker run \ .... ``` -## Redirect Example: +### Multiples Definitions on the same container: -```text -www.byjg.com.br=>http://byjg.com.br,byjg.com=>http://byjg.com.br +```bash +docker run \ + -l com.byjg.easyhaproxy.definitions=express,admin \ + + -l com.byjg.easyhaproxy.port.express=80 \ + -l com.byjg.easyhaproxy.localport.express=3000 \ + -l com.byjg.easyhaproxy.host.express=express.byjg.com.br \ + + -l com.byjg.easyhaproxy.port.admin=80 \ + -l com.byjg.easyhaproxy.localport.admin=3001 \ + -l com.byjg.easyhaproxy.host.admin=admin.byjg.com.br \ + .... +``` + +### Redirect Example: + +```bash +docker run \ + -l com.byjg.easyhaproxy.redirect.=www.byjg.com.br::http://byjg.com.br,byjg.com::http://byjg.com.br +``` + +# DISCOVER: `static` + +This method expects a YAML file to setup the `haproxy.cfg` + +Create a YAML file and map to `/etc/haproxy/easyconfig.yml` + +```yaml +stats: + username: admin + password: password + port: 1936 # Optional (default 1936) + +customerrors: true # Optional (default false) + +easymapping: + - port: 80 + hosts: + host1.com.br: container:5000 + host2.com.br: other:3000 + redirect: + www.host1.com.br: http://host1.com.br + + - port: 443 + ssl_cert: BASE64_PEM_CERTIFICATE + hosts: + host1.com.br: container:80 + + - port: 8080 + hosts: + host3.com.br: domain:8181``` +``` + +Running: + +```bash +docker run -v /my/config.yml:/etc/haproxy/easyconfig.yml .... byjg/easyhaproxy ``` # Mapping custom .cfg files -Just create a folder and put files with the extension .cfg. and map the volume to the container. -This will concatenate your config into the main haproxy.cfg +Map a folder containing valid HAProxy `.cfg` files to `/etc/haproxy/conf.d`. It will be concatenated to your HAProxy CFG. ```bash docker run \ @@ -70,29 +167,6 @@ docker run \ -d byjg/easy-haproxy ``` -Check if your config is ok: - -```bash -docker run \ - /* other parameters */ - -v /your/local/conf.d:/etc/haproxy/conf.d \ - -byjg/easy-haproxy -c -f /etc/haproxy/haproxy.cfg -``` - -# Docker Compose - -```yaml -version: "3.4" -services: - front: - image: byjg/easy-haproxy - volume: - - /path/to/local:/etc/easyconfig - ports: - - 80:80 - - 8080:8080 - - 1936:1936 -``` # Handling SSL @@ -110,8 +184,8 @@ Important: Different certificates need to be handled in different entries. # Setting Custom Errors -Map the volume : `/etc/haproxy/errors-custom/` and put a file named `ERROR_NUMBER.http` where ERROR_NUMBER -is the http error code (e.g. 503.http) +If enabled, map the volume : `/etc/haproxy/errors-custom/` to your container and put a file named `ERROR_NUMBER.http` +where ERROR_NUMBER is the http error code (e.g. 503.http) # Build @@ -120,17 +194,3 @@ docker build -t byjg/easy-haproxy . ``` - -# Docker Swarm - - -# AWS - -Easy HAProxy will try to get tasks from the tasks running in the CLUSTER. -It is important that easy haproxy run in the ECS Cluster and can connect to the containers. - - -You'll have to pass also the `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` or setup a role in the instance in order and -the `ECS_CLUSTER` with the arn of the cluster - - diff --git a/assets/etc/haproxy/certs/README.md b/assets/etc/haproxy/certs/README.md new file mode 100644 index 0000000..828a1d8 --- /dev/null +++ b/assets/etc/haproxy/certs/README.md @@ -0,0 +1,3 @@ +# Certs Folder + +Docker Easy HAProxy will save the SSL Certs here.