# Testing the Void Installer ISO on Real Hardware

End-to-end guide to take the freshly built `out/void-install.iso`, write it to a
USB stick, and run the installer on a real machine (e.g. the XPS 17 9700).

> ⚠️ **DESTRUCTIVE.** The installer will reformat the partition you select.
> Make a Timeshift / dd backup of any disk you care about before booting from
> the stick. The installer **never** touches the EFI System Partition — your
> existing Windows bootloader stays put.

---

## 1 · Prerequisites

| Item | Detail |
| --- | --- |
| USB stick | ≥ 2 GiB, **all data on it will be lost** |
| Target machine | UEFI firmware, x86_64, ≥ 4 GiB RAM, ≥ 30 GiB free on the target partition |
| Host (this laptop) | Linux with `lsblk`, `dd`, `sync`, root access |
| Built ISO | `out/void-install.iso` (run `make iso` first if missing) |
| Network | Ethernet **or** known-good Wi-Fi credentials (NetworkManager nmtui works in the live env) |

---

## 2 · Build the production ISO

```bash
cd ~/Sources/void-installer
make iso          # builds out/void-install.iso (~1.3 GiB)
sha256sum out/void-install.iso
```

The build runs entirely inside Docker, so the host stays clean.
Output: `out/void-install.iso`. Keep the sha256 — you'll verify it after `dd`.

---

## 3 · Identify the USB device

Plug the USB stick in. Then:

```bash
lsblk -o NAME,SIZE,MODEL,TRAN,MOUNTPOINTS
```

Find the line with `usb` in the `TRAN` column. Typical names: `/dev/sdb`,
`/dev/sdc`. **Never** pick `/dev/sda` (your system disk) or anything starting
with `nvme0n1` (your NVMe). Confirm with the size (matches your stick).

Set a shell variable so you can't typo it later:

```bash
USB=/dev/sdX     # ← replace X with the actual letter you saw above
echo "WILL ERASE: $USB"
lsblk "$USB"     # double-check
```

If the stick has any mounted partitions, unmount them all:

```bash
for p in $(lsblk -nro NAME "$USB" | tail -n +2); do
    sudo umount "/dev/$p" 2>/dev/null || true
done
```

---

## 4 · Flash the ISO

The Void ISO is a **hybrid ISO** (xorriso-isohybrid), so plain `dd` works for
both UEFI and legacy BIOS. **No partitioning, no formatting, no GUI tool
needed.**

```bash
sudo dd if=out/void-install.iso of="$USB" bs=4M status=progress conv=fsync oflag=direct
sync
```

When it finishes (~1-3 min on USB 3.x), verify the write actually landed:

```bash
sudo dd if="$USB" bs=4M count=$(( $(stat -c%s out/void-install.iso) / 4 / 1024 / 1024 )) \
    status=none | sha256sum
sha256sum out/void-install.iso
```

The two hashes should match (truncated read length matters; if they differ try
adding `iflag=fullblock`).

> Alternative GUI tools that also work: GNOME Disks → "Restore Disk Image…",
> balenaEtcher, Ventoy. Avoid Rufus' "ISO mode" → it rebuilds the partition
> table and can break UEFI boot.

Eject the stick cleanly:

```bash
sudo eject "$USB"
```

---

## 5 · Boot the target machine from USB

1. Plug the stick into the **target laptop** (not the host).
2. Power on while spamming the firmware boot-menu key:
   - Dell XPS 17: **F12**
   - ThinkPad: **F12**
   - HP: **F9**
   - Most others: **F8**, **F10**, **F11**, **Esc**
3. From the one-shot boot menu, select the entry that contains your USB stick's
   model name **and** the prefix `UEFI:` (NOT the legacy/MBR entry).
4. The Void Linux GRUB menu appears — keep the default "Void Linux installer"
   entry (or wait for the timeout).
5. After ~10-30 s you land on a console as `root` and the installer banner
   appears.

> **Secure Boot:** The ISO is **not** signed for Secure Boot. Disable Secure
> Boot in the firmware setup before the first boot, or shim signing will fail.
> You can re-enable it after the install completes (Void's GRUB will not
> validate, so leave it off unless you sign the kernel yourself).

---

## 6 · Run the installer

When you see the banner, follow the on-screen prompts. The installer is
**unattended-by-default** for the developer profile and will:

1. Bring up networking (DHCP on Ethernet, or `nmtui` for Wi-Fi if no link).
2. Show the disk picker — select your **target btrfs partition** (e.g.
   `/dev/nvme0n1p5`). The picker refuses to format the EFI partition or
   anything labelled NTFS / Windows.
3. Confirm the summary by typing `YES` (case-sensitive). Last chance to abort.
4. Wipe the chosen partition, mkfs.btrfs, mount subvolumes.
5. Bootstrap base-system + ~140 packages from the public Void mirror.
6. Configure users, sudo, services, GRUB chained next to the existing Windows
   loader.
7. Reboot. Remove the USB stick **before** GRUB starts.

Total install time on a Gen-12 laptop with NVMe + 1 Gbps internet: **8-15 min**.

---

## 7 · First-boot checks

After the system reboots, log in as **moze** (password from your `secrets.env`).

| Check | Command | Expected |
| --- | --- | --- |
| Cinnamon session | (lightdm shows it on login) | green Cinnamon wallpaper |
| Network | `nmcli c` | active connection |
| Audio | open `pavucontrol` | sink listed, no errors |
| Bluetooth | tray icon → "Devices…" | scan starts |
| Printer | Settings → Printers | CUPS server reachable |
| Trackpad gestures | three-finger swipe up | virtual-desktop overview |
| Screenshot | press **PrintScreen** | flameshot UI appears |
| Snapshots | `sudo timeshift --list` | (empty list, no errors) |
| Pre-upgrade snapshot | `sudo xbps-install -Sun \| tail` | wrapper prints `[snapshot]` line |
| GPU PRIME offload | `nvidia-smi` | NVIDIA GPU detected |
| Docker | `docker run --rm hello-world` | "Hello from Docker!" |
| VS Code | `code --version` | version printed |

---

## 8 · Recovery (if something goes wrong)

The installer **never overwrites your EFI partition** and **never touches
partitions other than the one you selected**. To roll back:

- **Boot Windows again**: in firmware setup, move the Windows boot entry above
  Void in the EFI boot order. Or hit the one-shot boot menu and pick Windows.
- **Wipe the Void partition**: boot back into the live USB, mount your old
  filesystem (e.g. `mount /dev/nvme0n1p5 /mnt`), and either restore from your
  backup or `mkfs.<oldfs> /dev/nvme0n1p5`.
- **Restore the GRUB menu only**: in the live USB,
  `mount /dev/<EFI> /mnt/efi && grub-install --efi-directory=/mnt/efi --bootloader-id=Windows --removable` (after chrooting into your old install) or use Microsoft's "Startup Repair" from a Windows install media.
- **Restore a Timeshift snapshot** (post-install): boot into the live USB,
  `xbps-install -Sy timeshift`, then `timeshift --restore --snapshot <name>`.

---

## 9 · Reporting bugs

If the installer aborts:

1. The serial / TUI shows the failing line and a log path.
2. Copy `/tmp/installer.log` and `/var/log/void-installer.log` off the live
   USB (e.g. via `scp` over Ethernet) and attach them to the bug report.
3. Note: which step failed, exact partition layout (`lsblk -f`), firmware mode
   (UEFI vs BIOS), and whether Secure Boot was on.