Two commands, and no forms to fill in
There is no download button, no registration and no license key. Clone the repository onto a server and run the installer.
Install the manager
sudo git clone https://git.failoverlb.net/failoverlb.git /data/docker/failoverlb \
&& sudo /data/docker/failoverlb/failoverlb_setup.sh \
--allowlist 198.51.100.25/32 \
--acme-email you@example.comReplace the allowlist with the public address of wherever you will manage this from. It is checked before the login page even renders, so a stolen password from the wrong network gets nothing.
Build nginx
sudo /data/docker/failoverlb/nginx-installer.sh installThe manager manages an nginx, it does not bring its own. This compiles nginx 1.30.4 from source against OpenSSL 3.5.7 with every module the GUI knows how to configure. It takes a few minutes.
Add a second server
Get a token from Cluster, Add a node on the first server, then on the second:
sudo git clone https://git.failoverlb.net/failoverlb.git /data/docker/failoverlb \
&& sudo /data/docker/failoverlb/failoverlb_setup.sh \
--join 203.0.113.10:7444 --token <token> \
--allowlist 198.51.100.25/32Replayed from a real run on a clean Ubuntu 26.04 machine.
What is in the repository
Everything, including the things that build everything else
| Path | What it is |
|---|---|
app/ | The manager: the web interface, the JSON API, the cluster logic, the health checker, the certificate handling, the config parser and renderer. |
app/catalog/ | Every nginx setting the GUI offers, with its help text, examples, validation and gating. |
host-agent/ | The root daemon and its systemd unit. The only privileged part, and the part worth reading. |
checks/ | Test suites meant to be run against a real installed fleet rather than a mock of one. |
docs/ | The 41 chapter user guide, and the comparison notes. |
sbom/ | A software bill of materials for what the build pulls in. |
nginx-installer.sh | Builds nginx from source with the modules, sets up certbot, keeps a rollback. |
docker_setup.sh | Docker CE on Ubuntu, done properly. |
install.sh | The per node install: agent, group, systemd unit, settings file, container, cluster join. |
failoverlb_setup.sh | The one shot setup that ties the above together. |
auth-recovery.sh | Puts local passwords back when single sign on has stopped working. |
LICENSE | MIT. |
Verify what you installed
Worth doing once, on each node.
# What nginx was built with
nginx -V
# Is the post quantum key exchange there
openssl list -kem-algorithms | grep -i mlkem
# Is the agent running
sudo systemctl status nginx-mgr-agent
# Is the manager running
sudo docker ps --filter name=nginx-fleet-manager
# What the manager thinks
sudo docker logs nginx-fleet-manager | tail -20The dashboard shows the same information: the nginx version, the OpenSSL version with a post quantum badge when the build supports it, the module count, and the config version. The quickest way to confirm two nodes match is to look at that panel on both.
Before you put it in front of traffic
Read this list first
- Set the allowlist on every node. Without it, anybody who can reach port 7443 gets the login page.
- Certificates start pointed at the practice service on purpose. Turn that off once you have one working.
- Test the failover deliberately, in daylight, before you need it.
- There is no support contract. When it breaks, the person fixing it is you.
- There has been no third party security audit.
Licensing
MIT, which means you do not have to ask
Use it commercially. Fork it. Change it. Ship it inside something else. Keep your changes private if you want to. You do not owe anybody anything and you do not have to tell anybody.
Two fresh servers is all it takes
Ubuntu 22.04 or newer, root access, and about twenty minutes. The installer does the rest and it is safe to run twice.