Skip to main content

Contributing

bootc-installer is a GTK4/Libadwaita Flatpak installer for bootc container-native OS images, backed by the fisherman Go install backend.

Getting started​

git clone --recurse-submodules https://github.com/projectbluefin/bootc-installer
cd bootc-installer

Important: fisherman is a git submodule. Always clone with --recurse-submodules, or run git submodule update --init --recursive after a plain clone. Without this, fisherman/ is empty and all build paths fail immediately.

Prerequisites​

  • flatpak + org.flatpak.Builder — for the recommended Flatpak build
  • meson, ninja — for native (non-Flatpak) builds
  • Go ≥ 1.22 — for fisherman (the install backend, in the submodule)
  • Python ≥ 3.10 — for the GUI codebase
  • libadwaita-1-dev, gettext, desktop-file-utils, libgnome-desktop-4-dev

Building​

git submodule update --init --recursive   # Required — fisherman is a submodule
flatpak run org.flatpak.Builder --force-clean --user --install _build flatpak/org.bootcinstaller.Installer.json
flatpak run org.bootcinstaller.Installer

Meson (development)​

git submodule update --init --recursive   # Required — fisherman is a submodule
meson setup build
ninja -C build
sudo ninja -C build install
bootc-installer

Dev loop​

./run-dev.sh                               # Rebuild and launch with BOOTC_DEMO=1 (no disk writes)
BOOTC_PREVIEW_SCREEN=confirm ./run-dev.sh  # Jump to a specific screen

Running tests​

pytest tests/unit/ -q                           # Unit tests (no display required)
xvfb-run -a pytest tests/ui/ -q                 # UI tests
python3 -m ruff check bootc_installer/ tests/   # Lint
./QUALIFY_SOFTWARE.sh                           # Full qualification suite

CI gate: --cov-fail-under=51 (minimum unit test coverage).

Branch workflow​

  • Default branch: dev
  • Open all PRs against dev — do not target main
  • Follow Conventional Commits for commit messages
  • PR title format: feat:, fix:, docs:, chore:, ci:

Adding images to the catalog​

The image catalog lives in fisherman/data/images.json. See the README for the full JSON schema.

fisherman/ is a git submodule pointing to projectbluefin/fisherman. Changes to the catalog must be committed and pushed separately to the fisherman repo, then the submodule pointer updated here.

Architecture overview​

ComponentLanguageRole
fisherman/fisherman/GoRoot-level CLI; reads JSON recipe, executes 9-step disk install pipeline
bootc_installer/PythonGTK4/Adwaita GUI; collects user choices, writes recipe JSON, drives fisherman

See CLAUDE.md and AGENTS.md for deeper architecture documentation.

Code style​

  • Python: Ruff (python3 -m ruff check)
  • Go: gofmt + go vet
  • Commit messages: Conventional Commits

Security​

Report vulnerabilities via GitHub Private Vulnerability Reporting. Do not open public issues for security bugs.