Skip to content

Development

This section covers contributing to Bazzite AI and building custom images.

Quick Start for Contributors

# 1. Clone repository
git clone https://github.com/atrawog/bazzite-ai.git
cd bazzite-ai/bazzite-ai

# 2. Install development environment (REQUIRED)
ujust install-dev-environment

# 3. Verify hooks installed
ujust verify-hooks

# 4. Make changes and commit
git add .
git commit -m "Feat: your changes here"

Pre-commit Hooks Required

Skip step 2 and your commits will fail CI validation!

Development Guides

Key Concepts

Immutable OS

Bazzite AI is built on Fedora Atomic Desktop with OSTree:

  • /usr is read-only at runtime
  • Changes require rebuilding the image or using overlay testing
  • Updates are atomic (complete or rollback)

Testing Changes

Use overlay testing for iterative development:

# Enable overlay mode
just test overlay enable

# Test your changes
ujust <your-command>

# Disable when done
just test overlay disable

Commit Messages

Use semantic prefixes:

  • Fix: - Bug fix
  • Feat: - New feature
  • Docs: - Documentation only
  • Refactor: - Code restructure
  • Test: - Adding/updating tests
  • Chore: - Maintenance tasks

Repository Structure

bazzite-ai/
├── build_files/          # Build scripts
│   ├── shared/           # Scripts used by OS and pods
│   └── os/               # OS-specific scripts
├── pods/                 # Pod container definitions
│   ├── base/
│   ├── nvidia/
│   ├── nvidia-python/
│   ├── jupyter/
│   ├── devops/
│   ├── playwright/
│   └── githubrunner/
├── system_files/         # Files copied to OS image
│   └── usr/share/        # ujust commands, configs
├── docs/                 # Documentation (this site)
├── Containerfile         # OS image build definition
├── justfile              # Task runner commands
└── CLAUDE.md             # Development policies

Getting Help