Bernardo Magri
e4800d7d8e
Some checks failed
Check / eval (push) Has been cancelled
Weekly nomarchy-gen-prune deletes only generations that are both older than 14 days and beyond the three most recent past gens (current always kept), for system and Home Manager profiles. Stock nix.gc no longer uses --delete-older-than. checks.gen-prune covers selection self-test and unit wiring; doctor points at the new tool when disk is tight.
102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# Recovery runbook — when something breaks
|
||
|
||
Ordered from "the desktop looks wrong" to "the machine won't boot".
|
||
Everything here already ships on an installed machine — you don't need a
|
||
live USB until the last resort. The theme is always the same: **nothing
|
||
in Nomarchy is destroyed by a bad change** — every rebuild is a NixOS /
|
||
Home Manager generation you can step back to, and (on BTRFS installs)
|
||
snapper keeps file-level history on top.
|
||
|
||
If the graphical session is unusable, a text console is one keystroke
|
||
away: **Ctrl+Alt+F2** gives a TTY login (the session itself runs on
|
||
tty1); log in with your normal user.
|
||
|
||
## 1. A theme or desktop change broke the session
|
||
|
||
Theme applies and `home-update` are Home Manager switches — one
|
||
generation each, so the previous desktop is still on disk:
|
||
|
||
```sh
|
||
home-manager generations # newest first, one per theme/HM change
|
||
/nix/store/…-home-manager-generation/activate # run the one you want
|
||
```
|
||
|
||
The same picker lives in the menu: **System › Recovery › Desktop
|
||
generation** lists the recent Home Manager generations — pick one and
|
||
it activates. System-level undo is **System › Recovery › System boot
|
||
generation** (boot menu) or **Files (BTRFS)** (snapper).
|
||
|
||
Or simply apply a theme you know is good: `nomarchy-state-sync apply
|
||
boreal` (or any preset). If a switch failed halfway, the state file is written
|
||
*before* the rebuild — fix the cause and re-run
|
||
`home-manager switch --flake ~/.nomarchy` (or `nomarchy-home`).
|
||
|
||
Your flake checkout is a git repo, and with auto-commit enabled every
|
||
apply is a commit — and every `nomarchy-pull`/`-rebuild`/`-home` first
|
||
sweeps pending hand edits into one, so history mirrors your generations:
|
||
`git -C ~/.nomarchy log` to see what changed, `git revert` the culprit,
|
||
then `nomarchy-home`.
|
||
|
||
## 2. The desktop won't start at all
|
||
|
||
Greeter loops, black screen after the password, session exits straight
|
||
back to tuigreet — from the Ctrl+Alt+F2 TTY:
|
||
|
||
```sh
|
||
journalctl -b -u greetd # did the session command launch?
|
||
journalctl --user -b # Hyprland + the user services
|
||
```
|
||
|
||
- Rolling back the *desktop* half is §1 (works from the TTY).
|
||
- If greetd/tuigreet itself is broken, that's system-side → §3.
|
||
- In a **VM**, a black screen is almost always missing guest OpenGL,
|
||
not your config — see docs/TESTING.md §5.
|
||
- First boot after an install came up *unthemed*: read
|
||
`/var/log/nomarchy-hm-preactivate.log` on the installed system.
|
||
|
||
## 3. A system change broke it — boot an older generation
|
||
|
||
Reboot and pick an older **NixOS generation** in the systemd-boot menu
|
||
(hold a key during firmware handoff if the menu doesn't linger; the
|
||
last 10 generations are kept). That boots yesterday's system unchanged.
|
||
|
||
Booting an old generation is temporary — the default entry is still the
|
||
broken one. Make the fix stick from the working boot: revert the change
|
||
in `~/.nomarchy` (`git -C ~/.nomarchy revert …` or edit `system.nix`
|
||
back), then `nomarchy-rebuild`.
|
||
|
||
**Automatic prune (#128):** a weekly timer (`nomarchy-gen-prune`) removes
|
||
system *and* Home Manager generations that are **older than 14 days** and
|
||
**beyond the three most recent past gens** (current + ≥3 past always kept).
|
||
Manual: `sudo nomarchy-gen-prune` (or `--dry-run`).
|
||
|
||
## 4. Files went missing or wrong — snapshots (BTRFS installs)
|
||
|
||
With `nomarchy.system.snapper.enable` (the installer's default on
|
||
BTRFS), the root filesystem has hourly/daily history, and
|
||
`nixos-rebuild-snap` leaves a snapshot right before a rebuild:
|
||
|
||
- **GUI:** menu › System › Recovery › Files (BTRFS) (btrfs-assistant;
|
||
expects a polkit password prompt).
|
||
- **Terminal/SSH:** `sudo nomarchy-snapshots` — browse a snapshot's
|
||
diff, **restore changed files** (snapper `undochange`), or **roll the
|
||
whole root back** to a snapshot and reboot. Both destructive actions
|
||
sit behind a typed-`yes` confirmation.
|
||
|
||
Snapshots are the undo for *data on disk*; the Nix config model is
|
||
undone by generations (§1/§3) — use each for its half.
|
||
|
||
## 5. Last resort — from the outside
|
||
|
||
Boot the Nomarchy ISO (any NixOS ISO works), then:
|
||
|
||
```sh
|
||
sudo mount /dev/<root> /mnt # + /mnt/boot; LUKS: cryptsetup open first
|
||
sudo nixos-enter --root /mnt # chroot with nix available
|
||
```
|
||
|
||
From there you have the full toolbox: `nixos-rebuild boot --flake
|
||
/home/<you>/.nomarchy#default` after fixing the flake, or snapper from
|
||
§4. If you get this far with something Nomarchy shipped broken, please
|
||
file it.
|