mirror-get-aurora-dev-iso/README.md

# Aurora ISO Builder

[![Build ISOs](https://github.com/ublue-os/aurora-iso/actions/workflows/build-iso-stable.yml/badge.svg)](https://github.com/ublue-os/aurora-iso/actions/workflows/build-iso-stable.yml)

This repository is dedicated to building bootable Aurora ISOs using [Titanoboa](https://github.com/ublue-os/titanoboa) and the Anaconda installer with WebUI.

## Overview

Aurora ISO Builder creates installation media for [Aurora](https://getaurora.dev), 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](https://getaurora.dev).

Testing ISOs are available [here](https://docs.getaurora.dev/guides/iso-testing).

## 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
├── iso_files/
│   ├── configure_iso_anaconda.sh                   # ISO configuration script
│   └── scope_installer.png                         # Installer branding
├── .pre-commit-config.yaml                         # Pre-commit hooks
└── README.md                                       # This file
```

## Building ISOs

### Prerequisites

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

```bash
# Install pre-commit
pip install pre-commit
pre-commit install
```

### Validation

Before submitting changes, validate your code:

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

# Test ISO configuration script syntax
bash -n iso_files/configure_iso_anaconda.sh
bash -n iso_files/build.sh
```

## 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. Format image reference
4. Generate flatpak list dynamically from Brewfiles in common repo
5. Build ISO with Titanoboa
6. Generate checksums
7. 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: `pre-commit run --all-files`
2. Test ISO script syntax: `bash -n iso_files/configure_iso_anaconda.sh && bash -n iso_files/build.sh`
3. Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification)
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](https://docs.getaurora.dev/)
- [Universal Blue Docs](https://universal-blue.org/)
- [Titanoboa](https://github.com/ublue-os/titanoboa) - ISO builder tool

## Resources

- [Aurora Website](https://getaurora.dev)
- [Aurora Repository](https://github.com/ublue-os/aurora)
- [Universal Blue](https://universal-blue.org)
- [Discussions](https://universal-blue.discourse.group/c/aurora/11)

## License

Apache-2.0

## Acknowledgments

- Built on [Universal Blue](https://universal-blue.org) infrastructure
- Uses [Titanoboa](https://github.com/ublue-os/titanoboa) for ISO creation
- Based on [Fedora Kinoite](https://fedoraproject.org/kinoite/)
- Powered by the [ublue-os](https://github.com/ublue-os) community