bringup the repository (#4)

2026-11-03 21:49:46 -09:00 · 2026-01-11 12:33:57 +02:00 · 2026-01-11 12:33:57 +02:00 · bbfb72a83d
commit bbfb72a83d
parent 455de11be2
10 changed files with 1190 additions and 2 deletions
--- a/.github/workflows/build-iso-stable.yml
+++ b/.github/workflows/build-iso-stable.yml
@ -0,0 +1,19 @@
+name: Build Stable ISOs
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/build-iso-stable.yml"
+      - ".github/workflows/reusable-build-iso-anaconda-webui.yml"
+      - "iso_files/**"
+  schedule:
+    - cron: "0 2 1 * *" # First day of each month at 2:00 AM UTC
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  build-iso-stable:
+    name: Build Stable ISOs
+    uses: ./.github/workflows/reusable-build-iso-anaconda-webui.yml
+    secrets: inherit
--- a/.github/workflows/validate-just.yml
+++ b/.github/workflows/validate-just.yml
@ -0,0 +1,28 @@
+name: Validate Justfiles
+
+on:
+  pull_request:
+    paths:
+      - "Justfile"
+      - "just/*"
+  push:
+    branches:
+      - main
+    paths:
+      - "Justfile"
+      - "just/*"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+
+      - name: Setup Just
+        uses: extractions/setup-just@e33e0265a09d6d736e2ee1e0eb685ef1de4669ff # v3
+
+      - name: Check Just Syntax
+        shell: bash
+        run: |
+          just check
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,38 @@
+# Build artifacts
+output/
+*.iso
+*.iso-CHECKSUM
+*_build*
+
+# Cloned repositories
+common/
+
+# Temporary files
+*.log
+*.tmp
+flatpaks.list
+previous.manifest.json
+changelog.md
+output.env
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+venv/
+env/
+
+# Just
+.just/
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@ -0,0 +1,11 @@
+# .pre-commit-config.yaml
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+        - id: check-json
+        - id: check-toml
+        - id: check-yaml
+        - id: end-of-file-fixer
+        - id: trailing-whitespace
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,347 @@
+# Aurora ISO Build Copilot Instructions
+
+This document provides essential information for coding agents working with the Aurora ISO build repository to minimize exploration time and avoid common build failures.
+
+## Repository Overview
+
+**Aurora ISO** is a dedicated repository for building bootable Aurora ISOs using Titanoboa and the Anaconda installer with WebUI. This is a specialized build system focused solely on creating installation media.
+
+- **Type**: ISO build system for Aurora (KDE-based immutable OS)
+- **Base**: Uses pre-built Aurora container images from ghcr.io/ublue-os/aurora
+- **Languages**: Bash scripts, YAML configuration
+- **Build System**: Just (command runner), GitHub Actions, Titanoboa (ISO builder)
+- **Target**: Bootable installation ISOs for Aurora desktop OS
+
+## Repository Structure
+
+### Root Directory Files
+
+- `Justfile` - Build automation recipes for ISO tasks
+- `.pre-commit-config.yaml` - Pre-commit hooks for validation
+- `README.md` - Repository documentation
+- `AGENTS.md` - This file
+
+### Key Directories
+
+- `.github/workflows/` - GitHub Actions workflows for ISO building
+- `iso_files/` - ISO configuration and customization scripts
+  - `configure_iso_anaconda-webui.sh` - Main ISO configuration script
+  - `scope_installer.png` - Aurora installer icon/branding
+
+### Architecture
+
+- **Build Target**: Bootable live ISOs with Anaconda WebUI installer
+- **Image Flavors**: main, nvidia-open
+- **Fedora Versions**: 42, 43 supported
+- **Stream Tags**: `stable`, `latest`
+- **Build Process**: GitHub Actions → Titanoboa → ISO creation
+- **Base Images**: Uses `ghcr.io/ublue-os/aurora` as foundation
+
+## Build Instructions
+
+### Prerequisites
+
+**ALWAYS install these tools before attempting any builds:**
+
+```bash
+# Install Just command runner (REQUIRED for build commands)
+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 for validation
+pip install pre-commit
+```
+
+### Essential Commands
+
+**Build validation (ALWAYS run before making changes):**
+```bash
+# 1. Validate syntax and formatting (1-2 minutes)
+pre-commit run --all-files
+
+# 2. Check Just syntax (requires Just installation)
+just check
+
+# 3. Check ISO configuration script syntax
+just test-iso-config
+
+# 4. Fix formatting issues automatically
+just fix
+```
+
+**Utility commands:**
+```bash
+# Clean build artifacts
+just clean
+
+# List all available recipes
+just --list
+
+# Validate image/tag/flavor combinations
+just validate aurora stable main
+
+# Clone common repository (for flatpak lists)
+just clone-common
+
+# Generate flatpak list from common repo
+just generate-flatpak-list
+
+# Get image name for a specific combination
+just image_name aurora stable main
+# Output: aurora
+
+just image_name aurora stable nvidia-open
+# Output: aurora-nvidia-open
+```
+
+### Critical Build Notes
+
+1. **ISOs are built in GitHub Actions** - local builds are not supported by default
+2. **Always run `just check` before making changes** - catches syntax errors early
+3. **Pre-commit hooks are mandatory** - run `pre-commit run --all-files` to validate changes
+4. **ISO builds require significant resources** (40GB+ disk, 8GB+ RAM, 60+ minute runtime)
+5. **Test the configuration script syntax** with `just test-iso-config`
+
+### Common Build Failures & Workarounds
+
+**Pre-commit failures:**
+```bash
+# Fix end-of-file and trailing whitespace automatically
+pre-commit run --all-files
+```
+
+**Just syntax errors:**
+```bash
+# Auto-fix formatting
+just fix
+
+# Manual validation
+just check
+```
+
+**ISO configuration script errors:**
+```bash
+# Validate bash syntax
+just test-iso-config
+
+# Manual check
+bash -n iso_files/configure_iso_anaconda-webui.sh
+```
+
+## Validation Pipeline
+
+### Pre-commit Hooks (REQUIRED)
+
+The repository uses mandatory pre-commit validation:
+
+- `check-json` - Validates JSON syntax
+- `check-toml` - Validates TOML syntax
+- `check-yaml` - Validates YAML syntax
+- `end-of-file-fixer` - Ensures files end with newline
+- `trailing-whitespace` - Removes trailing whitespace
+
+**Always run:** `pre-commit run --all-files` before committing changes.
+
+### GitHub Actions Workflows
+
+- `reusable-build-iso-anaconda-webui.yml` - Main ISO build workflow
+  - Runs on: Pull requests, workflow dispatch, monthly schedule
+  - Builds ISOs for main and nvidia-open flavors
+  - Uploads to CloudFlare R2 for stable releases
+- `validate-just.yml` - Validates Justfile syntax
+
+**Workflow Architecture:**
+
+- ISO builds use Titanoboa action from ublue-os/titanoboa
+- Configuration happens in `configure_iso_anaconda-webui.sh`
+- Flatpaks are dynamically generated from Brewfiles in get-aurora-dev/common repository
+- ISOs are uploaded to CloudFlare R2 for distribution
+
+### Manual Validation Steps
+
+1. `pre-commit run --all-files` - Runs validation hooks (1-2 minutes)
+2. `just check` - Validates Just syntax (30 seconds)
+3. `just test-iso-config` - Validates ISO configuration script (5 seconds)
+4. `just fix` - Auto-fixes formatting issues (30 seconds)
+
+## ISO Configuration
+
+### Main Configuration Script
+
+The ISO is customized via `iso_files/configure_iso_anaconda-webui.sh`:
+The ISO includes a custom Anaconda profile at `/etc/anaconda/profile.d/aurora.conf`:
+
+**Key Customizations:**
+- Installs Anaconda WebUI installer (anaconda-webui, anaconda-live, firefox)
+- Configures Anaconda profile for Aurora
+- Sets up BTRFS partitioning scheme with compression
+- Adds installer to KDE panel and kickoff menu
+- Configures secure boot key enrollment
+- Installs flatpaks dynamically generated from Brewfiles
+- Disables unnecessary services in live environment
+
+**Making Configuration Changes:**
+
+1. Edit `iso_files/configure_iso_anaconda-webui.sh`
+2. Validate syntax: `just test-iso-config`
+3. Run pre-commit hooks: `pre-commit run --all-files`
+4. Test in PR to trigger ISO build
+
+### Anaconda Configuration
+
+The ISO includes a custom Anaconda profile at `/etc/anaconda/profile.d/aurora.conf`:
+
+- **Profile ID**: aurora
+- **OS Detection**: Matches os-release with `os_id = aurora`
+- **Network**: First wired connection auto-enabled
+- **Bootloader**: Uses Fedora EFI directory, auto-hide menu
+- **Storage**: BTRFS with zstd:1 compression, custom partitioning scheme
+- **UI**: Custom stylesheet, hides network and password spokes
+
+### Kickstart Configuration
+
+Interactive kickstart includes:
+- OSTree container source from ghcr.io/ublue-os/aurora
+- Bootc configuration for signed images
+- Fedora Flatpak repo disabling
+- System flatpak installation
+- Secure boot key enrollment (password: `universalblue`)
+
+## Build System Deep Dive
+
+### Justfile Structure
+
+The `Justfile` contains ISO-specific build orchestration:
+
+**Validation Recipes:**
+- `just check` - Validates Just syntax across all .just files
+- `just fix` - Auto-formats Just files
+- `just validate <image> <tag> <flavor>` - Validates image/tag/flavor combinations
+- `just test-iso-config` - Validates ISO configuration script syntax
+
+**Utility Recipes:**
+- `just clean` - Removes build artifacts and cloned repos
+- `just image_name <image> <tag> <flavor>` - Generates image name for specific combo
+- `just clone-common` - Clones get-aurora-dev/common repository
+- `just generate-flatpak-list` - Generates flatpak list from common repo
+
+**Image/Tag Definitions:**
+
+```bash
+images: aurora
+flavors: main, nvidia-open
+tags: stable, latest
+```
+
+### GitHub Actions Workflow
+
+The `reusable-build-iso-anaconda-webui.yml` workflow:
+
+1. **Maximizes build space** - Removes unnecessary software
+2. **Validates Just syntax** - Ensures build recipes are valid
+3. **Formats image reference** - Constructs proper image reference
+4. **Generates flatpak list** - Dynamically from Brewfiles in common repo
+5. **Builds ISO with Titanoboa** - Uses ublue-os/titanoboa@main action
+6. **Renames and checksums ISO** - Prepares for distribution
+7. **Uploads artifacts** - To GitHub Actions (PRs) or CloudFlare R2 (stable)
+
+**Build Arguments:**
+- `image-ref` - Full container image reference
+- `flatpaks-list` - Path to dynamically generated flatpak list file
+- `hook-post-rootfs` - Path to ISO configuration script
+- `kargs` - Kernel arguments (currently NONE)
+
+## Development Guidelines
+
+### Making Changes
+
+1. **ALWAYS validate first:** `just check && pre-commit run --all-files`
+2. **Make minimal modifications** - prefer configuration over code changes
+3. **Test formatting:** `just fix` to auto-format
+4. **Test ISO config syntax:** `just test-iso-config`
+5. **Test in PRs** - ISO builds run automatically on PR creation
+
+### File Editing Best Practices
+
+- **JSON files**: Validate syntax with `pre-commit run check-json`
+- **YAML files**: Validate syntax with `pre-commit run check-yaml`
+- **Justfile**: Always run `just check` after modifications
+- **Shell scripts**: Follow existing patterns in iso_files/, validate with `bash -n`
+
+### Common Modification Patterns
+
+- **ISO branding**: Update files in `iso_files/` (images, scripts)
+- **Anaconda configuration**: Edit profile in `configure_iso_anaconda-webui.sh`
+- **Flatpak lists**: Modify Brewfiles in get-aurora-dev/common repository
+- **Build workflow**: Edit `.github/workflows/reusable-build-iso-anaconda-webui.yml`
+- **Partitioning scheme**: Update `default_partitioning` in Anaconda profile
+- **Live environment**: Add/remove packages in `configure_iso_anaconda-webui.sh`
+
+## Trust These Instructions
+
+**The information in this document has been validated against the current repository state.** Only search for additional information if:
+- Instructions are incomplete for your specific task
+- You encounter errors not covered in the workarounds section
+- Repository structure has changed significantly
+
+This repository is focused and straightforward. Following these instructions will significantly reduce build failures and exploration time.
+
+## Other Rules that are Important to the Maintainers
+
+- Ensure that [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) are used and enforced for every commit and pull request title.
+- Always be surgical with the least amount of code, the project strives to be easy to maintain.
+- Documentation for Aurora exists at https://docs.getaurora.dev/
+
+## Attribution Requirements
+
+AI agents must disclose what tool and model they are using in the "Assisted-by" commit footer:
+
+```text
+Assisted-by: [Model Name] via [Tool Name]
+```
+
+Example:
+
+```text
+Assisted-by: Claude 3.5 Sonnet via Zed AI
+```
+
+## Key Differences from Aurora Main Repository
+
+This repository is **ISO-only** and differs from the main Aurora repository:
+
+1. **No container building** - Uses pre-built Aurora images from GHCR
+2. **No image variants** - Only builds ISOs, not the OS itself
+3. **Simplified Justfile** - Only ISO-related recipes
+4. **Single workflow focus** - ISO building only
+5. **External dependencies** - Dynamically generates flatpak lists from Brewfiles in get-aurora-dev/common
+
+## Quick Reference
+
+### Validation Commands
+```bash
+pre-commit run --all-files  # Full validation
+just check                   # Just syntax
+just test-iso-config         # ISO script syntax
+just fix                     # Auto-fix formatting
+```
+
+### Utility Commands
+```bash
+just clean                   # Clean artifacts
+just clone-common            # Clone common repo
+just generate-flatpak-list   # Generate flatpak list
+just image_name aurora stable main  # Get image name
+```
+
+### Valid Combinations
+```bash
+# Images: aurora
+# Flavors: main, nvidia-open
+# Tags: stable, latest
+
+just validate aurora stable main
+just validate aurora stable nvidia-open
+just validate aurora latest main
+just validate aurora latest nvidia-open
+```
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,348 @@
+# 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
+- **Just**: Command runner for automation
+- **Pre-commit**: For running validation hooks
+- **Bash**: For running scripts
+
+### Installation
+
+```bash
+# 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
+
+# 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:
+
+```
+<type>[optional scope]: <description>
+
+[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
+
+# Validate Just syntax
+just check
+
+# Test ISO configuration script syntax
+just test-iso-config
+
+# Auto-fix formatting issues
+just fix
+```
+
+### 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
+
+# Or use the Just recipe
+just test-iso-config
+```
+
+## 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
+   just check
+   just test-iso-config
+   ```
+
+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:
+   - Just syntax validation
+   - 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
+- [ ] Validated locally with `just check`
+- [ ] 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
+
+### Justfile
+
+- Use descriptive recipe names
+- Add comments for complex recipes
+- Group related recipes with `[group('name')]`
+- Mark internal recipes with `[private]`
+- Use consistent formatting (run `just fix`)
+
+**Example:**
+```just
+# Build ISO for specific flavor
+[group('ISO')]
+build-iso flavor="main":
+    #!/usr/bin/bash
+    set -eoux pipefail
+    echo "Building ISO for {{ flavor }}"
+```
+
+### 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: `just test-iso-config`
+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
+
+### Modifying Justfile
+
+1. Edit `Justfile`
+2. Validate syntax: `just check`
+3. Test affected recipes
+4. Run `just fix` to format
+5. Create PR
+
+## Resources
+
+### Documentation
+- [Aurora Documentation](https://docs.getaurora.dev/)
+- [Universal Blue Docs](https://universal-blue.org/)
+- [AGENTS.md](AGENTS.md) - AI agent development guide
+- [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
+- [Just Manual](https://just.systems/man/en/)
+- [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. Review [AGENTS.md](AGENTS.md) for detailed instructions
+3. Search existing [issues](https://github.com/ublue-os/aurora-iso/issues)
+4. Ask in [Discourse forums](https://universal-blue.discourse.group/c/aurora/11)
+5. 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! 🚀
--- a/164
+++ b/164
@ -0,0 +1,164 @@
+repo_organization := "ublue-os"
+common_image := "ghcr.io/get-aurora-dev/common:latest"
+images := '(
+    [aurora]=aurora
+)'
+flavors := '(
+    [main]=main
+    [nvidia-open]=nvidia-open
+)'
+tags := '(
+    [stable]=stable
+    [latest]=latest
+)'
+export SUDO_DISPLAY := if `if [ -n "${DISPLAY:-}" ] || [ -n "${WAYLAND_DISPLAY:-}" ]; then echo true; fi` == "true" { "true" } else { "false" }
+export SUDOIF := if `id -u` == "0" { "" } else if SUDO_DISPLAY == "true" { "sudo --askpass" } else { "sudo" }
+export PODMAN := if path_exists("/usr/bin/podman") == "true" { env("PODMAN", "/usr/bin/podman") } else if path_exists("/usr/bin/docker") == "true" { env("PODMAN", "docker") } else { env("PODMAN", "exit 1 ; ") }
+just := just_executable()
+
+[private]
+default:
+    @{{ just }} --list
+
+# Check Just Syntax
+[group('Just')]
+check:
+    #!/usr/bin/bash
+    find . -type f -name "*.just" | while read -r file; do
+    	echo "Checking syntax: $file"
+    	{{ just }} --unstable --fmt --check -f $file
+    done
+    echo "Checking syntax: Justfile"
+    {{ just }} --unstable --fmt --check -f Justfile
+
+# Fix Just Syntax
+[group('Just')]
+fix:
+    #!/usr/bin/bash
+    find . -type f -name "*.just" | while read -r file; do
+    	echo "Checking syntax: $file"
+    	{{ just }} --unstable --fmt -f $file
+    done
+    echo "Checking syntax: Justfile"
+    {{ just }} --unstable --fmt -f Justfile || { exit 1; }
+
+# Clean Repo
+[group('Utility')]
+clean:
+    #!/usr/bin/bash
+    set -eoux pipefail
+    rm -rf output/
+    rm -rf common/
+    rm -f *.iso*
+    rm -f flatpaks.list
+
+# Check if valid combo
+[group('Utility')]
+[private]
+validate $image $tag $flavor:
+    #!/usr/bin/bash
+    set -eou pipefail
+    declare -A images={{ images }}
+    declare -A tags={{ tags }}
+    declare -A flavors={{ flavors }}
+
+    # Handle Stable Daily
+    if [[ "${tag}" == "stable-daily" ]]; then
+        tag="stable"
+    fi
+
+    checkimage="${images[${image}]-}"
+    checktag="${tags[${tag}]-}"
+    checkflavor="${flavors[${flavor}]-}"
+
+    # Validity Checks
+    if [[ -z "$checkimage" ]]; then
+        echo "Invalid Image..."
+        exit 1
+    fi
+    if [[ -z "$checktag" ]]; then
+        echo "Invalid tag..."
+        exit 1
+    fi
+    if [[ -z "$checkflavor" ]]; then
+        echo "Invalid flavor..."
+        exit 1
+    fi
+
+# Image Name
+[group('Utility')]
+image_name image="aurora" tag="stable" flavor="main":
+    #!/usr/bin/bash
+    set -eou pipefail
+    {{ just }} validate {{ image }} {{ tag }} {{ flavor }}
+    if [[ "{{ flavor }}" =~ main ]]; then
+        image_name={{ image }}
+    else
+        image_name="{{ image }}-{{ flavor }}"
+    fi
+    echo "${image_name}"
+
+# Clone Common Repository
+[group('ISO')]
+clone-common:
+    #!/usr/bin/bash
+    set -eoux pipefail
+    if [[ ! -d "common" ]]; then
+        git clone https://github.com/get-aurora-dev/common.git common
+    else
+        echo "Common repository already cloned"
+    fi
+
+# Generate Flatpak List
+[group('ISO')]
+generate-flatpak-list:
+    #!/usr/bin/bash
+    set -eoux pipefail
+    {{ just }} clone-common
+    find common -iname "*system-flatpaks.Brewfile" -exec cat '{}' ';' | \
+        grep -v '#' | \
+        grep -F -e "flatpak" | \
+        sed 's/flatpak //' | \
+        tr -d '"' | \
+        tee flatpaks.list
+
+# Verify Container with Cosign
+[group('Utility')]
+verify-container container="" registry="ghcr.io/ublue-os" key="":
+    #!/usr/bin/bash
+    set -eou pipefail
+
+    # Get Cosign if Needed
+    if [[ ! $(command -v cosign) ]]; then
+        COSIGN_CONTAINER_ID=$(${SUDOIF} ${PODMAN} create cgr.dev/chainguard/cosign:latest bash)
+        ${SUDOIF} ${PODMAN} cp "${COSIGN_CONTAINER_ID}":/usr/bin/cosign /usr/local/bin/cosign
+        ${SUDOIF} ${PODMAN} rm -f "${COSIGN_CONTAINER_ID}"
+    fi
+
+    # Verify Cosign Image Signatures if needed
+    if [[ -n "${COSIGN_CONTAINER_ID:-}" ]]; then
+        if ! cosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity=https://github.com/chainguard-images/images/.github/workflows/release.yaml@refs/heads/main cgr.dev/chainguard/cosign >/dev/null; then
+            echo "NOTICE: Failed to verify cosign image signatures."
+            exit 1
+        fi
+    fi
+
+    # Public Key for Container Verification
+    key={{ key }}
+    if [[ -z "${key:-}" ]]; then
+        key="https://raw.githubusercontent.com/ublue-os/main/main/cosign.pub"
+    fi
+
+    # Verify Container using cosign public key
+    if ! cosign verify --key "${key}" "{{ registry }}"/"{{ container }}" >/dev/null; then
+        echo "NOTICE: Verification failed. Please ensure your public key is correct."
+        exit 1
+    fi
+
+# Test ISO Configuration Script
+[group('ISO')]
+test-iso-config:
+    #!/usr/bin/bash
+    set -eoux pipefail
+    bash -n iso_files/configure_iso_anaconda-webui.sh
+    echo "ISO configuration script syntax is valid"
--- a/17
+++ b/17
@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2024 Universal Blue
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
--- a/README.md
+++ b/README.md
@ -1 +1,217 @@
-# Aurora ISOs
+# Aurora ISO Builder
+
+[![Build ISOs](https://github.com/ublue-os/aurora-iso/actions/workflows/reusable-build-iso-anaconda-webui.yml/badge.svg)](https://github.com/ublue-os/aurora-iso/actions/workflows/reusable-build-iso-anaconda-webui.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
+- **Monthly Builds**: Automatically built ISOs on the first of each month
+- **CloudFlare Distribution**: Stable ISOs automatically uploaded for public access
+
+## Download
+
+Pre-built ISOs are available at [getaurora.dev](https://getaurora.dev).
+
+## Repository Structure
+
+```
+.
+├── .github/
+│   └── workflows/
+│       ├── reusable-build-iso-anaconda-webui.yml  # Main ISO build workflow
+│       └── validate-just.yml                       # Justfile validation
+├── iso_files/
+│   ├── configure_iso_anaconda-webui.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:
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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-webui.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
+
+### Triggers
+
+- **Pull Requests**: Builds ISOs for testing (uploads to GitHub artifacts)
+- **Workflow Dispatch**: Manual triggering
+- **Schedule**: First day of each month at 2:00 AM UTC
+
+### 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 artifacts (PR) or CloudFlare R2 (stable release)
+
+## 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](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-webui.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-webui.yml`
+
+## Documentation
+
+- [Aurora Documentation](https://docs.getaurora.dev/)
+- [Universal Blue Docs](https://universal-blue.org/)
+- [AGENTS.md](AGENTS.md) - Comprehensive guide for AI-assisted development
+- [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