---

name: build description: | Development: Unified build system for OS images, pods, VMs, and ISOs. Run from repository root with 'just build '. Includes smart cache strategy that matches GitHub Actions for optimal build times.

Build - Unified Build System

Overview

The build command provides a unified interface for all bazzite-ai build operations:

• OS container images
• Pod container variants
• VM images (QCOW2/RAW)
• Live ISO installers
• Push to registry
• Sign with cosign

Smart Caching: Automatically detects git branch and uses matching cache tag, ensuring local builds are compatible with GitHub Actions builds.

Quick Reference

Pod Variants

Smart Cache Strategy

The build system automatically detects your git branch and uses the appropriate cache tag to maximize cache reuse between local and CI builds:

This ensures that when you build locally on the testing branch, you pull cache layers from the :testing images pushed by GitHub Actions.

Environment Variables

For CI integration, the following environment variables are supported:

Common Workflows

Build OS Image

Copy# Build with branch-appropriate tag
just build os

# Build with custom tag
just build os custom-tag

Build Pods

Copy# Interactive selection
just build pod

# Specific variant
just build pod nvidia

# All variants
just build pod all

Build VM/ISO

Copy# Build QCOW2 VM image
just build qcow2

# Build live ISO
just build iso

# Build RAW image
just build raw

Push to Registry

Copy# Push OS image
just build push os

# Push specific pod
just build push pod nvidia

# Push all pods
just build push pod all

Sign Images

Copy# Sign OS image (requires COSIGN_PRIVATE_KEY env var)
COSIGN_PRIVATE_KEY=$KEY just build sign os

# Sign pod
COSIGN_PRIVATE_KEY=$KEY just build sign pod nvidia

Generate Pixi Locks

Copy# Python variant
just build pixi python

# Jupyter variant
just build pixi jupyter

# All variants
just build pixi all

CI Integration

The build commands are designed for GitHub Actions integration:

Copy# Build, push, and sign in CI
- name: Build and push OS
  env:
    BUILD_LABELS: ${{ steps.metadata.outputs.labels }}
    COSIGN_PRIVATE_KEY: ${{ secrets.SIGNING_SECRET }}
  run: |
    just build os $TAG
    just build push os $TAG
    just build sign os $TAG

# Build pod with base image digest
- name: Build nvidia pod
  env:
    BASE_IMAGE: ghcr.io/owner/bazzite-ai-pod@${{ needs.base.outputs.digest }}
  run: just build pod nvidia $TAG

Output Images

Images are tagged with the registry prefix:

Copyghcr.io/atrawog/bazzite-ai:{tag}           # OS image
ghcr.io/atrawog/bazzite-ai-pod:{tag}       # Base pod
ghcr.io/atrawog/bazzite-ai-pod-nvidia:{tag} # NVIDIA pod
ghcr.io/atrawog/bazzite-ai-pod-comfyui:{tag} # ComfyUI pod

Requirements

• Podman installed and configured
• Git repository cloned
• Sufficient disk space (~10GB for OS, ~20GB for ISO)
• Network access (pulls base images)
• cosign installed (for signing)
• Registry authentication (for push)

Troubleshooting

Build Fails with Cache Error

Symptom: Cache layer not found

Cause: Remote image not yet pushed for this branch

Fix:

Copy# Build without cache (first build on new branch)
# Or check status to see cache state
just build status

Pod Build Fails with Base Image Missing

Symptom: Cannot find base pod image

Cause: Parent variant not built

Fix:

Copy# Build in order (base -> nvidia -> jupyter)
just build pod base
just build pod nvidia
just build pod jupyter

Push Fails with Authentication Error

Symptom: unauthorized: authentication required

Cause: Not logged into registry

Fix:

Copy# Login to GitHub Container Registry
podman login ghcr.io

Sign Fails

Symptom: cosign not found or key not set

Cause: cosign not installed or COSIGN_PRIVATE_KEY not set

Fix:

Copy# Check cosign is installed
which cosign

# Set signing key
export COSIGN_PRIVATE_KEY="$(cat cosign.key)"

CUDA Test Fails

Symptom: nvidia-smi not found

Cause: No GPU available or CDI not configured

Fix:

Copy# Verify GPU on host
nvidia-smi

# Check CDI configuration
ls /etc/cdi/

Cross-References

• Related Skills: clean (cleanup build artifacts)
• System Commands: ujust jupyter, ujust ollama (use built pods)
• Documentation: See Containerfile for image layers

When to Use This Skill

Use when the user asks about:

• "build os", "build image", "build container"
• "build pod", "build nvidia", "build jupyter", "build comfyui"
• "build iso", "build qcow2", "build vm"
• "push os", "push pod", "push to registry"
• "sign image", "cosign", "sign pod"
• "pixi lock", "generate lock"
• "just build" (any build command)