From 23f8565de22d56d5c6a29e7add9487abe6e2c01a Mon Sep 17 00:00:00 2001 From: Davide Cavalca Date: May 12 2024 02:25:35 +0000 Subject: Add a page documenting deviations from stock Fedora Linux --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index eead31a..61d3010 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,2 +1,3 @@ * xref:installation.adoc[Installation] +* xref:deviations.adoc[Deviations] * xref:faq.adoc[FAQ] diff --git a/modules/ROOT/pages/deviations.adoc b/modules/ROOT/pages/deviations.adoc new file mode 100644 index 0000000..476c501 --- /dev/null +++ b/modules/ROOT/pages/deviations.adoc @@ -0,0 +1,77 @@ += Deviations + +This page documents where Fedora Asahi Remix deviates from Fedora Linux and the reasoning behind. + +We are using a https://fedoraproject.org/wiki/Remix[Remix] as opposed to delivering Apple Silicon support in Fedora Linux proper because this ecosystem is still very fast moving and we believe a Remix will offer the best user experience for the time being. + +Building a Remix allow us to integrate hardware support as it becomes available and bring it to users as quickly as possible. Nonetheless, as much of this work as possible is being conducted upstream, with most components being developed, maintained and packaged in Fedora Linux proper. Ultimately, we expect Apple Silicon support to be integrated in Fedora Workstation and Fedora Server in a future release, and are working towards this goal. This approach is in line with the overarching goal of the Asahi project itself to integrate support for these systems in the relevant upstream projects. + +== Edition mapping + +We provide Fedora Asahi Remix in four editions, which map to the stock Fedora Linux deliverables as follows: + +- Fedora Linux with KDE Plasma -> Fedora KDE Plasma Desktop +- Fedora Linux with GNOME -> Fedora Workstation +- Fedora Server -> Fedora Server +- Fedora Minimal -> Fedora Everything + +The flagship edition for Fedora Asahi Remix is Fedora Linux with KDE Plasma. + +== Deviations + +=== Installation does not use Anaconda + +Apple Silicon Macs have a bespoke https://github.com/AsahiLinux/docs/wiki/Introduction-to-Apple-Silicon[boot process] that requires special considerations to support https://github.com/AsahiLinux/docs/wiki/Open-OS-Ecosystem-on-Apple-Silicon-Macs[alternative operating systems]. Currently, Fedora Asahi Remix is installed from macOS via the https://github.com/AsahiLinux/asahi-installer[Asahi Installer], which takes care of preparing the system for the installation, downloading an image for Fedora Asahi Remix and laying it on disk. + +The Asahi Installer has also the ability to prepare the system and install the supporting components for a barebone UEFI-enabled system. This could potentially be used in the future to support Anaconda-based installation using regular Fedora Linux install media, but it is not currently supported. The work required is tracked in our issue tracker (https://pagure.io/fedora-asahi/project/issue/9[Anaconda], https://pagure.io/fedora-asahi/project/issue/10[disk management tools]). + +=== No official support for full disk encryption + +The Asahi Installer does not currently support installing systems using full disk encryption. There is no technical limitation preventing the use of encryption, but it not currently a supported configuration, and the installer does not provide any facility to set it up. A number of approaches to resolve this (including https://github.com/AsahiLinux/asahi-installer/pull/240[implementing installer suppport]) are currently being discussed upstream in the Asahi Linux project. + +=== Installation images are built with Kiwi + +Fedora Asahi Remix installation images are built using https://osinside.github.io/kiwi/[Kiwi] from the published https://pagure.io/fedora-asahi/kiwi-descriptions[Kiwi descriptions]. + +=== Installation images are built and hosted outsite of Fedora infrastructure + +Because the installation images include additional components that are not part of stock Fedora Linux, they cannot currently be built or hosted on Fedora Infrastructure. We are instead using AWS EC2 instances to perform builds and upload them to AWS S3, triggered by an https://gitlab.com/fedora/sigs/asahi/overseer[AWS Lambda] (which runs daily). We use another https://gitlab.com/fedora/sigs/asahi/manifest-generator[Lambda] to generate the manifest for these https://fedora-asahi-remix.org/builds.html[daily builds] to be consumed by the Asahi Installer. + +We host our https://fedora-asahi-remix.org/[website] on AWS S3, fronted by AWS Cloudfront; we use https://gitlab.com/fedora/sigs/asahi/cdn-invalidation[another Lambda] to handle CDN invalidation. The website is automatically deployed from its https://gitlab.com/fedora/sigs/asahi/website[GitLab repository]; this is also where the manually-maintained https://gitlab.com/fedora/sigs/asahi/website/-/blob/main/installer_data_stable.json[installer manifest] for release images (as opposed to dailies) lives. The Lambdas are also automatically deployed via Gitlab Pipelines using AWS Chalice. + +=== No support for legacy X11 desktops + +Fedora Asahi Remix comes out of the box with a 100% https://wayland.freedesktop.org/[Wayland] environment. Wayland is required to provide a good experience on this platform, and the legacy Xorg server is not supported. Existing X11 applications are fully supported out of the box thanks to XWayland. + +=== Downstream packages required for platform enablement are included + +Fedora Asahi Remix includes a number of components that are not part of stock Fedora Linux; these are preinstalled and delivered via our https://copr.fedorainfracloud.org/groups/g/asahi/coprs/[copr repositories]. + +These components include `mesa` (https://pagure.io/fedora-asahi/mesa/[source], https://copr.fedorainfracloud.org/coprs/g/asahi/mesa/[copr]), which is tightly coupled to the kernel AGX driver and in active development, and `u-boot` (https://pagure.io/fedora-asahi/uboot-tools[source], https://copr.fedorainfracloud.org/coprs/g/asahi/u-boot/[copr]), which requires patches in the process of being upstreamed. + +The kernel is also maintained downstream in a https://gitlab.com/fedora-asahi/kernel-asahi[fork] of the main https://gitlab.com/cki-project/kernel-ark[kernel-ark] repository. The kernel is in active development -- while platform enablement for Apple Silicon is https://github.com/AsahiLinux/docs/wiki/Feature-Support[in the process] of being upstreamed, currently a downstream kernel is required for the best experience. + +Finally, a number of packages specific to the Remix implementation are also maintained downstream: + +- `asahi-platform-metapackage` (https://pagure.io/fedora-asahi/asahi-platform-metapackage[source], https://copr.fedorainfracloud.org/coprs/g/asahi/fedora-remix-scripts/[copr]) provides a metapackage that declares all other Asahi platform package dependencies +- `asahi-repos` (https://pagure.io/fedora-asahi/asahi-repos[source], https://copr.fedorainfracloud.org/coprs/g/asahi/fedora-remix-branding/[copr]) provides Yum repository definitions for our copr-provided packages +- `calamares-firstboot-configs` (https://pagure.io/fedora-asahi/calamares-firstboot-config[source], https://copr.fedorainfracloud.org/coprs/g/asahi/fedora-remix-scripts/[copr]) provides the Calamares configuration used for the first-boot installer on the KDE edition +- `fedora-asahi-remix-appstream-metadata` (https://pagure.io/fedora-asahi/fedora-asahi-remix-appstream-metadata[source], https://copr.fedorainfracloud.org/coprs/g/asahi/fedora-remix-branding/[copr]) provides the Remix-specific AppStream metadata that is required to support updates between major releases via PackageKit +- `fedora-asahi-remix-release` (https://pagure.io/fedora-asahi/fedora-asahi-remix-release[source], https://copr.fedorainfracloud.org/coprs/g/asahi/fedora-remix-branding/[copr]) provides the distribution branding for the Remix +- `fedora-asahi-remix-scripts` (https://pagure.io/fedora-asahi/fedora-asahi-remix-scripts[source], https://copr.fedorainfracloud.org/coprs/g/asahi/fedora-remix-scripts/[copr]) provides various utility scripts and systemd services used in the Remix + +=== Fedora Asahi Remix uses 16K pages + +Apple Silicon hardware native page-size is 16K; consequently, this is also the Fedora Asahi Remix default, and we deploy the `kernel-16k` variant. While a 4K page-size kernel is available in the `kernel` package, this is completely unsupported and should not be used. + +=== Fedora Linux with KDE Plasma uses Calamares for first-boot setup + +We provide a custom Calamares-based first-boot setup wizard to simplify user onboarding. This only availabe on the Fedora Linux with KDE Plasma edition and is used in place of `initial-setup`. + +=== Fedora Server uses btrfs as the filesystem for the installed system + +Fedora Asahi Remix uses btrfs for all of the deliverables. This matches what Fedora Linux does since Fedora Linux 33, with the exception of Fedora Server, which still defaults to XFS. We use btrfs everywhere because we need the ability to online resize the filesystem, so that it can be expanded to fill the available space on the first boot after the installation, and so that users can shrink it as needed if they want to deploy custom layouts. + +=== OpenH264 is automatically installed on first-boot + +Fedora Asahi Remix automatically installs openh264 on the first boot, enabling playback of H.264-encoded content out of the box. This is possible because of the two-step install process -- the Asahi Installer downloads the necessary packages from Cisco's server and makes them available to the deployed system to the perform the installation via a one-off systemd service.