Skip to content

Development

Welcome to Bazzite AI development! This guide will help you set up your development environment and understand the project workflow.

Quick Start

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

# 2. Install pre-commit hooks (REQUIRED)
just lint-install

# 3. Enable overlay testing
just overlay enable

# 4. Make changes and test
# Edit files in just/bazzite-ai/ or just/bazzite-ai-dev/
ujust <your-command>  # Test your changes

# 5. Commit when ready
git add .
git commit -m "Feat: your changes here"

Pre-commit Hooks Required

Step 2 installs mandatory validation hooks. Skip it and your commits will fail CI!

just vs ujust Commands

Bazzite AI has two command entry points with different purposes:

Command Entry Point Purpose
just ./justfile (repo root) Development - build, test, clean, docs
ujust /usr/share/ublue-os/justfile User - services, configuration

Development Commands (just)

For building, testing, and maintaining the project. Run from repository root.

Category Examples
Build just build os, just build pod nvidia, just build iso
Clean just clean all, just clean podman, just clean cache
Docs just docs build, just docs serve
Test just overlay enable, just overlay refresh
LFS just lfs checkout, just lfs verify
Record just record pods, just record all

See Dev Commands Reference for complete documentation.

User Commands (ujust)

For using Bazzite AI features. Run from anywhere on the system.

Category Examples
Pods ujust ollama start, ujust jupyter start
K8s ujust k3d config, ujust deploy jupyterhub
VMs ujust vm add myvm, ujust bootc start
Config ujust config docker enable, ujust install all

See Commands Reference for complete documentation.

Rule of Thumb

Developing bazzite-ai? Use just (development commands) Using bazzite-ai features? Use ujust (system commands)

Development Workflow

1. Setup Overlay Testing

Overlay testing lets you edit justfiles and test changes without rebuilding the OS image.

# One-time setup
just overlay enable

# After editing justfiles
just overlay refresh

# Test your changes
ujust <command> <action>

2. Edit Source Files

What to Edit Location
User commands just/bazzite-ai/*.just
Dev commands just/bazzite-ai-dev/*.just
System files system_files/usr/share/
Container builds Containerfile, pods/
Documentation docs/

3. Validate Before Commit

# Run all linters
pre-commit run --all-files

# Check justfile syntax
just check

4. Commit with Proper Format

Type: Short description

Optional body explaining why.

Assisted-by: Claude (fully tested and validated)

Types: Fix:, Feat:, Docs:, Chore:, Refactor:, Style:, Perf:, Test:

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)

Configuration Files

Do Not Edit ~/.config Directly

Configuration files in ~/.config/ are generated outputs. Edit the source code that generates them instead.

Correct workflow:

# 1. Edit source
vim just/bazzite-ai/*.just

# 2. Regenerate config
ujust <command> config

# 3. Verify
systemctl --user status <service>

Tech Stack

Component Tool Purpose
Build System Just + Podman Task runner + container builds
OS Runtime Fedora Atomic Desktop Immutable OS (OSTree)
Python/Docs Pixi Conda-forge package manager
CI/CD GitHub Actions Self-hosted runners (GPU)
Documentation MkDocs Material Documentation site
Validation Pre-commit Hooks (ShellCheck, yamllint, etc.)

Git Workflow

Branch Strategy

Branch Purpose Protection
main Stable releases Protected (no direct commits)
testing Development Open
feature/* Feature branches Open

AI Attribution (Required)

Per Fedora AI Contribution Policy, AI-assisted contributions must include attribution:

Assisted-by: Claude (fully tested and validated)
Confidence When to Use
fully tested and validated Overlay testing + all standards met
analysed on a live system Live system observation
syntax check only Pre-commit passed only

Further Reading

Document Description
Development Policies 10 core policies for code quality
AI Enforcement Subagent system and enforcement triggers
Justfile Patterns Just 1.46.0 syntax and command patterns
Submodule Workflow Managing git submodules
Dev Commands Development command reference
Testing Framework Automated testing documentation

Repository Structure

bazzite-ai/
├── build_files/          # Build scripts
├── pods/                 # Pod container definitions
├── plugins/              # Claude Code plugins
├── system_files/         # Files copied to OS image
├── just/
│   ├── bazzite-ai/       # ujust commands (user)
│   └── bazzite-ai-dev/   # just commands (development)
├── docs/                 # Documentation (this site)
├── Containerfile         # OS image build definition
├── justfile              # Development task runner
└── CLAUDE.md             # Development policies

Getting Help