191 lines
6.8 KiB
Markdown
191 lines
6.8 KiB
Markdown
# 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.
|