Loadcat

Loadcat is an Nginx configurator that allows you to use Nginx as a load balancer. The project is inspired by the various Nginx load balancing tutorial articles available online and also the existence of Linode's load balancer service NodeBalancers. So far the tool covers some of HTTP and HTTPS load balancing features, such as SSL termination, adding servers on the fly, marking them as unavailable or backup as necessary, and setting their weights to distribute load fairly.

Installation

Arch Linux

Install Loadcat using a pre-built .pkg file:

$ wget https://github.com/hjr265/loadcat/releases/download/v0.1-alpha.1/loadcat-0.1_alpha.1-1-x86_64.pkg.tar.xz
# pacman -U loadcat-0.1_alpha.1-1-x86_64.pkg.tar.xz

Or, from AUR using Yaourt:

$ yaourt loadcat

Or, manually:

$ git clone https://aur.archlinux.org/loadcat.git
$ cd loadcat
$ makepkg
# pacman -U loadcat-0.1_alpha.1-1-x86_64.pkg.tar.xz

From Source

Install Loadcat using the go get command:

$ go get github.com/hjr265/loadcat/cmd/loadcatd

Usage

If you installed Loadcat using the distribution specific package, you can start it as a service using systemctl:

# systemctl start loadcat.service

If you installed Loadcat from source, you can launch it with:

$ cd $GOPATH/src/github.com/hjr265/loadcat
# $GOPATH/bin/loadcatd

Loadcat parses a TOML encoded configuration file. In case one is not found, Loadcat will create one with same sane defaults. The location of the configuration file can be specified with the -config flag.

Loadcat works by generating Nginx configuration files under a particular directory (a directory named "out" under Loadcat's working directory, as set in loadcat.conf). Nginx must be configured to load configuration files from this directory. For example on Arch Linux, when installed from AUR, Loadcat uses /var/lib/loadcat/out as the directory where generated Nginx configuration files are stored. You must include the following line inside the http {} block of /etc/nginx/nginx.conf to load configuration files generated by Loadcat:

include  /var/lib/loadcat/out/*/nginx.conf

Once Loadcat is running, you can navigate to http://{host}:26590 on your web browser, where {host} is the domain name or IP address of the machine where Loadcat is running (for example http://localhost:26590 when running locally). To save a thousand words, here is a (kind of big) picture:

Make sure that Nginx is running as a systemd service and is configured to load generated configuration files from the appropriate directory.

Caution

As this is a very young project, and pretty experimental, you may encounter bugs and issues here and there. It would be really appreciated if you could open an issue outlining details of the bug or issue, or any feature that you would like to request. Any contribution or criticism (constructive or destructive) is really appreciated.

A lot of Nginx load balancing features is still not covered by this tool and at this moment that makes this rather limited in context of practical applications. However, solving this problem is just a matter of time. Although Nginx Plus specific features may have to wait for a while - at least until I get my hands on an instance or someone else with access to Nginx Plus starts contributing.

Documentation

• Reference

Resources

• DigitalOcean's Tutorial on Using Nginx as a Load Balancer
• Nginx's HTTP Load Balancing Documentation

Contributing

Contributions are welcome.

License

Loadcat is available under the BSD (3-Clause) License.