From c2000ce8b9cb1694fda778dcee0850960db7d6f7 Mon Sep 17 00:00:00 2001 From: Juha Uotila <10782843+inffy@users.noreply.github.com> Date: Sat, 5 Sep 2026 09:18:00 +0300 Subject: [PATCH] chore: rename ISO filenames --- .github/workflows/promote-iso.yml | 1 + .../workflows/reusable-build-iso-anaconda.yml | 2 +- CONTRIBUTING.md | 304 ++++++++++++++++++ README.md | 210 +++++++++--- 4 files changed, 472 insertions(+), 45 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.github/workflows/promote-iso.yml b/.github/workflows/promote-iso.yml index 9dc4634..189f084 100644 --- a/.github/workflows/promote-iso.yml +++ b/.github/workflows/promote-iso.yml @@ -63,6 +63,7 @@ jobs: echo "Promoting ISOs from Test to Production" /home/linuxbrew/.linuxbrew/bin/rclone sync R2_TEST:aurora-dl-test R2_PROD:aurora-dl \ --filter "- *-testing-*" \ + --filter "- *-webui-*" \ --filter "+ *.iso" \ --filter "+ *.iso-CHECKSUM" \ --filter "- *" \ diff --git a/.github/workflows/reusable-build-iso-anaconda.yml b/.github/workflows/reusable-build-iso-anaconda.yml index 870e40e..7ff9d44 100644 --- a/.github/workflows/reusable-build-iso-anaconda.yml +++ b/.github/workflows/reusable-build-iso-anaconda.yml @@ -75,7 +75,7 @@ jobs: image_ref="${IMAGE_REGISTRY}/${image_name}" KARGS="NONE" echo "image_ref=$image_ref" >> "${GITHUB_OUTPUT}" - echo "artifact_format=${image_name}-${IMAGE_VERSION}-webui-$(uname -m)" >> "${GITHUB_OUTPUT}" + echo "artifact_format=${image_name}-${IMAGE_VERSION}-$(uname -m)" >> "${GITHUB_OUTPUT}" echo "kargs=$KARGS" >> "${GITHUB_OUTPUT}" - name: Generate titanoboa-compatible file list diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..98437c0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,304 @@ +# Contributing to Aurora ISO Builder + +Thank you for your interest in contributing to Aurora ISO Builder! This guide will help you get started with contributing to the project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Making Changes](#making-changes) +- [Testing](#testing) +- [Submitting Changes](#submitting-changes) +- [Style Guide](#style-guide) +- [Resources](#resources) + +## Code of Conduct + +This project follows the [Universal Blue Code of Conduct](https://universal-blue.org/CODE_OF_CONDUCT/). By participating, you are expected to uphold this code. + +## Getting Started + +### Prerequisites + +Before you begin, ensure you have the following tools installed: + +- **Git**: Version control +- **Pre-commit**: For running validation hooks +- **Bash**: For running scripts + +### Installation + +```bash +# Install pre-commit +pip install pre-commit + +# Clone the repository +git clone https://github.com/ublue-os/aurora-iso.git +cd aurora-iso + +# Install pre-commit hooks +pre-commit install +``` + +## Development Setup + +1. **Fork the repository** on GitHub +2. **Clone your fork** locally: + ```bash + git clone https://github.com/YOUR_USERNAME/aurora-iso.git + cd aurora-iso + ``` +3. **Add upstream remote**: + ```bash + git remote add upstream https://github.com/ublue-os/aurora-iso.git + ``` +4. **Install pre-commit hooks**: + ```bash + pre-commit install + ``` + +## Making Changes + +### Branch Naming + +Create a descriptive branch name: +- `feat/add-new-feature` - For new features +- `fix/bug-description` - For bug fixes +- `docs/update-readme` - For documentation changes +- `chore/update-deps` - For maintenance tasks + +### Commit Messages + +We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for all commit messages: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +**Types:** +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation changes +- `chore`: Maintenance tasks +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `ci`: CI/CD changes + +**Examples:** +``` +feat: add support for custom kernel arguments + +fix: correct Anaconda profile partitioning scheme + +docs: update README with new ISO variants + +chore: update pre-commit hooks to v5.0.0 +``` + +### Attribution Footer + +If using AI assistance, include an attribution footer: + +``` +feat: improve ISO configuration script + +Assisted-by: Claude 3.5 Sonnet via Zed AI +``` + +## Testing + +### Local Validation + +Always validate your changes before committing: + +```bash +# Run all pre-commit hooks +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 Build Testing + +ISO builds are automatically triggered on pull requests. The workflow will: +1. Build ISOs for all configured flavors +2. Generate checksums +3. Upload artifacts to GitHub + +You can download and test the generated ISOs from the GitHub Actions artifacts. + +### Manual Testing + +To manually test the ISO configuration script: + +```bash +# Validate bash syntax +bash -n iso_files/configure_iso_anaconda-webui.sh +``` + +## Submitting Changes + +### Before Submitting + +1. **Sync with upstream**: + ```bash + git fetch upstream + git rebase upstream/main + ``` + +2. **Run validation**: + ```bash + pre-commit run --all-files + bash -n iso_files/configure_iso_anaconda.sh + bash -n iso_files/build.sh + ``` + +3. **Test your changes**: Ensure the ISO builds successfully in GitHub Actions + +### Pull Request Process + +1. **Push your changes**: + ```bash + git push origin your-branch-name + ``` + +2. **Create a Pull Request** on GitHub with: + - Clear title using conventional commit format + - Detailed description of changes + - Link to related issues (if applicable) + - Screenshots or logs (if relevant) + +3. **Wait for CI checks** to complete: + - Pre-commit hooks + - ISO build (if workflow files changed) + +4. **Address review feedback** if requested + +5. **Squash commits** if requested by maintainers + +### Pull Request Template + +```markdown +## Description +Brief description of what this PR does. + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Documentation update +- [ ] Maintenance/chore + +## Testing +- [ ] Ran pre-commit hooks +- [ ] Tested ISO configuration script syntax +- [ ] ISO builds successfully in GitHub Actions + +## Related Issues +Closes #123 + +## Additional Notes +Any additional context or notes for reviewers. +``` + +## Style Guide + +### Shell Scripts + +- Use `#!/usr/bin/bash` or `#!/usr/bin/env bash` shebang +- Use `set -eoux pipefail` for strict error handling +- Quote variables: `"${VARIABLE}"` +- Use meaningful variable names in UPPER_CASE +- Add comments for complex logic +- Follow existing patterns in `iso_files/configure_iso_anaconda-webui.sh` + +**Example:** +```bash +#!/usr/bin/bash +set -eoux pipefail + +readonly IMAGE_NAME="aurora" +readonly IMAGE_VERSION="stable" + +if [[ -n "${IMAGE_NAME}" ]]; then + echo "Building ISO for ${IMAGE_NAME}" +fi +``` + +### YAML Files + +- Use 2 spaces for indentation +- Quote strings when necessary +- Use `---` document separator +- Keep workflows readable with descriptive names + +### Markdown + +- Use descriptive headings +- Include code blocks with language specification +- Keep lines under 120 characters when possible +- Use relative links for internal documentation + +## Common Tasks + +### Adding New ISO Configuration + +1. Edit `iso_files/configure_iso_anaconda-webui.sh` +2. Test syntax: `bash -n iso_files/configure_iso_anaconda-webui.sh` +3. Create PR with changes +4. Wait for ISO build to complete +5. Test the generated ISO + +### Modifying Flatpak Lists + +1. Flatpaks are defined in Brewfiles in the get-aurora-dev/common repository +2. Edit `*system-flatpaks.Brewfile` in the common repository +3. Flatpaks are dynamically extracted during ISO build +4. Format: `flatpak "app.id.here"` + +### Updating Workflows + +1. Edit workflow file in `.github/workflows/` +2. Validate YAML syntax: `pre-commit run check-yaml` +3. Create PR and monitor workflow execution +4. Ensure all checks pass + +## Resources + +### Documentation +- [Aurora Documentation](https://docs.getaurora.dev/) +- [Universal Blue Docs](https://universal-blue.org/) +- [Titanoboa](https://github.com/ublue-os/titanoboa) - ISO builder + +### Community +- [Discourse Forums](https://universal-blue.discourse.group/c/aurora/11) +- [GitHub Discussions](https://github.com/ublue-os/aurora/discussions) +- [Discord](https://discord.gg/universalblue) + +### Tools +- [Pre-commit](https://pre-commit.com/) +- [Conventional Commits](https://www.conventionalcommits.org/) + +## Getting Help + +If you need help: + +1. Check the [documentation](https://docs.getaurora.dev/) +2. Search existing [issues](https://github.com/ublue-os/aurora-iso/issues) +3. Ask in [Discourse forums](https://universal-blue.discourse.group/c/aurora/11) +4. Join our [Discord](https://discord.gg/universalblue) + +## Recognition + +Contributors are recognized in several ways: +- Listed in GitHub contributors +- Mentioned in release notes for significant contributions +- Acknowledged in project documentation + +Thank you for contributing to Aurora ISO Builder! 🚀 diff --git a/README.md b/README.md index 38d3c14..7872f91 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,20 @@ [![Build ISOs](https://github.com/get-aurora-dev/iso/actions/workflows/build-iso-stable.yml/badge.svg)](https://github.com/get-aurora-dev/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 -This repo creates installation media for [Aurora](https://getaurora.dev), these ISOs provide a live environment with the Anaconda WebUI installer and [plasma-setup](https://invent.kde.org/plasma/plasma-setup) which handles user creation and other things which have to be done on first boot. These ISOs are only compatible with UEFI and will not boot on systems with a legacy bios boot implementation. +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 @@ -12,8 +23,6 @@ Pre-built ISOs are available at [getaurora.dev](https://getaurora.dev). Testing ISOs are available [here](https://docs.getaurora.dev/guides/iso-testing). -Size usually ranges from 6GB to 8GB depending on the required runtimes by the preinstalled Flatpak applications and of course the container image size itself. - ## Verifying ISOs ### 1. Integrity Check (Checksum) @@ -21,80 +30,158 @@ Size usually ranges from 6GB to 8GB depending on the required runtimes by the pr You can verify the SHA256 checksum of your downloaded ISO against the published checksum file: ```bash -sha256sum --check .iso-CHECKSUM +sha256sum -c .iso-CHECKSUM ``` -Example: +### 2. Provenance Attestation (GitHub Actions) + +All official ISOs built via GitHub Actions include signed cryptographic build provenance attestations. You can verify that the ISO was built and published directly by this repository using the [GitHub CLI (`gh`)](https://cli.github.com/): ```bash -sha256sum --check aurora-stable-webui-x86_64.iso-CHECKSUM -aurora-stable-webui-x86_64.iso: OK +gh attestation verify .iso --owner get-aurora-dev ``` -### 2. Provenance Attestation (GitHub Actions) - -All official ISOs built via GitHub Actions include signed cryptographic build provenance attestations. You can verify that the ISO was built and published directly by the Aurora team by using the [GitHub CLI (`gh`)](https://cli.github.com/): +Or by specifying the repository directly: ```bash -gh attestation verify .iso --owner get-aurora-dev +gh attestation verify .iso --repo get-aurora-dev/iso ``` -Example: +## Repository Structure ``` -gh attestation verify aurora-stable-webui-x86_64.iso --owner get-aurora-dev -Loaded digest sha256:5738320c906bdbae6fbb87be7bc0e30cc11cc6975916a0e28da9086641513f22 for file://aurora-stable-webui-x86_64.iso -Loaded 1 attestation from GitHub API +. +├── .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 +``` -The following policy criteria will be enforced: -- Predicate type must match:................ https://slsa.dev/provenance/v1 -- Source Repository Owner URI must match:... https://github.com/get-aurora-dev -- Subject Alternative Name must match regex: (?i)^https://github\.com/get-aurora-dev/ -- OIDC Issuer must match:................... https://token.actions.githubusercontent.com +## Building ISOs -✓ Verification succeeded! +### Prerequisites -The following 1 attestation matched the policy criteria +ISOs are built using GitHub Actions, but you can validate your changes locally: -- Attestation #1 -- Build repo:..... get-aurora-dev/iso -- Build workflow:. .github/workflows/build-iso-stable.yml@refs/heads/gh-readonly-queue/main/pr-85-3c092658d6fa47a1702442a7fc1c614a38ede582 -- Signer repo:.... get-aurora-dev/iso -- Signer workflow: .github/workflows/reusable-build-iso-anaconda.yml@refs/heads/gh-readonly-queue/main/pr-85-3c092658d6fa47a1702442a7fc1c614a38ede582 +```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 -There will be no ISOs for [DX images](https://docs.getaurora.dev/dx/aurora-dx-intro). - ### Versions -- **stable**: Built on top of aurora:stable images -- **testing**: Built on top of aurora:testing images +- **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 -See the [release stream docs](https://docs.getaurora.dev/guides/release-streams). +The custom Aurora profile includes: -There will be no ISOs for `:latest` images. +- **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 Secure boot is supported by default. After installation, users are prompted to enroll the secure boot key with password: `universalblue` -## Build Overview +## GitHub Actions Workflow -1. Generate flatpak list dynamically via Brewfiles from [common repo](https://github.com/get-aurora-dev/common) -2. Build Container Image which is a regular aurora image tailored for the live environment -3. Generate ISO with Titanoboa which embeds a regular aurora image into the live environments container storage -4. Generate checksums and build provenance attestations -5. Upload to CloudFlare R2 test bucket (scheduled builds) or GitHub artifacts for PRs +### 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 and build provenance attestations +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: @@ -110,6 +197,36 @@ To promote ISOs 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/) @@ -121,10 +238,15 @@ To promote ISOs to production: - [Aurora Website](https://getaurora.dev) - [Aurora Repository](https://github.com/ublue-os/aurora) - [Universal Blue](https://universal-blue.org) -- [Discussions](https://github.com/ublue-os/aurora/discussions) +- [Discussions](https://universal-blue.discourse.group/c/aurora/11) + +## License + +Apache-2.0 ## Acknowledgments -- [Titanoboa](https://github.com/ublue-os/titanoboa) for ISO creation -- [Anaconda WebUI](https://github.com/rhinstaller/anaconda-webui) for the installer -- [Slitherer](https://gitlab.com/VelocityLimitless/Projects/slitherer) for providing the runner used by Anaconda +- 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