Dotfiles/docs/md/installation.md

# Installation

Three paths are available depending on how much you want to automate:

| Path | When to use |
|------|-------------|
| [Interactive TUI](#interactive-tui) | Fresh Arch system, guided dialogs |
| [Answerfile (automated)](#answerfile-automated) | Unattended or repeatable installs |
| [Custom ISO](#custom-live-iso) | Deploy from USB to multiple machines |

---

## Prerequisites

- Arch Linux (base install completed, user created)
- Internet connection
- `git` available (`sudo pacman -S git`)

---

## Interactive TUI

Clone the repo and run the installer:

```bash
git clone https://git.abdelbaki.eu/The_miro/Dotfiles.git ~/Dotfiles
bash ~/Dotfiles/setup/tui-install.sh
```

The TUI walks you through:

1. **Hostname** — optional; sets `/etc/hostname` immediately
2. **Components** — pick any combination:
   - `pkg` — package managers (yay, nvm, Rust)
   - `core` — 100+ base system packages
   - `svc` — core services (NetworkManager, cronie, fail2ban, greetd)
   - `shell` — zsh, Neovim, Yazi, Micro, Starship
3. **Desktop Environment** — Hyprland, Sway, KDE Plasma, GNOME, COSMIC, XFCE, LXQt, or none
4. **Applications** — checklist of ~50 optional apps (see [Modules](modules.md))
5. **Colorway** — optional; enter hex values to customise the CyberQueer palette

All activity is logged to `~/dotfiles-install.log`.

### Adding Modules Later

To install additional optional apps on an already-configured system:

```bash
bash ~/Dotfiles/setup/install-modules.sh
```

This presents the same app checklist without re-running core setup.

---

## Answerfile (Automated)

An **answerfile** lets the entire install — base OS _and_ dotfiles — run without any user input.

### Generating an Answerfile

```bash
bash ~/Dotfiles/setup/generate-answerfile.sh [OUTPUT_PATH]
# Default output: ~/answerfile.json
```

This dry-runs every installer dialog and saves your choices. **No software is installed.** Passwords are intentionally excluded — you will be prompted at install time.

### Answerfile Schema

```json
{
  "_generated": "2026-05-18T12:00:00+00:00",
  "drive": "/dev/sda",
  "kernel": "linux",
  "hostname": "myhost",
  "username": "amir",
  "encrypt": true,
  "fido2_root": false,
  "fido2_user": false,
  "run_tui": true,
  "components": ["pkg", "core", "svc", "shell"],
  "desktop_environment": "hyprland",
  "apps": ["firefox-browser", "vscodium", "docker"],
  "colors": {
    "COLOR_TEXT": "D6ABAB",
    "COLOR_BG": "1A1A1A",
    "COLOR_HIGHLIGHT": "E40046",
    "COLOR_DARK": "5018DD",
    "COLOR_RED": "F50505"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `drive` | string | Install target (`/dev/sda`, `/dev/nvme0n1`, …) |
| `kernel` | string | `linux`, `linux-lts`, or `linux-zen` |
| `hostname` | string | Base hostname — a MAC-address suffix is appended automatically |
| `username` | string | Primary user account name |
| `encrypt` | bool | Enable LUKS2 root encryption |
| `fido2_root` | bool | Enroll FIDO2 key for LUKS unlock |
| `fido2_user` | bool | Enroll FIDO2 key for PAM login |
| `run_tui` | bool | Run dotfiles setup automatically after base install |
| `components` | array | Dotfiles components to install |
| `desktop_environment` | string | DE name or `"none"` |
| `apps` | array | Optional app IDs (see [Modules](modules.md)) |
| `colors` | object | Optional colour overrides (omit to keep defaults) |

### Hostname Uniqueness

When `hostname` is set in the answerfile, the MAC address of the primary network interface is automatically appended:

```
myhost  →  myhost-aabbccddee11
```

This prevents hostname conflicts when the same answerfile is used across multiple machines.

### Running with an Answerfile

Place the file at `/answerfile.json` (or set the `ANSWERFILE` environment variable):

```bash
# Use default location
sudo cp ~/answerfile.json /answerfile.json
bash ~/Dotfiles/setup/tui-install.sh

# Or override the path
ANSWERFILE=~/my-setup.json bash ~/Dotfiles/setup/tui-install.sh
```

---

## Base OS Installers

Two scripts install Arch Linux itself (before the dotfiles step):

### Guided Installer (`archbaseos-guided-install.sh`)

Interactive, dialog-based. Prompts for each setting with sensible defaults. Good for hands-on installs where you want to review each option.

```bash
bash ~/installer/archbaseos-guided-install.sh
```

### Auto Installer (`arch-autoinstall.sh`)

Reads all settings from `/answerfile.json` if present; falls back to prompts for anything missing.

```bash
bash ~/installer/arch-autoinstall.sh
```

Both installers perform the same steps:

1. Partition disk (EFI 15 GiB · Root · Swap = RAM size)
2. Optionally encrypt root with LUKS2
3. Format root as Btrfs with `@` and `@home` subvolumes
4. `pacstrap` base system
5. Configure locale, timezone, hostname, user, sudo
6. Set up mkinitcpio hooks and GRUB
7. Optionally run `tui-install.sh` inside the chroot

### Disk Encryption

When encryption is enabled:

- **Primary key**: entered interactively at install time
- **Backup key**: generated automatically from `/dev/urandom`, enrolled into a second LUKS slot, and written to `/_LUKS_BACKUP_KEY` inside the new system (mode `0400`, root-readable only, inside the encrypted container)
- **FIDO2** (optional): enroll a hardware key for passwordless unlock

The backup key can be collected by Ansible — see [FreeIPA & Ansible](freeipa-ansible.md).

### mkinitcpio Hook Sets

| Scenario | Hooks |
|----------|-------|
| No encryption | `base udev autodetect microcode modconf kms consolefont block btrfs filesystems keyboard fsck` |
| LUKS + password | `base udev autodetect microcode modconf kms consolefont block encrypt lvm2 btrfs filesystems keyboard keymap fsck` |
| LUKS + FIDO2 | `base udev systemd autodetect microcode modconf kms consolefont block sd-encrypt lvm2 btrfs filesystems keyboard keymap fsck` |

---

## Custom Live ISO

See [Archiso](archiso.md) for building a bootable USB that embeds the installer and, optionally, a pre-baked answerfile for zero-touch deployment.