Manual / Setup

Installation

OpenFollow ships as a pre-built release. The simplest path is the ready-made image for your board – Raspberry Pi 5 or Compute Module 5 – which boots straight into the app. Any other 64-bit Raspberry Pi uses the .deb package, and so does a 64-bit Intel or AMD PC running Debian 13 (Trixie); the package is made for a headless OS – Raspberry Pi OS Lite or a Debian without a desktop environment. For development or branch tracking, build from source. Pick the tab that matches your setup below. Everything comes from the OpenFollow releases page, and every option is configured from the web UI at http://<host-ip> once the device boots.

Once it's running, keep the app current from the web UI – see Updating.

The image is Raspberry Pi OS Lite with OpenFollow pre-installed. It boots straight into the app on the HDMI output – nothing to install on the device. Download openfollow-pi5_<version>.img.xz from the OpenFollow releases page and flash it to a microSD card.

Insert a microSD card (8 GB or larger) into your computer.
In Raspberry Pi Imager: Choose OS → Use custom, select openfollow-pi5_<version>.img.xz.
Choose Storage → the microSD card → Write.
Insert the card into the Pi 5 and power on – it comes up running OpenFollow on HDMI. The storage auto-expands to fill the card on first boot.

Open the web UI at http://<pi-ip> to configure it.

The image is Raspberry Pi OS Lite with OpenFollow pre-installed. It boots straight into the app on the HDMI output – nothing to install on the device. Download openfollow-cm5_<version>.img.xz from the OpenFollow releases page and flash it to the onboard eMMC.

The CM5 has no card slot, so you flash the onboard eMMC over USB: put the IO board into rpiboot mode to expose the eMMC as a USB drive, then write the image with Raspberry Pi Imager. Pick your computer's OS below.

Connect the CM5 straight to the computer. Run the USB-C cable directly from the computer to the board's USB-C slave / OTG port, and unplug every USB-C dock, hub, and dongle first. Through a dock or adapter, rpiboot won't see the eMMC.

You'll use Terminal – a standard macOS app for running text-based commands. Type or paste each line exactly and press Enter.

Open Terminal.
Press Cmd+Space, type Terminal, and press Enter.
Build and start rpiboot.
With Homebrew installed, build Raspberry Pi's usbboot tool and start it in mass-storage mode:
```
brew install libusb pkg-config
git clone --depth=1 https://github.com/raspberrypi/usbboot.git
cd usbboot
make
sudo ./rpiboot -d mass-storage-gadget64
```
Leave it running – it waits for the CM5 to appear.
Put the CM5 into bootloader mode.
With rpiboot running, the board powered off, and the USB-C cable not yet connected: fit the jumper marked Fit jumper to disable eMMC Boot on the IO board, press and hold the CM5's power button, and – still holding it – connect the USB-C cable. Release the button the instant the LED next to the HDMI port turns red. rpiboot detects the BCM2712 and the eMMC appears as a USB drive. macOS may warn the disk is unreadable – expected, it holds a Linux filesystem; dismiss the warning and don't initialise the disk.
Flash the image.
Once Terminal shows the eMMC mounted, open Raspberry Pi Imager: Choose OS → Use custom, select openfollow-cm5_<version>.img.xz. Choose Storage → the CM5 eMMC → Write.
Boot it.
When the write finishes, power off the board, remove that jumper, and power back on. The CM5 comes up running OpenFollow on HDMI.

You'll use a terminal for a few text-based commands. The package names below are for Debian / Ubuntu / Raspberry Pi OS; adjust for other distributions.

Open a terminal.
Press Ctrl+Alt+T, or open "Terminal" from your applications.

Build and start rpiboot.

Install the build dependencies, build Raspberry Pi's usbboot tool, and start it in mass-storage mode:

sudo apt install -y git libusb-1.0-0-dev pkg-config build-essential
git clone --depth=1 https://github.com/raspberrypi/usbboot.git
cd usbboot
make
sudo ./rpiboot -d mass-storage-gadget64

Leave it running – it waits for the CM5 to appear.

