hjr265 / loadcat

NGINX load balancer configurator

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

Docker Image

Install Loadcat using Docker:

# docker run -p 26590:26590 -p 80:80 -p 443:443 loadcat/base:v0.1.1

From Source

Install Loadcat using the go install command:

$ go install github.com/hjr265/loadcat/cmd/loadcatd@latest

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.

loadcat's Issues

Installation via go failed

Following the instructions of the guide, go returns this message:

"go install: version is required when current directory is not in a module
Try 'go install github.com/hjr265/loadcat/cmd/loadcatd@latest' to install the latest version"

It is suggested to add @latest

update server (worker) parameters

Is it possible with loadcat to update the parameters (say weight) of an existing server in balancer?

docker version

is there loadcat under docker

so we can setup nginx under one docker continer, and loadcat another container..

thx

Client Certificate Verification for HTTPS

Description

This issue proposes the addition of a new feature to Loadcat that enables users to optionally add client certificate verification when HTTPS is enabled. Client certificate verification adds an extra layer of security by requiring clients to present a valid certificate during the SSL/TLS handshake process.

ScreenShots

• 

• 

Remove server

Hello,
I know that this package has this feature to make a server unavailable.
I was wondering why you don't have the ability to also remove a server compeletely.
Would you please consider this?

Update Nginx Version - Docker

This issue proposes updating the Nginx version specified in the Dockerfile to ensure compatibility with the latest features and security patches. Additionally, it suggests creating a docker-compose_base.yml file to facilitate the local setup and build process.

• It's crucial to note that the ssl on; directive is deprecated in recent versions of Nginx.
• Keeping this directive in the nginx.conf template will result in errors and potential misconfigurations.
• The issue proposes updating the nginx.conf template to remove the deprecated ssl on; directive

Balancers can't be removed from the GUI

As the title says, there is no option to remove a balancer or a server

Error Loading SSL Certificate and Key Paths in Nginx Template

This issue addresses an error encountered when attempting to load SSL certificate and key files in the Nginx configuration template. The error message indicates that the certificate file specified by ssl_certificate directive cannot be loaded due to a "No such file or directory" error.

The template is incorrectly using {{.Dir}} as the directory path, which results in the incorrect location /etc/nginx/out/<bal_id> instead of the expected location /var/lib/loadcat/out/<bal_id> where the certificate and key files are generated

Proposed Solution:

Hardcode Directory Path: Modify the Nginx configuration template to explicitly specify the correct directory path /var/lib/loadcat/out/{{.Balancer.Id.Hex}} for locating the SSL certificate and key files.

panic: open ui/templates/layout.html: no such file or directory

Trying to run this after using the go get installation. Getting the following error:

$ .go/bin/loadcatd
panic: open ui/templates/layout.html: no such file or directory

goroutine 1 [running]:
html/template.Must(0x0, 0x7fe6f4f8f078, 0xc20803b530, 0x1)
    /usr/lib/golang/src/html/template/template.go:304 +0x50
github.com/hjr265/loadcat/ui.init()
    .go/src/github.com/hjr265/loadcat/ui/templates.go:10 +0x14a
main.init()
    .go/src/github.com/hjr265/loadcat/cmd/loadcatd/main.go:63 +0x42