Skip to content

installation.md

Latest commit

 

History

History
305 lines (200 loc) · 9.46 KB

installation.md

File metadata and controls

305 lines (200 loc) · 9.46 KB

Installation Guide

End-to-end walkthrough for installing HyprArch from the Arch Linux live ISO.

Before you start

Hardware requirements

Component Minimum
CPU x86-64 with UEFI firmware
RAM 4 GB (8 GB recommended)
Disk 40 GB (SSD strongly recommended)
Network Ethernet or Wi-Fi (required during install)
Boot mode UEFI — legacy BIOS is not supported

For removable-ESP layouts you also need a USB drive or SD card (≥2 GB).

BIOS/UEFI settings to check before booting the ISO

These are almost always required; the exact menu paths vary by vendor.

  1. Disable Secure Boot — the live ISO is not signed. You will re-enable it during the install.
  2. Set Secure Boot to Setup Mode (not User Mode) — sbctl requires Setup Mode to enroll custom keys. Look for "Clear Secure Boot keys", "Reset to Setup Mode", or "Custom Key Management".
  3. Enable TPM 2.0 — required for automatic disk unlock. Usually under Security → TPM Device or similar.
  4. Disable CSM / Legacy Boot — enables pure UEFI mode.
  5. Set the boot order so the USB comes first.

If your firmware does not have a "Setup Mode" option, enroll keys manually with sbctl enroll-keys after install; see Post-install steps.

Step 1 — Boot the Arch ISO

Download the latest Arch Linux ISO, write it to a USB drive (e.g. dd or Ventoy), and boot from it.

Step 2 — Connect to the internet

Ethernet — connected automatically.

Wi-Fi:

iwctl
  station wlan0 scan
  station wlan0 get-networks
  station wlan0 connect "Network Name"
  exit

Verify connectivity:

ping -c 3 archlinux.org

Step 3 — Run the installer

curl -sL "https://install.jallits.com/hyprarch" | bash

bootstrap.sh clones the repository and immediately launches install.sh. You can also run manually after cloning:

bash install.sh              # Interactive
bash install.sh --dry-run    # Preview all actions without changes
bash install.sh --config FILE # Replay a saved config (skip TUI)
bash install.sh --debug      # Verbose logging

Step 4 — Interactive configuration (TUI)

Phases 1–3 run automatically (preflight checks, hardware detection, geolocation). Phase 4 presents a series of prompts. Detected values are pre-filled where possible.

System

Prompt Default Notes
Hostname hyprarch Machine hostname
Timezone Auto-detected from IP E.g. America/New_York
Locale Auto-detected from IP E.g. en_US.UTF-8
Use linux-hardened kernel? Yes Recommended; the standard linux kernel is available if you need out-of-tree modules

User account

Prompt Notes
Username Lowercase, no spaces
Full name Used for GECOS field
User password Typed twice; becomes the sudo password

Disk layout

Prompt Default Notes
Installation disk — Internal NVMe/SATA; all data will be erased
ESP on removable device? No Yes = boot keys on USB/SD; harder to lose if laptop is stolen
Removable device — Only if above is Yes
Detached LUKS header? Yes Only if removable ESP is Yes; stores LUKS metadata on the removable device so internal disk is unreadable without it

Encryption

Prompt Default Notes
Encryption strength standard standard = AES-256; strong = AES-512; paranoid = Serpent-512
LUKS passphrase — Used as the fallback unlock passphrase (Plymouth prompt at boot)

Packages

Prompt Default Notes
AUR helper paru paru or yay; none skips all AUR packages (Howdy, Walker, Voxtype, etc.)

Theme

Choose a starting color theme. You can switch at any time after install with theme set <name>.

catppuccin · ethereal · everforest · gruvbox · hackerman · kanagawa · matte-black · nord · osaka-jade · ristretto · rose-pine · tokyo-night

Security

Prompt Default Notes
Enable Secure Boot? Yes Requires UEFI Setup Mode; see above
Include Microsoft Secure Boot keys? Yes Keeps firmware-signed option ROMs (GPU, NVMe) working; safe to include
Enable USBGuard? Yes Allow-lists currently connected USB devices; new devices blocked until added

Step 5 — Review and confirm

Phase 5 displays all configuration for review. This is the last chance to abort before destructive operations begin. Type yes to proceed.

Step 6 — Installation (phases 6–12)