Put the CM5 into bootloader mode.
With rpiboot running, the board powered off, and the USB-C cable not yet connected: fit the jumper marked Fit jumper to disable eMMC Boot on the IO board, press and hold the CM5's power button, and – still holding it – connect the USB-C cable. Release the button the instant the LED next to the HDMI port turns red. rpiboot detects the BCM2712 and the eMMC appears as a USB drive. Don't let your file manager format or initialise it – it holds a Linux filesystem.
Flash the image.
Once the terminal shows the eMMC mounted, open Raspberry Pi Imager: Choose OS → Use custom, select openfollow-cm5_<version>.img.xz. Choose Storage → the CM5 eMMC → Write.
Boot it.
When the write finishes, power off the board, remove that jumper, and power back on. The CM5 comes up running OpenFollow on HDMI.

Windows uses Raspberry Pi's prebuilt rpiboot installer, so there's no terminal or building involved – it's all graphical.

Install rpiboot.
Download the Windows rpiboot installer from the usbboot repository and run it, accepting the defaults.
Start rpiboot.
Launch rpiboot from the Start menu. Leave its window open – it waits for the CM5 to appear.
Put the CM5 into bootloader mode.
With rpiboot running, the board powered off, and the USB-C cable not yet connected: fit the jumper marked Fit jumper to disable eMMC Boot on the IO board, press and hold the CM5's power button, and – still holding it – connect the USB-C cable. Release the button the instant the LED next to the HDMI port turns red. rpiboot boots the CM5 and the eMMC appears as a drive in File Explorer. Windows may offer to format the disk – cancel; it holds a Linux filesystem.
Flash the image.
Once the eMMC is mounted, open Raspberry Pi Imager: Choose OS → Use custom, select openfollow-cm5_<version>.img.xz. Choose Storage → the CM5 eMMC → Write.
Boot it.
When the write finishes, power off the board, remove that jumper, and power back on. The CM5 comes up running OpenFollow on HDMI.

Open the web UI at http://<pi-ip> to configure it.

For any other 64-bit Raspberry Pi (a model without a ready-made image), install the .deb package on headless Raspberry Pi OS Lite (64-bit). You set the Pi up from another computer over SSH, so the Pi needs no keyboard of its own. It does need internet during the install so apt can pull the package's system dependencies.

Use Raspberry Pi OS Lite (64-bit) – not the Desktop version. The package is made for the headless Lite system: OpenFollow drives the HDMI output itself and runs full-screen. The Desktop's graphical environment isn't supported. In Raspberry Pi Imager, choose Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit).

Flash Raspberry Pi OS Lite (64-bit).
In Raspberry Pi Imager, open the settings (the gear icon): enable SSH, create a user – note the username and password – and set the hostname and Wi-Fi too if the Pi isn't on wired Ethernet. Enter the username here:

The username you created

Flash the card, connect the Pi to a monitor, and power it on. The first boot can take several minutes, with a lot of text scrolling on screen – that's normal. It finishes by printing My IP address is …. Enter that address here:

Your Pi's IP address
Connect to the Pi from your computer.
Open Terminal (macOS or Linux) or PowerShell (Windows) and connect over SSH. Where the command shows <pi-user> and <pi-ip>, use the username you created and the Pi's IP address – or fill the boxes above to complete every command at once:
```
ssh <pi-user>@<pi-ip>
```
When asked if you want to connect, type yes. When it asks for the password, type the one you set and press Enter – the characters won't appear as you type, that's normal. From here on, what you type runs on the Pi.

SSH refused with a host-key warning? If you see REMOTE HOST IDENTIFICATION HAS CHANGED, the Pi's SSH identity changed since you last connected at this IP (typically a reflash). Clear the stale key and reconnect: ssh-keygen -R <pi-ip> (same command on macOS, Linux, and Windows PowerShell).
Download the package onto the Pi.
This pulls the latest release's openfollow_<version>_arm64.deb onto the Pi:
```
wget <asset-url>
```
If the command still shows <asset-url>, open the releases page, copy the link to the .deb file, and use that in its place.

Install it.

sudo apt update
sudo apt upgrade -y
sudo apt install -y ./openfollow_*_arm64.deb

