quine-global-labs/mirror-get-aurora-dev-iso
1
0
Fork 0
mirror of https://github.com/get-aurora-dev/iso.git synced 2026-11-03 21:49:46 -09:00
Code Issues Projects Releases Packages Wiki Activity

docs: simplify them (#86)

Browse source
This commit is contained in:
renner 2026-09-05 08:15:32 +02:00 committed by GitHub
parent 4e4805886e
commit ed802cca8f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 49 additions and 475 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

304
CONTRIBUTING.md
View file

@ -1,304 +0,0 @@
# 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:
```
<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
# 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! 🚀

220
README.md
View file

@ -2,20 +2,9 @@
[![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
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
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.
## Download
@ -23,6 +12,8 @@ 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)
@ -30,158 +21,80 @@ Testing ISOs are available [here](https://docs.getaurora.dev/guides/iso-testing)
You can verify the SHA256 checksum of your downloaded ISO against the published checksum file:
```bash
sha256sum -c <iso-name>.iso-CHECKSUM
sha256sum --check <iso-name>.iso-CHECKSUM
```
Example:
```bash
sha256sum --check aurora-stable-webui-x86_64.iso-CHECKSUM
aurora-stable-webui-x86_64.iso: OK
```
### 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/):
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/):
```bash
gh attestation verify <iso-name>.iso --owner get-aurora-dev
```
Or by specifying the repository directly:
```bash
gh attestation verify <iso-name>.iso --repo get-aurora-dev/iso
```
## Repository Structure
Example:
```
.
├── .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
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
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
✓ Verification succeeded!
The following 1 attestation matched the policy criteria
- 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
```
## Building ISOs
### Prerequisites
ISOs are built using GitHub Actions, but you can validate your changes locally:
```bash
# Install pre-commit
pip install pre-commit
pre-commit install
```
### Validation
Before submitting changes, validate your code:
```bash
# Check all syntax and formatting
pre-commit run --all-files
# Test ISO configuration script syntax
bash -n iso_files/configure_iso_anaconda.sh
bash -n iso_files/build.sh
```
## ISO Variants
### Flavors
- **main**: Standard Aurora ISO with open-source drivers
- **nvidia-open**: Aurora ISO with NVIDIA Open kernel modules
There will be no ISOs for [DX images](https://docs.getaurora.dev/dx/aurora-dx-intro).
### Versions
- **stable**: Latest stable Fedora release (recommended)
- **latest**: Current Fedora release
- **stable**: Built on top of aurora:stable images
- **testing**: Built on top of aurora:testing images
## Configuration
See the [release stream docs](https://docs.getaurora.dev/guides/release-streams).
### ISO Customization
There will be no ISOs for `:latest` images.
The ISO is customized via `iso_files/configure_iso_anaconda.sh`:
- Installs Anaconda WebUI installer
- Configures Aurora-specific Anaconda profile
- Sets up BTRFS partitioning with zstd compression
- Adds installer to KDE panel and kickoff menu
- Configures secure boot key enrollment
- Pre-installs flatpaks (dynamically generated from Brewfiles)
### Anaconda Profile
The custom Aurora profile includes:
- **Storage**: BTRFS with zstd:1 compression
- **Partitioning**:
- `/` (1 GiB min, 70 GiB max)
- `/home` (500 MiB min, 50 GiB free)
- `/var` (BTRFS)
- **Network**: First wired connection auto-enabled
- **Bootloader**: Fedora EFI directory, auto-hide menu
### Secure Boot
## Secure Boot
Secure boot is supported by default. After installation, users are prompted to enroll the secure boot key with password: `universalblue`
## GitHub Actions Workflow
## Build Overview
### 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
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 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:
@ -197,36 +110,6 @@ 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/)
@ -238,15 +121,10 @@ Contributions are welcome! Please follow these guidelines:
- [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
- [Discussions](https://github.com/ublue-os/aurora/discussions)
## 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
- [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