Installing

One or two servers running Ubuntu 22.04 or newer, with internet access and root. That is the whole list.

• One server works and gives you the GUI, the certificates and the WAF.
• Two servers is what gives you failover, and is the shape everything here is designed around.
• The servers do not need to be large. Four processors and four gigabytes is comfortable for most workloads.
• You also want a domain name you control, so you can get certificates.

Two commands. The first fetches the code and sets up Docker if it is missing. The second builds nginx.

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.com

sudo /data/docker/failoverlb/nginx-installer.sh install

Replace the allowlist with the public address of your office or wherever you will manage this from. Then open the address the installer printed on port 7443.

22.04 and newer. The Docker setup script refuses anything older and says so. The installers are tested on the long term support releases, and they will try on other Ubuntu versions and tell you up front that they are outside what is promised.

Debian will very likely work and is not what this is written for.

Red Hat, Rocky and Alma are not supported, and the reasoning is written out on the why page. The short version is one person cannot honestly test four moving targets, plus a long standing grudge about CentOS.

It is the list of networks allowed to load the management GUI, and it is checked before the login page even renders. A stolen password from the wrong network gets nothing.

Put your office public address followed by /32, or your office range such as 198.51.100.0/24. If you are not sure what your address is, visit any site that reports it.

Without it, anybody who can reach port 7443 gets the login page. Set it before you put this anywhere interesting.

It is printed to the container log once, during installation.

cd /data/docker/failoverlb
sudo docker compose logs | grep -A3 "Made the first admin"

Change it as soon as you are in. If you have lost it entirely, use the console recovery command instead.

It is safe. Fix whatever it complained about and run exactly the same command a second time. It leaves alone anything it has already done, and it never touches your .env file or your database.

Port 5353 is where the DNS part really listens, on UDP and TCP, and a firewall rule the software manages sends 53 to it. You never open 5353 and you never test against it.

Pass --skip-docker if Docker is already set up the way you want it.

sudo /data/docker/failoverlb/failoverlb_setup.sh --skip-docker

You do not need git access at all. Copy the folder onto the box, change into it, and run the setup script from inside it. It will use what is already there.

cd /path/to/failoverlb
sudo ./failoverlb_setup.sh

Pass credentials to the setup script, or set NFM_GIT_TOKEN in the environment.

sudo ./failoverlb_setup.sh --git-user myname --git-token ghp_xxx

The token is kept inside the function that builds the clone URL, so it does not end up in a log line or in the process list of anything except git.

The installer guesses both, and the guess is worth checking on a box with several interfaces.

sudo ./failoverlb_setup.sh \
  --name lb-01 --address 203.0.113.10 --priority 100

The address is the one other nodes will reach this one on. Priority decides who wins the election, and higher takes it.

• Made a group called nginxmgr with gid 10001.
• Installed the host agent to /opt/nginx-fleet-manager and started it as a systemd service.
• Wrote an .env file with this node's identity and its secret key.
• Built and started the manager container.
• Turned off the certbot timer, on purpose.
• Put nginx-installer.sh at /opt/nginx-installer.sh so rebuilds work from the GUI.

The manager manages an nginx, it does not bring its own. The GUI comes up either way, and it warns you that nothing can be applied until nginx is there.

sudo /data/docker/failoverlb/nginx-installer.sh install

It takes the longest of any step because it compiles nginx from source with every module the GUI knows how to configure.

Do not edit anything under /etc/nginx/nginxmgr by hand. It is rewritten from scratch on every apply.