docs: update hardware/setup docs and add install script

Co-authored-by: Junie <junie@jetbrains.com>
2026-05-20 10:49:07 +02:00
parent bab92f0292
commit cdb0730280
4 changed files with 161 additions and 4 deletions
@@ -8,10 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]

 ### Added
+- New Ansible role `ansible/roles/system-upgrade/` that runs as the **first** role in `workstation.yml`. Performs a full `pacman -Syu`, dual-installs `linux612` (LTS, fallback) and `linux70` (stable, new default) kernels with matching headers, and verifies both initramfs images and GRUB menu entries post-install. Invoke stand-alone with `ansible-playbook ansible/workstation.yml --tags system-upgrade`; idempotent on re-runs (2026-05-18).
+- `docs/adr/0002-kernel-and-nvidia-strategy.md` — ADR documenting the LTS+stable kernel choice and the `575xx → 595.71` NVIDIA migration for Hyprland/Wayland preparation (2026-05-18).
+- Pre-flight safety gate in the new role: aborts if free space on `/` drops below `min_free_root_gb` (5 GiB by default) (2026-05-18).
 - Comprehensive NVMe benchmark for Samsung PM9A1 before firmware update: SMART health, hdparm, fio seq/rand benchmarks (2026-04-02). See `docs/tech/nvme-benchmark-pre-gxa7802q.md`.
 - CLI suite update script `scripts/update-cli-suite.sh` for Manjaro/Arch tool maintenance (2026-04-02).

 ### Changed
+- **Executed `system-upgrade` playbook on the live workstation** (2026-05-18). `pacman -Syu` upgraded **1103 packages**; kernel set now `linux612 6.12.85-1` (LTS, was 6.12.77-1) + `linux70 7.0.3-1` (NEW); NVIDIA migrated to mainline `595.71.05` for both `linux612-nvidia` and `linux70-nvidia`; legacy `*-nvidia-575xx` packages removed. Both `/boot/initramfs-6.12-x86_64.img` (54 MB) and `/boot/initramfs-7.0-x86_64.img` (122 MB) generated; GRUB regenerated with menuentries for both kernels. **Reboot required**: select `linux70` from the GRUB "Advanced options for Manjaro Linux" submenu to activate the new kernel and NVIDIA 595.71.05 modules. Logs: `logs/system-upgrade-20260518-101253-live.log`.
+- NVIDIA driver migrated from the pinned `*-nvidia-575xx` (575.64.05) branch to the mainline `*-nvidia` (595.71.05) branch via the new `system-upgrade` role. `linux612-nvidia-575xx`, `nvidia-575xx-utils`, `lib32-nvidia-575xx-utils`, `nvidia-575xx-settings` are removed; `linux612-nvidia`, `linux70-nvidia`, `nvidia-utils`, `lib32-nvidia-utils`, `opencl-nvidia`, `nvidia-settings` are installed in one atomic pacman transaction (2026-05-18).
+- `ansible/workstation.yml`: `system-upgrade` registered as the first role, guarded by `when: os_type == 'archlinux'`, with tag `system-upgrade` (2026-05-18).
+- `ansible/vars/main.yml`: added `kernel_packages`, `nvidia_kernel_modules`, `nvidia_userspace_packages`, `nvidia_packages_to_remove`, `min_free_root_gb` so future kernel/driver pins are a one-line change (2026-05-18).
+- `docs/tech/setup.md`: new bootstrap step "Run system upgrade & kernel install" before the main playbook, with `--tags system-upgrade` examples and a reboot-into-`linux70` callout (2026-05-18).
 - Samsung PM9A1 NVMe firmware update applied: GXA7401Q → GXA7801Q (non-SED variant, reboot pending to activate). All nvme-cli steps succeeded (2026-04-02).
 - Corrected firmware research: GXA7802Q is SED-only (`00B07`); non-SED drives (`00B00`) require GXA7801Q. Updated `docs/tech/firmware-update-research.md` with naming convention and correct source.
 - Updated `.gitignore`: added `logs/` and `docs/tech/capabilities/` exclusions (2026-04-02).
@@ -31,5 +39,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Synchronized software versions across documentation files (2026-03-13).

 ### Fixed
