High availability

View as Markdown

High availability (HA) keeps Proto Fleet reachable when one Fleet host stops serving. Browsers and API clients use one virtual IP address. That address moves between two Fleet hosts when ownership changes.

Use HA for a new deployment that needs automatic local failover. For a single-host deployment, follow the standard installation guide.

Install an HA cluster

Prepare three hosts and run the guided installer.

Update an HA cluster

Update the passive host first, then complete the update through failover.

Remove an HA cluster

Remove the runtime or delete all local HA state for a fresh installation.

Troubleshoot an HA cluster

Check readiness, installation, updates, and virtual IP access.

Topology

HostRole
ha-aFull Fleet host and database host
ha-bFull Fleet host and database host
ha-cCoordination witness; it does not serve Fleet

Exactly one full Fleet host is active. The other remains passive and can take over the virtual IP. The witness helps the hosts agree which one may be active.

Supported hosts

The installer supports dedicated hosts with apt, systemd, sudo, and iproute2:

  • Debian 12 or 13
  • Ubuntu 22.04 or 24.04
  • 64-bit Raspberry Pi OS based on Debian 12 or 13
  • Debian or Ubuntu derivatives whose reported release is available from Docker’s package repository

Hosts may use amd64 or arm64, and all hosts must use a 4,096-byte page size. RPM-based Linux distributions, Linux systems without systemd, and 32-bit hosts are not supported.

Before you choose HA

You need:

  • Three dedicated hosts on the same local network
  • One reserved IPv4 address for each host
  • One unused IPv4 address for the virtual IP, excluded from the DHCP pool
  • SSH and sudo access to every host
  • Network routes from both full Fleet hosts to your miners
  • The same Proto Fleet release on all three hosts; host architectures may differ

HA is available starting with Proto Fleet v0.2.10. It is for new deployments and does not convert an existing standard installation in place.

What to expect

  • A host or application outage causes a brief interruption while the virtual IP moves.
  • Queued commands run after failover. Commands interrupted while running may need to be retried.
  • Rolling updates replace Fleet application services only. Database, coordination, and virtual IP services stay in place.
  • There is no in-place host replacement workflow. Rebuild the three-node cluster when replacing a host.
  • HA keeps Fleet available, but it does not replace backups.

Continue to install an HA cluster.