FFOS Local Build (containerized)#

This folder provides a local FFOS ISO build pipeline using Docker (Arch Linux + archiso). It avoids Git submodules to prevent Netlify build interference.

✨ NEW: Boots Straight to Offline Starfield#

The ISO now boots directly to offline starfield - no internet required!

Bundled offline pieces: starfield, notepat, roz
See OFFLINE-MODE.md for configuration

Goals#

Build FFOS ISO locally from a fork of feral-file/ffos + feral-file/ffos-user.
Keep all external repos out of the monorepo (no submodules).
Keep Netlify builds safe (no extra top‑level build steps).
Verify ISO integrity before flashing to USB.

What it does#

Clones FFOS + FFOS-USER into a local cache directory (.ffos-cache/).
Applies optional overlay patches from overlays/ (example: AC kiosk service).
Runs mkarchiso inside an Arch Linux container to produce an ISO.
Generates SHA256 checksums for built ISOs.
Verifies SquashFS integrity to catch corruption early.

Quick Start#

# From repo root
bash utilities/ffos-build/build.sh

Verify & Flash ISO#

After building (or downloading) an ISO, use the verification tool:

# Verify ISO integrity only
bash utilities/ffos-build/verify-iso.sh --verify-only path/to/FF1.iso

# Verify and flash to USB
bash utilities/ffos-build/verify-iso.sh path/to/FF1.iso /dev/sdb

The verification tool:

Checks SHA256 against .sha256 file (generates one if missing)
Validates SquashFS inside the ISO (catches xz decompression issues)
Safely writes to USB with progress and verification
Verifies the write by comparing first 4MB

Common Installation Errors This Prevents#

If you see these during FFOS installation, the ISO is corrupted:

SQUASHFS error: Failed to read block
xz decompression failed, data probably corrupt
rsync error: some files/attrs were not transferred
p11-kit failed verification

Always run verify-iso.sh before flashing!

GitHub Actions#

A workflow is provided to build the ISO on GitHub runners and upload the ISO as an artifact:

.github/workflows/ffos-local-iso.yml

Outputs#

ISO artifacts will be written to:
- utilities/ffos-build/.ffos-cache/out/

Configure#

Set env vars as needed:

FFOS_REPO (default: https://github.com/feral-file/ffos.git)
FFOS_USER_REPO (default: https://github.com/feral-file/ffos-user.git)
FFOS_BRANCH (default: develop)
FFOS_USER_BRANCH (default: develop)
FFOS_VERSION (optional)

Example:

FFOS_BRANCH=develop FFOS_USER_BRANCH=develop bash utilities/ffos-build/build.sh

Netlify Safety#

This pipeline does not add submodules and does not modify Netlify config. The cache directory is ignored in git.

Notes#

mkarchiso requires root; we run it inside Docker.
This is prototype tooling. Expect iteration.

Included overlay: Aesthetic Computer kiosk#

This repo ships an overlay that adds:

start-aesthetic-kiosk.sh
aesthetic-kiosk.service

Paths:

overlays/ffos-user/users/feralfile/scripts/start-aesthetic-kiosk.sh
overlays/ffos-user/users/feralfile/.config/systemd/user/aesthetic-kiosk.service

Enablement depends on the FFOS image; you may still need to enable the user service:

systemctl --user enable --now aesthetic-kiosk.service