+- Resolved kitty cursor keys not working by disabling the `TERM=xterm-256color` override in `.bashrc`, allowing Kitty to correctly set `TERM=xterm-kitty`. Added Ansible management for `kitty.conf` to ensure proper terminal behavior and shell integration (2026-05-19).
+- `system-upgrade` role: GRUB menu assertion now matches Manjaro's real `menuentry 'Manjaro Linux (Kernel: X.Y.Z-MANJARO x64)'` format (counted per-kernel-family) instead of the wrong `menuentry .*linux(612|70)` regex that always returned 0 hits on Manjaro and broke the live run with a false-negative failure (2026-05-18).
+- `system-upgrade` role: migration task `changed_when` now matches pacman's progress lines `^\(N/M\)\s+(installing|upgrading|removing)\s` instead of plain substring matching, so the role's own echo lines no longer trigger spurious `changed=true` on idempotent re-runs. Verified: second live re-run reports `ok=16 changed=0 failed=0 skipped=5` (2026-05-18).
 - Resolved system unresponsiveness issue by addressing critical memory/swap pressure with increased headroom and proactive OOM killing (2026-03-17).
 - Identified failed `archlinux-keyring-wkd-sync.service` in system health check.
@@ -100,10 +100,16 @@ last_updated: '2026-04-02'
 |-------|-------|
 | Model | NVIDIA GeForce GTX 1050 Ti |
 | VRAM | 4096 MiB |
-| Driver | 575.64.05 |
+| Driver | 575.64.05 (migrating to 595.71.05 — see [ADR 0002](../adr/0002-kernel-and-nvidia-strategy.md)) |
 | GPU Temp (idle) | 47°C |
 | PCI Address | 08:00.0 |

+> **Driver strategy**: This Pascal-generation GPU is being migrated from the
+> pinned Manjaro `*-nvidia-575xx` branch to the mainline `*-nvidia` 595.71
+> branch as part of the Hyprland/Wayland preparation. The migration is
+> automated by the `system-upgrade` Ansible role and documented in
+> [ADR 0002 — Kernel and NVIDIA Driver Strategy for Hyprland/Wayland](../adr/0002-kernel-and-nvidia-strategy.md).
+
 ## Network

 ### Physical
@@ -5,7 +5,7 @@ tags:
  - setup
  - bootstrap
  - ansible
-last_updated: '2026-03-09'
+last_updated: '2026-05-18'
 ---

 # Workstation Setup Guide
