diff --git a/README.md b/README.md index 3b2242e..cc5fe51 100644 --- a/README.md +++ b/README.md @@ -36,11 +36,11 @@ Use the `.sig` file to verify the ISO against the Omarchy signing key. - [Dual-boot install](https://omarchy.org/manual/dual-boot-install/): install Omarchy in the free space of a drive, beside Windows or another OS. - [Unattended installs](https://omarchy.org/manual/unattended-installs/): let the ISO install itself from a configuration on a second drive, with no keyboard and no wizard. -## For maintainers +# For maintainers The rest of this file covers building, testing and publishing the ISO. -### What is published, and where +## What is published, and where | What | Where | When | | --- | --- | --- | @@ -54,7 +54,7 @@ Every ISO and every VM image has a `.sha256` file next to it. The release ISO al On nightly.omarchy.org, a published file is never replaced. Only `latest.json` changes. It is written last, after every file of the version has been fetched back through the CDN and compared. -### The nightly build +## The nightly build `.github/workflows/nightly-build.yml` runs every night for two channels: @@ -67,7 +67,7 @@ A separate job publishes. It is the only job with the bucket's key, and it runs `test/vm-image/nightly-plan` decides which channels a run builds and where they are published. `test/vm-image/nightly-layout` lays out the files and writes `latest.json`. `test/unit/nightly-test.sh` tests both. -### latest.json +## latest.json | Field | What it is | | --- | --- | @@ -88,7 +88,7 @@ A separate job publishes. It is the only job with the bucket's key, and it runs The version is also in the edge ISO's file name. -### VM images +## VM images VM images are for testing. Users download the release ISO from iso.omarchy.org. @@ -96,7 +96,7 @@ A VM image is Omarchy already installed, as one `.qcow2` file. There is an image The user is `omarchy` and the password is `omarchy`. SSH takes keys only. -#### Boot the image by itself +### Boot the image by itself The image boots through UEFI with no other file. Run these commands on a Linux machine with QEMU, read and write access to `/dev/kvm`, `curl` and `jq`: @@ -117,7 +117,7 @@ qemu-system-x86_64 -enable-kvm -cpu host -smp 4 -m 4G \ The firmware paths are Arch's. `snapshot=on` keeps the downloaded image unchanged. The image is a 4 to 5 GB download. -#### Boot it faster, with SSH +### Boot it faster, with SSH The `unpacked/` folder next to each image holds what a direct boot needs: @@ -143,7 +143,7 @@ chmod +x vm-boot To get the URL of the edge ISO, run `jq -r .url` on the same `latest.json`. -### Autoinstall +## Autoinstall The [manual's page](https://omarchy.org/manual/unattended-installs/) is the one for users; this is the same feature in full. @@ -151,7 +151,7 @@ The shipped ISO installs itself with no keyboard when it finds its configuration `cidata` is the cloud-init `NoCloud` label, so Proxmox, libvirt, and Packer already know how to attach one. -#### Configuration files +### Configuration files These are the configurator's own output files, so the way to get a starting set is to run one interactive install and copy what it wrote into `/root`. @@ -179,7 +179,7 @@ When `authorized_keys` is present, autoinstall installs it as the user's `~/.ssh When `tailscale_authkey` is present (one key, blank lines and `#` comments ignored), the install adds the `tailscale` package from the ISO's bundled mirror — nothing is fetched from the network at install or boot — and stages the join for first boot: the key lands at `/etc/tailscale/authkey` (root-only), `tailscaled` is enabled, ufw allows traffic in on `tailscale0`, and a background unit runs `tailscale up` once the network is actually up, retrying until it succeeds without holding up the boot. After a successful join the key is deleted and the unit disables itself; until then both survive reboots, so a machine installed offline joins whenever it first gets connectivity. The node appears on the tailnet under the configured hostname. Use a reusable, pre-authorized (tagged) key so one drive image serves many machines — or an ephemeral key for disposable VMs. -#### Building the drive +### Building the drive ```bash mkdir cidata @@ -187,7 +187,7 @@ cp user_configuration.json user_credentials.json authorized_keys cidata/ genisoimage -output cidata.iso -volid cidata -joliet -rock cidata/ ``` -#### Proxmox example +### Proxmox example ```bash qm create 101 --name my-omarchy \ @@ -207,7 +207,7 @@ Boot order is disk first: the empty disk falls through to the ISO on the first b Encrypted autoinstalls are not fully unattended — the LUKS passphrase prompt still needs someone at the first boot. -### Creating the ISO +## Creating the ISO Run `./bin/omarchy-iso-make`; output goes into `./release`. By default the ISO uses the Omarchy packages and tracks the `quattro` branch, from the stable mirror. Pass `--edge` to use `omarchy-dev` and `omarchy-settings-dev` from the edge mirror. @@ -221,7 +221,7 @@ Despite the local folder name, the first argument is the Omarchy source checkout Use `--dev` or `--rc` to build against those package channels. Both `--dev` and `--edge` select the dev packages from the edge mirror. -### Testing the ISO +## Testing the ISO Run `./bin/omarchy-iso-boot [release/omarchy.iso]`. @@ -233,7 +233,7 @@ synthetic disk in `/tmp` with an existing ESP and data partition plus ample unallocated space, then offers to start an interactive installation on it. The fixture exercises Windows partition preservation but does not contain Windows. -### Acceptance testing the ISO +## Acceptance testing the ISO Run `./bin/omarchy-iso-test [release/omarchy.iso]` to install the ISO into a headless VM by driving the real interactive install flow — the harness reads each screen via QMP screendumps + OCR and answers with virtual keystrokes, so the configurator wizard, install dashboard, reboot prompt, and SDDM login are all exercised exactly as a user would. It then boots the installed system, sends real VM keyboard shortcuts for the primary shell and window-management actions, and runs the in-guest acceptance suite (`test/acceptance` in the omarchy repo). The suite checks session and service health, the complete core-package manifest, user defaults, representative applications, menus, panels, live weather, launchers, visual selectors, notifications, clipboard, and other interactive shell behavior. @@ -249,7 +249,7 @@ The harness syncs the acceptance suite from `$OMARCHY_PATH` when it is available Pass `--encrypt` to drive the encrypted install flow (including typing the LUKS passphrase at boot) instead of the unencrypted one. Pass `--no-preview` to collect the same visual artifacts without opening them in `imv` when the run finishes. -### Integration testing the ISO +## Integration testing the ISO Scenarios under `test/integration.d/` boot a real ISO install in QEMU and assert on what the running system actually does. The runner installs the ISO once — unattended, from a generated cidata drive — and saves the result as a reusable base image; every scenario then boots a throwaway overlay of that base with its own copy of the firmware vars, so neither disk nor NVRAM state leaks between runs. Shared machinery (VM lifecycle, QMP screendump + OCR console driving, virtual keystrokes, guest SSH, the cidata build) lives in `test/integration.d/base-test.sh`, so a new scenario is one file. @@ -263,14 +263,14 @@ The first scenario is `factory-reset`: it proves `omarchy-system-factory-reset` Artifacts — screenshots, the fixtured/staged/final `limine.conf`, the reset typescript, and the factory-reset log — land under `test-runs/-integration/runs/-/`, and `--no-preview` skips the `imv` review just like the acceptance harness. -### Signing the ISO +## Signing the ISO Run `./bin/omarchy-iso-sign [release/omarchy.iso]`. The signing key is retrieved from the shared Omarchy vault with the 1Password CLI. -### Uploading the ISO +## Uploading the ISO Run `./bin/omarchy-iso-upload [release/omarchy.iso]`. This requires rclone configuration (`rclone config`). The `.sig` and `.sha256` sidecars go up with the ISO when they exist beside it. -### Full release of the ISO +## Full release of the ISO Run `./bin/omarchy-iso-release VERSION` to create, test, sign, and upload the ISO in one flow. Add `--rc` to release an RC build instead.