High availability

Install a high-availability cluster

View as Markdown

Install Proto Fleet high availability (HA) on three dedicated Linux hosts. You run one command for each host. The installer creates the cluster configuration and credentials.

Before you begin

Confirm that you have:

  • Three supported hosts on the same local network
  • Reserved IPv4 addresses for ha-a, ha-b, and ha-c
  • An unused IPv4 address for the virtual IP, excluded from the DHCP pool
  • The same SSH username on ha-b and ha-c
  • SSH and sudo access to every host
  • curl on every host
  • Outbound HTTPS access to GitHub releases and the host package repositories

The hosts can use different processor architectures. The installer selects the correct release artifact for each host and pins all three hosts to the same Proto Fleet version.

1

Start the installation on ha-a

From your operator machine, run the public installer on ha-a. Replace the SSH destination with the username and address for your host:

$ssh -A -t admin@10.40.0.11 'curl -fsSL https://fleet.proto.xyz/install.sh | sudo --preserve-env=SSH_AUTH_SOCK bash -s -- --ha'

The -A option forwards your SSH agent to ha-a, and --preserve-env=SSH_AUTH_SOCK keeps it available to the installer when it connects to the peers. If you use passwords instead, omit both options and respond to the prompts.

The installer downloads the correct release artifact and verifies its checksum. It then asks for:

  1. The ha-b IPv4 address
  2. The ha-c IPv4 address
  3. The virtual IPv4 address
  4. The SSH username shared by ha-b and ha-c

Review the displayed topology and host changes. Type INSTALL to continue.

The installer checks both SSH destinations before it changes ha-a. It then sends each peer its protected host bundle and installs the local HA service. Password and host-key prompts can appear during the SSH checks.

When ha-a finishes, save the public service CA fingerprint and the complete commands for ha-b and ha-c from its output.

2

Install ha-b

On your operator machine, run the first command printed by ha-a.

The command confirms that the prepared bundle is present. It then downloads and verifies the release selected by ha-a and installs the full passive Fleet host. You do not transfer a release archive or confirm the installation again.

The command returns after the local HA service starts. The cluster continues to converge in the background while ha-c joins.

3

Install ha-c

On your operator machine, run the second command printed by ha-a.

The witness downloads and verifies the same release, installs the coordination service, and waits until Fleet is active through the virtual IP. If it continues waiting after the other two commands finish, see installation remains at peer waiting.

When the virtual IP is ready, the command prints the public service CA download and fingerprint commands.

4

Verify and trust the public service CA

Run the CA commands printed by ha-c on your operator machine. They:

  1. Download the public certificate from the virtual IP.
  2. Write one parsed certificate to proto-fleet-ha-service-ca.crt.
  3. Display its SHA-256 fingerprint.

Compare that fingerprint with the value printed in the authenticated ha-a session. Import proto-fleet-ha-service-ca.crt only when the values match.

Do not import the certificate before comparing the fingerprints. Never import or distribute a host bundle. Host bundles contain private keys and cluster credentials.

$sudo install -m 0644 proto-fleet-ha-service-ca.crt /usr/local/share/ca-certificates/proto-fleet-ha-service-ca.crt
$sudo update-ca-certificates

Other operating systems and managed browsers have their own trust-store settings.

5

Open Fleet

Open https://<virtual-ip> in a browser that trusts the public service CA. Create the administrator account and pair miners through the normal first-run flow.

If the installer stops or Fleet does not open at the virtual IP, see HA troubleshooting.