Install the master

What this gets you

A running master: the first machine, powered on and ready for you to open its web panel and log in for the first time.

Before you start

• The machine you’re using as the master, connected to your router by Ethernet.
• An Ubuntu Server install already on it, matching what What you need expects.
• A terminal on that machine, or SSH access to it.

Option A — Install from the latest published package (recommended)

This is the way to install the master. One package covers both ARM64 and x86-64 machines; the installer picks the right one for the machine it’s running on.

The steps

1. Find the version you want. Open Release notes — the newest release is listed first. The steps below use 0.0.22 as the example; put your version in its place.

   Note the release notes write a version as v0.0.22, with a leading v, but the download address uses the bare number 0.0.22. Leave the v out of the commands.

2. On the master, download the package and its checksum file into the same folder:

   v=0.0.22
   curl -fLO https://releases.buddy-cluster.dev/releases/$v/buddy-cluster-$v-linux.tar.gz
   curl -fLO https://releases.buddy-cluster.dev/releases/$v/SHA256SUMS

3. Verify the download before you run anything from it:

   sha256sum -c SHA256SUMS

   It must print the package’s name followed by OK. If it prints FAILED, don’t go on — see Verifying a download.

4. Unpack it and run the installer:

   tar xzf buddy-cluster-$v-linux.tar.gz
   cd buddy-cluster-$v-linux
   sudo ./install.sh

Re-running the installer later is safe: it upgrades Buddy Cluster in place without touching your existing cluster. Before it touches your data, Buddy backs it up on its own; if the version you’re installing is too far behind what your cluster already has, it refuses to start rather than risk your data, leaving everything exactly as it was.

Once the master is running, you don’t need to come back here for later versions. Buddy checks for new releases itself and can install them for you from the panel — see Keep the cluster updated.

Option B — Flash a ready-made image

⚠Known limitation

No ready-made image is published for any release. Buddy Cluster can be built into one, but no image file has ever been made available to download, so this option cannot be followed today. Use Option A above. This section stays here because the steps are accurate for an image you already have — not because there is somewhere to get one.

Use this only if you already hold an image file and its matching SHA256SUMS, and you’re starting from a blank memory card.

1. Verify the image before you write it anywhere:

   sha256sum -c SHA256SUMS

2. Write the image to the master’s memory card with an imaging tool such as Raspberry Pi Imager or balenaEtcher; or, from a terminal:

   xz -dc buddy-cluster-<version>-arm64.img.xz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync

3. Insert the card into the master, connect it to your router by Ethernet, and power it on. On its first boot it configures itself and starts the panel automatically, no further action needed at the machine itself.

An image ships with a default operating-system login (buddy / buddy, for console or SSH access to the machine itself). Change that password after first boot. This is separate from the web panel’s own admin account, which you set up next in Open the panel and log in.

How you know it worked

The panel becomes reachable at the master’s address over HTTPS. Continue to Open the panel and log in to confirm it.

What can go wrong

• The download can’t be found, or the checksum doesn’t match
• The master isn’t reachable at all after installing (no SSH, no panel)
• The panel won’t open

See these symptoms in Troubleshooting.