@@ -41,14 +41,38 @@ This guide describes how to bootstrap the **mw-pfeddersheim-workstation** infras
   ansible-vault create ansible/vars/secrets.yml
   ```

-4. **Run the Playbook**
+4. **Run system upgrade & kernel install** (preparation for Hyprland/Wayland)
+
+   This step runs the dedicated `system-upgrade` role: full `pacman -Syu`,
+   dual-kernel install (`linux612` LTS + `linux70` stable), and NVIDIA
+   driver migration from the pinned `575xx` branch to mainline `595.71`.
+   Always preview first with `--check`. See
+   [ADR 0002](../adr/0002-kernel-and-nvidia-strategy.md) for the rationale.
+
+   ```bash
+   # Preview — never run the live playbook before --check is clean
+   ansible-playbook -i localhost, -c local \
+     --vault-password-file ansible/vault_password \
+     ansible/workstation.yml --check --tags system-upgrade
+
+   # Apply (will install/remove packages and regenerate GRUB)
+   ansible-playbook -i localhost, -c local \
+     --vault-password-file ansible/vault_password \
+     ansible/workstation.yml --tags system-upgrade
+   ```
+
+   After it finishes, **reboot and select `linux70` from the GRUB menu**
+   before continuing to step 5. Verify with `uname -r` (expect 7.0.x)
+   and `nvidia-smi` (expect driver 595.71.05).
+
+5. **Run the Playbook** (remaining roles: common, dev-tools, maintenance)
   ```bash
   ansible-playbook -i localhost, -c local --vault-password-file ansible/vault_password ansible/workstation.yml --check
   # If check passes:
   ansible-playbook -i localhost, -c local --vault-password-file ansible/vault_password ansible/workstation.yml
   ```

-5. **Initialize Maintenance**
+6. **Initialize Maintenance**
   ```bash
   ./scripts/maintenance.sh
   ```
@@ -0,0 +1,116 @@
+#!/bin/bash
+# install-hyprland.sh - Install Hyprland with Wayland on Manjaro (NVIDIA)
+# Run: bash scripts/install-hyprland.sh
+set -euo pipefail
+
+echo "=== Hyprland Installation for mw-manjaro-pf ==="
+echo "GPU: NVIDIA GTX 1050 Ti (595.71.05)"
+echo "Monitors: 3x (DP-1 + HDMI-A-1 + DVI-D-1)"
+echo ""
+
+# Step 1: Install core packages
+echo "[1/5] Installing Hyprland and core Wayland packages..."
+sudo pacman -S --needed --noconfirm \
+  hyprland \
+  hyprlock \
+  hypridle \
+  hyprshot \
+  hyprcursor \
+  xdg-desktop-portal-hyprland \
+  waybar \
+  wofi \
+  dunst \
+  kitty \
+  cliphist \
+  wl-clipboard \
+  brightnessctl \
+  pipewire \
+  pipewire-pulse \
+  wireplumber \
+  pavucontrol
+
+echo "[1/5] Done."
+
+# Step 2: NVIDIA-specific package verification
+echo "[2/5] Verifying NVIDIA packages..."
+pacman -Q nvidia-utils >/dev/null 2>&1 && echo "  nvidia-utils: OK" || echo "  nvidia-utils: MISSING"
+pacman -Q egl-wayland >/dev/null 2>&1 && echo "  egl-wayland: OK" || echo "  egl-wayland: MISSING"
+echo "[2/5] Done."
+
+# Step 3: Config directory (already created)
+echo "[3/5] Verifying configuration..."
+if [ -f ~/.config/hypr/hyprland.conf ]; then
+    echo "  hyprland.conf: OK ($(wc -l < ~/.config/hypr/hyprland.conf) lines)"
+else
+    echo "  hyprland.conf: MISSING - create it first!"
+    exit 1
+fi
+echo "[3/5] Done."
+
+# Step 4: Enable DRM KMS for NVIDIA (critical for Wayland)
+echo "[4/5] Configuring NVIDIA DRM KMS..."
+if grep -q "nvidia-drm.modeset=1" /etc/modprobe.d/*.conf 2>/dev/null; then
+    echo "  nvidia-drm.modeset=1: Already configured"
+else
+    echo "  Adding nvidia-drm.modeset=1 to /etc/modprobe.d/nvidia.conf..."
+    echo "options nvidia-drm modeset=1" | sudo tee -a /etc/modprobe.d/nvidia.conf
+    echo "  IMPORTANT: Reboot required after installation."
+fi
+
+# Early loading of NVIDIA modules
+if grep -q "nvidia" /etc/mkinitcpio.conf 2>/dev/null; then
+    echo "  mkinitcpio modules: Already configured"
+else
+    echo "  Adding NVIDIA modules to mkinitcpio..."
+    sudo sed -i 's/^MODULES=(/MODULES=(nvidia nvidia_modeset nvidia_uvm nvidia_drm /' /etc/mkinitcpio.conf
+    sudo mkinitcpio -P
+fi
+echo "[4/5] Done."
+
+# Step 5: Register Hyprland session
+echo "[5/5] Verifying session registration..."
+if [ -f /usr/share/wayland-sessions/hyprland.desktop ]; then
+    echo "  Session file: OK"
+else
+    echo "  Session file: Creating..."
+    sudo tee /usr/share/wayland-sessions/hyprland.desktop > /dev/null << 'DESKTOP'
+[Desktop Entry]
+Name=Hyprland
+Comment=An intelligent dynamic tiling Wayland compositor
+Exec=Hyprland
+Type=Application
+DesktopNames=Hyprland
+DESKTOP
+fi
+echo "[5/5] Done."
+
+echo ""
+echo "=== Installation Complete ==="
+echo ""
+echo "NEXT STEPS:"
+echo "  1. REBOOT to apply NVIDIA DRM KMS changes"
+echo "  2. Select 'Hyprland' from the login manager (SDDM)"
+echo "  3. If monitors are wrong, check names with: hyprctl monitors"
+echo "     and adjust in ~/.config/hypr/hyprland.conf"
+echo ""
+echo "MONITOR NAMES may differ from X11:"
+echo "  X11 name    -> Wayland name (expected)"
+echo "  DP-0        -> DP-1"
+echo "  HDMI-0      -> HDMI-A-1"
+echo "  DVI-D-0     -> DVI-D-1"
+echo ""
+echo "KEY BINDINGS (SUPER = Windows key):"
+echo "  SUPER+Return = Terminal (kitty)"
+echo "  SUPER+D      = Launcher (wofi)"
+echo "  SUPER+E      = File manager (dolphin)"
+echo "  SUPER+L      = Lock screen"
+echo "  SUPER+Q      = Close window"
+echo "  SUPER+F      = Fullscreen"
+echo "  SUPER+1-9    = Switch workspace"
+echo "  SUPER+Arrows = Focus monitor"
+echo ""
+echo "TROUBLESHOOTING:"
+echo "  - Cursor issues: WLR_NO_HARDWARE_CURSORS=1 is set"
+echo "  - Blank screen: Check 'nvidia-drm.modeset=1' in kernel params"
+echo "  - Flickering: Try disabling blur in hyprland.conf"
+echo "  - Monitor names: Run 'hyprctl monitors' after first launch"