The offline-first
content platform.

Detailed Installation Guide

This guide serves as the authoritative reference for deploying Fyr. Choose the path that fits your specific hardware and environment requirements.

Option A: Docker on an Existing System

Use this path for a fast, repeatable deployment on Linux, macOS, or Windows.

Production Image

docker run --rm -p 8080:8080 \
  -e FYR_HOST=0.0.0.0 \
  -e DATA_DIR=/data \
  -v fyr-data:/data \
  hexagon/fyr:latest

Dev Image

docker run --rm -p 8080:8080 \
  -e FYR_HOST=0.0.0.0 \
  -e DATA_DIR=/data \
  -v fyr-data:/data \
  hexagon/fyr:dev

Persist Data Across Reinstalls and Upgrades

Fyr keeps user data only in DATA_DIR (/data in Docker examples). Reuse the same mount target on every run to keep data between container replacements.

Host folder bind-mount (direct host access):

docker run --rm -p 8080:8080 \
  -e FYR_HOST=0.0.0.0 \
  -e DATA_DIR=/data \
  -v /path/to/fyr-data:/data \
  hexagon/fyr:latest

Windows PowerShell bind-mount example:

docker run --rm -p 8080:8080 `
  -e FYR_HOST=0.0.0.0 `
  -e DATA_DIR=/data `
  -v C:\fyr-data:/data `
  hexagon/fyr:latest

sudo chown -R 1000:1000 /path/to/fyr-data

Option B: From Source (Development)

Use this path when you want to develop Fyr or run local code changes.

Prerequisites

• Rust stable toolchain
• Node.js 24 (recommended to match CI)
• npm

Build and Run

1. Build frontend assets:

cd crates/ui/frontend
npm ci
npm run build
cd ../../..

2. Build backend binary:

cargo build --release -p server --bin fyr

3. Run Fyr:

./target/release/fyr

Note: For Windows PowerShell use .\target\release\fyr.exe

Optional Runtime Overrides:

• DATA_DIR (default ./public/data)
• FYR_HOST (default 127.0.0.1; use 0.0.0.0 for Docker/LAN access)
• FYR_PORT (default 8080)

Option C: Raspberry Pi OS From Scratch

Use this path to deploy Fyr on a clean Raspberry Pi. Fyr images natively support linux/arm64, which matches Raspberry Pi 64-bit OS perfectly.

1) Flash and Update Raspberry Pi OS

Flash Raspberry Pi OS 64-bit (Bookworm recommended) using Raspberry Pi Imager. Boot and update packages:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

After reboot: sudo apt update

2) Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker --version

3) Run Fyr

Once Docker is installed, follow Option A above to run Fyr — the same Docker commands and environment variable overrides apply.

To start Fyr automatically on every boot:

docker run -d --restart unless-stopped --name fyr \
  -p 8080:8080 \
  -e FYR_HOST=0.0.0.0 \
  -e DATA_DIR=/data \
  -v fyr-data:/data \
  hexagon/fyr:latest

4) Optional: Set Up as a Wi-Fi Hotspot

Turn your Raspberry Pi into a standalone Wi-Fi hotspot so phones, tablets, and laptops can connect directly to Fyr — no existing router or internet connection required. This is ideal for field use, classrooms, or off-grid deployments.

Create the hotspot (replace Fyr and offline-fyr with your preferred SSID and password):

sudo nmcli device wifi hotspot \
  ifname wlan0 \
  con-name fyr-hotspot \
  ssid "Fyr" \
  password "offline-fyr"

Enable the hotspot to start automatically on every boot:

sudo nmcli connection modify fyr-hotspot connection.autoconnect yes
sudo nmcli connection modify fyr-hotspot connection.autoconnect-priority 10

Bring it up immediately without rebooting:

sudo nmcli connection up fyr-hotspot

Once devices connect to the Fyr Wi-Fi network, they can reach Fyr at http://10.42.0.1:8080 (the default hotspot gateway address assigned by NetworkManager).

Quick Verification Checklist

• docker ps (if running in Docker) shows the Fyr container as running.
• Your browser can open /api/status on your target host and port.
• The DATA_DIR location is writable by the system.
• Port 8080 is not blocked by a firewall or occupied by another service.