Unattended from here. The installer:

  1. Partitions and formats the disk(s)
  2. Creates LUKS2 container and opens it
  3. Creates BTRFS subvolumes and swap file
  4. Installs base packages via pacstrap
  5. Configures security hardening, UKI, Secure Boot keys
  6. Installs the Hyprland desktop stack and AUR packages

Installation takes 10–30 minutes depending on internet speed (AUR packages download and compile).

The full log is written to /var/log/install.log on the installed system.

Post-install steps

After the first reboot you will land at the regreet login screen.

1. Verify Secure Boot

sbctl status

If Secure Boot is shown as disabled, your firmware was not in Setup Mode when keys were enrolled. To fix:

  1. Reboot, enter UEFI firmware, clear Secure Boot keys (returns to Setup Mode)
  2. Boot the installed system (Secure Boot still off)
  3. Re-enroll keys: sudo sbctl enroll-keys --microsoft
  4. Reboot — Secure Boot should now be active

2. Enroll TPM2 for auto-unlock

TPM2 enrollment is intentionally skipped during install. The installer runs from the Arch ISO with Secure Boot disabled, so any key sealed at that point would be bound to the wrong PCR 7 value and would never unseal on a real boot. The installer prints the exact commands to run — they are also here:

Root partition:

sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 /dev/nvme0n1p2

Replace /dev/nvme0n1p2 with your LUKS root partition (check with lsblk). You will be prompted for your LUKS passphrase once to authorize the enrollment.

Keystore partition (removable ESP layout only):

sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 /dev/sdX3

Replace /dev/sdX3 with your keystore partition on the removable device.

After enrolling, the root disk unlocks automatically at boot via PCR 7 (Secure Boot state). The passphrase remains as a fallback.

3. Enroll biometrics

Fingerprint (if detected at install):

fprintd-enroll                              # Right index finger (default)
fprintd-enroll -f left-index-finger         # Specify a different finger

Swipe the same finger several times when prompted.

Facial recognition (if a camera was detected at install):

sudo howdy add

For the full biometric policy — which prompts accept which sensor types — see desktop-guide.md.

4. Verify USBGuard

If USBGuard was enabled, any USB device not present during install will be blocked. To allow a new device:

sudo usbguard list-devices            # Find the device ID
sudo usbguard allow-device <id>       # Allow it for this session
sudo usbguard generate-policy >> /etc/usbguard/rules.conf  # Make permanent

5. Set up OpenClaw API key (ai-tools add-on only)

If you selected the ai-tools add-on, add your Anthropic API key so the OpenClaw gateway can connect:

echo 'OPENCLAW_API_KEY=sk-ant-...' > ~/.config/openclaw/openclaw.env
systemctl --user restart openclaw-gateway

6. Authenticate GitHub Copilot

Copilot is installed in both Neovim and VS Code but requires a one-time sign-in.

Neovim:

:Copilot auth

Follow the device-flow prompt — open the URL, enter the code, and authorise in your browser.

VS Code:

Click the Copilot icon in the status bar and follow the GitHub sign-in flow.

7. Authenticate Claude Code

claude

The first run launches an interactive auth flow. Follow the browser prompt to sign in with your Anthropic account.

Saving and replaying a configuration

After a successful install, save the config for future reinstalls:

sudo cp /var/log/install.log ~/install.log   # Log only — config is not persisted

To save the config during install for replay, capture it before reboot:

# In the installer terminal before phase 6 completes
cp /tmp/hyprarch.conf ~/hyprarch-saved.conf

Security note — hyprarch.conf contains LUKS_PASSPHRASE and USER_PASSWORD in plaintext. Store it only on an encrypted volume and delete it after use.

Replay on a fresh ISO:

bash install.sh --config hyprarch-saved.conf

Backup ESP (removable ESP layout)

If you chose a removable ESP, the internal disk cannot boot without the USB/SD card. Create a backup ESP on the internal disk for emergencies:

# After install, from the running system
sudo fdisk /dev/nvme0n1         # Create a small FAT32 partition (~500 MB)
sudo mkfs.fat -F32 -n ESP-BACKUP /dev/nvme0n1p2   # Adjust partition number
sudo mkdir /efi-backup
sudo mount /dev/nvme0n1p2 /efi-backup
sudo rsync -a /efi/ /efi-backup/
sudo umount /efi-backup

Add the backup ESP to /etc/fstab with nofail so it does not block boot if absent. Re-sync after every kernel update (sudo mkinitcpio -P writes new UKIs to /efi).
⚡