ZacharyZhang-NY/omarchy-iso
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

README: "For maintainers" is a top-level part

Browse Source 
Its sections move up one level with it, so creating, testing and
releasing the ISO are second-level headings again.
This commit is contained in:
Emir Beganovic committed 2026-10-09 21:45:12 +02:00
1 parent f9d184f2bc
commit 20fd1dd00b
1 file changed
+18 -18
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+18 -18
View File
@@ -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. - [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. - [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. 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 | | 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. 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: `.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. `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 | | 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. 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. 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. 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`: 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. 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: 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`. 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. 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. `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`. 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. 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 ```bash
mkdir cidata 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/ genisoimage -output cidata.iso -volid cidata -joliet -rock cidata/
``` ```
#### Proxmox example ### Proxmox example
```bash ```bash
qm create 101 --name my-omarchy \ 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. 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. 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. 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]`. 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 unallocated space, then offers to start an interactive installation on it. The
fixture exercises Windows partition preservation but does not contain Windows. 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. 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. 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. 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/<iso>-integration/runs/<timestamp>-<scenario>/`, and `--no-preview` skips the `imv` review just like the acceptance harness. Artifacts — screenshots, the fixtured/staged/final `limine.conf`, the reset typescript, and the factory-reset log — land under `test-runs/<iso>-integration/runs/<timestamp>-<scenario>/`, 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. 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. 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. 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.