mirror of
https://github.com/get-aurora-dev/iso.git
synced 2026-11-03 21:49:46 -09:00
bringup the repository (#4)
This commit is contained in:
inffy
GitHub
parent
455de11be2
commit
bbfb72a83d
10 changed files with 1190 additions and 2 deletions
19
.github/workflows/build-iso-stable.yml
vendored
Normal file
19
.github/workflows/build-iso-stable.yml
vendored
Normal file
|
|
@ -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
|
||||
|
|
@ -121,4 +121,4 @@ jobs:
|
|||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y rclone
|
||||
rclone copy "${SOURCE_DIR}" R2:aurora-dl
|
||||
rclone copy "${SOURCE_DIR}" R2:aurora-dl
|
||||
28
.github/workflows/validate-just.yml
vendored
Normal file
28
.github/workflows/validate-just.yml
vendored
Normal file
|
|
@ -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
|
||||
38
.gitignore
vendored
Normal file
38
.gitignore
vendored
Normal file
|
|
@ -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/
|
||||
11
.pre-commit-config.yaml
Normal file
11
.pre-commit-config.yaml
Normal file
|
|
@ -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
|
||||
347
AGENTS.md
Normal file
347
AGENTS.md
Normal file
|
|
@ -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
|
||||
```
|
||||
348
CONTRIBUTING.md
Normal file
348
CONTRIBUTING.md
Normal file
|
|
@ -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! 🚀
|
||||
164
Justfile
Normal file
164
Justfile
Normal file
|
|
@ -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"
|
||||
17
LICENSE
Normal file
17
LICENSE
Normal file
|
|
@ -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.
|
||||
218
README.md
218
README.md
|
|
@ -1 +1,217 @@
|
|||
# Aurora ISOs
|
||||
# Aurora ISO Builder
|
||||
|
||||
[](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
|
||||
Loading…
Reference in a new issue