The package pulls in everything OpenFollow needs, grants the service the privileges it requires – no root, no separate permission step – and starts it straight away, and on every boot after, full-screen on HDMI. No reboot needed: once the install finishes, give it a few seconds and open the web UI at http://<pi-ip> to configure it.

OpenFollow also installs on a 64-bit Intel or AMD machine – a mini-PC, NUC, or laptop – from the amd64 .deb package. The package is made for a headless Debian without a desktop environment: OpenFollow drives the display itself and runs full-screen. It needs internet during the install so apt can pull the package's system dependencies.

Requires Debian 13 (Trixie), 64-bit. The package's dependencies are built against the Python 3.13 that ships with Trixie – the same base as Raspberry Pi OS. Debian 12 and Ubuntu 24.04 carry an older Python, and the install is refused on them.

Install Debian 13 (Trixie), 64-bit – headless.
Put the machine on wired Ethernet. In the installer's software selection, leave every desktop environment unticked – a minimal headless install.
Download the package.
Pull the latest release's openfollow_<version>_amd64.deb onto the machine – not the .ofupdate file, which is for the in-app updater:
```
wget <asset-url>
```
If the command still shows <asset-url>, open the releases page, copy the link to the amd64.deb file, and use that in its place.

Install it.

sudo apt update
sudo apt upgrade -y
sudo apt install -y ./openfollow_*_amd64.deb

The package pulls in everything OpenFollow needs, grants the service the privileges it requires – no root, no separate permission step – and starts it straight away, and on every boot after, full-screen on the display. No reboot needed: once the install finishes, give it a few seconds and open the web UI at http://<host-ip> to configure it.

A source-based install builds from a source checkout instead of a pre-built release – use it for development, for Pi models without a published image, or to track a branch. An Ansible playbook, run from your computer, sets up Python and the app's dependencies on the Pi over SSH.

Use Raspberry Pi OS Lite (64-bit) – not the Desktop version. OpenFollow drives the HDMI output itself and runs full-screen; the Desktop's graphical environment isn't supported. In Raspberry Pi Imager, choose Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit).

Internet needed during install. The Pi fetches its dependencies from the internet while the playbook runs. Once it finishes, no internet access is required.

Flash Raspberry Pi OS Lite (64-bit).
In Raspberry Pi Imager, open the settings (the gear icon): enable SSH, create a user – note the username and password – and set the hostname and Wi-Fi too if the Pi isn't on wired Ethernet. The playbook disables Wi-Fi when it finishes, so the Pi runs on wired Ethernet afterward – set Wi-Fi only to carry it through the install. On a Compute Module 5, flash to the eMMC using the rpiboot steps in the Compute Module 5 tab first. Enter the username here:

The username you created

Flash the card, connect the Pi to a monitor, and power it on. The first boot can take several minutes, with a lot of text scrolling on screen – that's normal. It finishes by printing My IP address is …. Enter that address here:

Your Pi's IP address

Install Ansible on your computer.

# macOS
brew install ansible

# Debian / Ubuntu
sudo apt install -y ansible

Run the installer against the Pi.
From the root of an OpenFollow source checkout on your computer, point the playbook at the Pi with your username and its IP address. It installs from the public source by default, so no repository access is needed. If you paste the command from a rich-text source, make sure the quotes around the inventory host are plain ASCII ' characters, not curly quotes:
```
ansible-playbook -i '<pi-ip>,' -u <pi-user> scripts/ansible/install-raspberry-pi.yml
```
It runs for several minutes, installing Python and the app's dependencies on the Pi; scrolling text is normal progress, not an error.

Playbook or SSH refused with a host-key warning? If you see REMOTE HOST IDENTIFICATION HAS CHANGED, the Pi's SSH identity changed since you last connected at this IP (typically a reflash). Clear the stale key and try again: ssh-keygen -R <pi-ip> (same command on macOS, Linux, and Windows PowerShell).
Check it.
The playbook creates a dedicated openfollow user that runs the app. Log in as that user to confirm the install:
```
ssh openfollow@<pi-ip>
```
The default password is openfollow. Open the web UI at http://<pi-ip> to configure it.

More install options for development – installing from a private fork, selecting a branch, NVMe storage, offline source archives, and the macOS development environment – are documented in the project's README on GitHub.