David Heinemeier HanssonandClaude Fable 5
0339b13d12
* Join the tailnet from a cidata tailscale_authkey A tailscale_authkey file on the autoinstall drive gets the installed machine onto the tailnet on its own: the tailscale package is bundled in the offline mirror and installed only when the key is present, the key is staged root-only at /etc/tailscale/authkey, and a oneshot first-boot unit runs tailscale up once the network is really there. On success the key is deleted and the unit disables itself; on failure both survive to retry on the next boot, so an offline install joins whenever it first gets connectivity. ufw allows traffic in on tailscale0 via the same write-the-rule-then-ignore-the-chroot-exit-code dance as the SSH phase. Bundling rather than fetching at first boot is deliberate: pacman -Sy tailscale on a fresh machine is a partial upgrade, and pacman -Syu means an unattended full system upgrade racing the user's first login. The offline mirror is a coherent snapshot; installing from it keeps the target consistent and the install offline-capable. See plans/tailscale.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xc74h4WSYpuYPGuYbFAR1q * Do not hold boot hostage for the tailnet join Review caught that the join unit was Type=oneshot wanted by multi-user.target: target units implicitly gain After= for their Wants=, so an offline machine's boot -- SDDM included -- stalled for the full 10-minute timeout, and once timed out the join never retried within that boot. Type=simple counts as started the moment it forks, so boot proceeds while the join retries in the background for as long as the boot lasts. Cleanup moves inside the script, sequenced after tailscale up succeeds, which preserves the retry-across-boots behavior: key and unit survive a boot with no connectivity, and the key never outlives a successful join. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xc74h4WSYpuYPGuYbFAR1q --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
124 lines
8.2 KiB
Markdown
124 lines
8.2 KiB
Markdown
# Omarchy ISO
|
|
|
|
The Omarchy ISO is the only supported way to install Omarchy. It ships the Omarchy Configurator, installs Arch Linux, installs the Omarchy packages from the bundled mirror, runs target system setup in the chroot, creates the user, and runs `omarchy-setup-user` for that user.
|
|
|
|
## Downloading the latest ISO
|
|
|
|
See the ISO link on [omarchy.org](https://omarchy.org).
|
|
|
|
## 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.
|
|
|
|
For local development, build the ISO from sibling checkouts:
|
|
|
|
```bash
|
|
./bin/omarchy-iso-make --local-source ../omarchy-installer ../omarchy-pkgs
|
|
```
|
|
|
|
Despite the local folder name, the first argument is the Omarchy source checkout (runtime commands, configs, setup scripts, themes, shell, migrations). The installer itself lives in this ISO repo.
|
|
|
|
Use `--dev` or `--rc` to build against those package channels. Both `--dev` and `--edge` select the dev packages from the edge mirror.
|
|
|
|
## Autoinstall
|
|
|
|
The shipped ISO installs itself with no keyboard when it finds its configuration on a second drive. Attach a drive labeled `cidata` alongside the ISO and the installer copies the config off it and skips the configurator; with no such drive, nothing changes and the wizard runs as usual. No rebuild, no extra boot entry.
|
|
|
|
`cidata` is the cloud-init `NoCloud` label, so Proxmox, libvirt, and Packer already know how to attach one.
|
|
|
|
### 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`.
|
|
|
|
| File | Required | Purpose |
|
|
|------|----------|---------|
|
|
| `user_configuration.json` | Yes | archinstall config: disk, hostname, timezone, keyboard |
|
|
| `user_credentials.json` | Yes | Username and password hash |
|
|
| `user_full_name.txt` | No | Git full name |
|
|
| `user_email_address.txt` | No | Git email |
|
|
| `user_encrypt_installation.txt` | No | `true` when `user_configuration.json` carries a `disk_encryption` block; defaults to false |
|
|
| `authorized_keys` | No | SSH public keys in sshd's own format, one per line |
|
|
| `tailscale_authkey` | No | Tailscale auth key; the machine joins your tailnet on first boot |
|
|
|
|
Both required files must be present or the installer falls back to the configurator. Generate the password hash for `user_credentials.json` with `openssl passwd -6 "yourpassword"`.
|
|
|
|
Encryption itself is configured by the `disk_encryption` block inside `user_configuration.json` — which carries the passphrase in plaintext, so treat a drive built from an encrypted install accordingly. The flag file must match it: it drives the encrypted install's SDDM autologin and the final boot validation, not the encryption.
|
|
|
|
`authorized_keys` is the same file sshd reads — copy your own or write one key per line:
|
|
|
|
```
|
|
ssh-ed25519 AAAA... you@host
|
|
```
|
|
|
|
When `authorized_keys` is present, autoinstall installs it as the user's `~/.ssh/authorized_keys`, enables `sshd`, and adds a `ufw allow ssh` rule — a stock Omarchy install ships openssh with the service disabled and its firewall opens neither port 22 nor anything else beyond LocalSend. Networking needs nothing extra; NetworkManager is already enabled with DHCP. Password SSH authentication is left at the distro default. An `authorized_keys` with no usable keys fails the install rather than producing a machine nobody can reach.
|
|
|
|
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
|
|
|
|
```bash
|
|
mkdir cidata
|
|
cp user_configuration.json user_credentials.json authorized_keys cidata/
|
|
genisoimage -output cidata.iso -volid cidata -joliet -rock cidata/
|
|
```
|
|
|
|
### Proxmox example
|
|
|
|
```bash
|
|
qm create 101 --name my-omarchy \
|
|
--bios ovmf --machine q35 --cpu host --cores 4 --memory 8192 \
|
|
--ostype l26 --scsihw virtio-scsi-single \
|
|
--efidisk0 local-lvm:0,efitype=4m,pre-enrolled-keys=0 \
|
|
--scsi0 local-lvm:40,discard=on,iothread=1 \
|
|
--net0 virtio,bridge=vmbr0 --vga virtio --serial0 socket \
|
|
--ide2 local:iso/omarchy.iso,media=cdrom \
|
|
--ide3 local:iso/cidata.iso,media=cdrom \
|
|
--boot order='scsi0;ide2'
|
|
|
|
qm start 101
|
|
```
|
|
|
|
Boot order is disk first: the empty disk falls through to the ISO on the first boot, and the installed system boots from disk afterwards. The machine reboots into Omarchy on its own when the install finishes.
|
|
|
|
Encrypted autoinstalls are not fully unattended — the LUKS passphrase prompt still needs someone at the first boot.
|
|
|
|
## Testing the ISO
|
|
|
|
Run `./bin/omarchy-iso-boot [release/omarchy.iso]`.
|
|
|
|
Run `./test/all` for the unit tests, which cover cidata autoinstall loading and the orchestrator's SSH access phase without needing a built ISO.
|
|
|
|
To exercise installation alongside existing Windows-style partitions, run
|
|
`./bin/omarchy-iso-test-windows-disk [release/omarchy.iso]`. It creates a
|
|
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
|
|
|
|
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.
|
|
|
|
Visual checkpoints are saved as `success-<step>.png` or `failure-<step>.png` alongside the serial and install logs in `test-runs/<iso>/runs/<timestamp>/`. Independent test files and applications continue after a failure so one broken surface does not hide the rest of the report. The harness then stops the VM and opens the ordered screenshots in `imv` for quick visual review.
|
|
|
|
The harness syncs the acceptance suite from `$OMARCHY_PATH` when it is available. The install phase produces a reusable base image, so iterating against another checkout is fast:
|
|
|
|
```bash
|
|
./bin/omarchy-iso-test release/omarchy.iso --install-only # once per ISO
|
|
./bin/omarchy-iso-test release/omarchy.iso --reuse-base \
|
|
--sync-omarchy ../omarchy # fast loop against local tests
|
|
```
|
|
|
|
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.
|
|
|
|
## 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
|
|
|
|
Run `./bin/omarchy-iso-upload [release/omarchy.iso]`. This requires rclone configuration (`rclone config`).
|
|
|
|
## 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.
|