Aurora ISO Builder

This repository is dedicated to building bootable Aurora ISOs using Titanoboa and the Anaconda installer with WebUI.

Overview

Aurora ISO Builder creates installation media for Aurora, a delightful KDE desktop experience built on Universal Blue. These ISOs provide a live environment with the Anaconda WebUI installer for easy installation of Aurora.

Features

• Live Environment: Boots into a fully functional Aurora desktop
• Anaconda WebUI Installer: Modern web-based installation experience
• Multiple Flavors: Support for standard and NVIDIA Open variants
• Pre-configured: Optimized BTRFS partitioning, secure boot support, flatpak integration
• Test & Production Pipeline: ISOs are built to test bucket, then promoted to production
• Manual Promotion: Controlled release process with dry-run capability

Download

Pre-built ISOs are available at getaurora.dev.

Repository Structure

.
├── .github/
│   └── workflows/
│       ├── build-iso-stable.yml                    # Caller workflow for stable ISOs
│       ├── reusable-build-iso-anaconda.yml         # Reusable ISO build workflow
│       ├── promote-iso.yml                         # ISO promotion workflow
│       └── validate-just.yml                       # Justfile validation
├── iso_files/
│   ├── configure_iso_anaconda.sh                   # ISO configuration script
│   └── scope_installer.png                         # Installer branding
├── .pre-commit-config.yaml                         # Pre-commit hooks
├── AGENTS.md                                       # AI agent documentation
├── Justfile                                        # Build automation recipes
└── README.md                                       # This file

Building ISOs

Prerequisites

ISOs are built using GitHub Actions, but you can validate your changes locally:

# Install Just command runner
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

# Install pre-commit
pip install pre-commit
pre-commit install

Validation

Before submitting changes, validate your code:

# Check all syntax and formatting
pre-commit run --all-files

# Validate Justfile syntax
just check

# Test ISO configuration script
just test-iso-config

# Auto-fix formatting issues
just fix

Available Just Recipes

# List all available recipes
just --list

# Clean build artifacts
just clean

# Clone common repository (flatpak lists)
just clone-common

# Generate flatpak list from common repo
just generate-flatpak-list

# Get image name for specific combination
just image_name aurora stable main

# Validate image/tag/flavor combination
just validate aurora stable nvidia-open

ISO Variants

Flavors

• main: Standard Aurora ISO with open-source drivers
• nvidia-open: Aurora ISO with NVIDIA Open kernel modules

Versions

• stable: Latest stable Fedora release (recommended)
• latest: Current Fedora release

Configuration

ISO Customization

The ISO is customized via iso_files/configure_iso_anaconda.sh:

• Installs Anaconda WebUI installer
• Configures Aurora-specific Anaconda profile
• Sets up BTRFS partitioning with zstd compression
• Adds installer to KDE panel and kickoff menu
• Configures secure boot key enrollment
• Pre-installs flatpaks (dynamically generated from Brewfiles)

Anaconda Profile

The custom Aurora profile includes:

• Storage: BTRFS with zstd:1 compression
• Partitioning:
  • / (1 GiB min, 70 GiB max)
  • /home (500 MiB min, 50 GiB free)
  • /var (BTRFS)
• Network: First wired connection auto-enabled
• Bootloader: Fedora EFI directory, auto-hide menu

Secure Boot

Secure boot is supported by default. After installation, users are prompted to enroll the secure boot key with password: universalblue

GitHub Actions Workflow

ISO Build Workflow

Triggers

• Pull Requests: Builds ISOs for validation (no uploads)
• Workflow Dispatch: Manual triggering with configurable upload options
• Schedule: Weekly on Tuesdays at 03:15 AM UTC (2 hours after Aurora publishes weekly builds)

Build Matrix

The workflow builds ISOs for:

• Platform: amd64
• Flavors: main, nvidia-open
• Version: stable

Workflow Steps

1. Maximize build space (removes unnecessary software)
2. Checkout repository
3. Validate Just syntax
4. Format image reference
5. Generate flatpak list dynamically from Brewfiles in common repo
6. Build ISO with Titanoboa
7. Generate checksums
8. Upload to CloudFlare R2 test bucket (scheduled builds) or GitHub artifacts (configurable via inputs)

Upload Behavior

• PR builds: No uploads (validation only)
• Scheduled builds: Upload to CloudFlare R2 test bucket (aurora-dl-test)
• Manual dispatch: Configurable via upload_artifacts and upload_r2 inputs

ISO Promotion Workflow

The promotion workflow (promote-iso.yml) copies ISOs from the test bucket to production.

Triggers

• Workflow Dispatch: Manual triggering only

Inputs

• dry_run: (default: true) Preview changes without copying files

Workflow Steps

1. Install rclone
2. Configure test bucket (source) and production bucket (destination)
3. List files in test bucket for verification
4. Promote ISOs and checksums (with rclone sync)
5. Verify files in production bucket (if not dry-run)

Usage

To promote ISOs to production:

1. Go to Actions → Promote ISOs to Production
2. Click "Run workflow"
3. First run with dry_run = true to preview changes
4. Review the dry-run output
5. Run again with dry_run = false to execute promotion

Note: The promotion workflow uses rclone sync, which will:

• Copy new files from test to production
• Update existing files if changed
• Remove ISO and CHECKSUM files from production that don't exist in test (subject to the rclone include filters)

Contributing

Contributions are welcome! Please follow these guidelines:

Before Committing

1. Run validation: just check && pre-commit run --all-files
2. Test ISO script syntax: just test-iso-config
3. Use conventional commits
4. Keep changes minimal and focused

Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run validation locally
5. Submit a pull request
6. Wait for ISO build to complete in GitHub Actions
7. Test the generated ISO if needed

Common Changes

• Branding: Update images in iso_files/
• Anaconda config: Edit profile in configure_iso_anaconda.sh
• Flatpak lists: Modify Brewfiles in get-aurora-dev/common repository
• Partitioning: Modify default_partitioning in Anaconda profile
• Live environment: Add/remove packages in configuration script
• Workflow: Update .github/workflows/reusable-build-iso-anaconda.yml or promote-iso.yml

Documentation

• Aurora Documentation
• Universal Blue Docs
• AGENTS.md - Comprehensive guide for AI-assisted development
• Titanoboa - ISO builder tool

Resources

• Aurora Website
• Aurora Repository
• Universal Blue
• Discussions

License

Apache-2.0

Acknowledgments

• Built on Universal Blue infrastructure
• Uses Titanoboa for ISO creation
• Based on Fedora Kinoite
• Powered by the ublue-os community