From 955269f9a2a2e8f92b9384f18b389289a266ba06 Mon Sep 17 00:00:00 2001 From: Bernardo Magri Date: Sat, 25 Apr 2026 10:40:31 +0100 Subject: [PATCH] docs: add MIGRATION.md for in-place adoption from existing NixOS Documents the layered-adoption path: add nomarchy as a flake input, build a single pkgs with nomarchy.overlays.default, wire nomarchy.nixosModules into both nixosSystem and a standalone homeManagerConfiguration, and rebuild. Preserves the user's hardware-configuration, hostname, and account; no reformat. Calls out the conflicts an existing config will hit (DM, Hyprland, audio, NetworkManager, user groups, /etc/os-release rebrand, autoLogin) with explicit mkForce/drop-this-line guidance. Points at the live-ISO clean install as the alternative for users who'd rather start fresh. Co-Authored-By: Claude Opus 4.7 --- MIGRATION.md | 255 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..b6c19a7 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,255 @@ +# Migrating an existing NixOS install to Nomarchy + +You already have NixOS running and you want the Nomarchy desktop without +reformatting. This is the in-place path. Your `/`, `/home`, hostname, and +user account are preserved; Nomarchy is layered on as a flake input. + +> Prefer a clean disk? Skip to the [fallback](#fallback-clean-install-via-the-live-iso). + +--- + +## Prerequisites + +- NixOS 25.11. Older releases are not supported by the current Nomarchy + modules. +- Flakes enabled. If you don't have them yet: + ```nix + # somewhere in your existing config + nix.settings.experimental-features = [ "nix-command" "flakes" ]; + ``` + Apply with `sudo nixos-rebuild switch` once before proceeding. + +--- + +## 1. Move to a flake-based config + +If you already have `/etc/nixos/flake.nix`, skip to step 2. + +Back your existing config up: + +```bash +sudo cp /etc/nixos/configuration.nix /etc/nixos/configuration.nix.bak +``` + +Then create `/etc/nixos/flake.nix` with the structure below. (This is the +same shape the Nomarchy installer produces — see +`installer/install.sh:generate_flake_config` in the upstream repo.) + +```nix +{ + description = "My Nomarchy Configuration"; + + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11"; + nomarchy.url = "github:bemagri/nomarchy"; # or pin to a commit/tag + nixos-hardware.url = "github:NixOS/nixos-hardware/master"; + home-manager = { + url = "github:nix-community/home-manager/release-25.11"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + }; + + outputs = { self, nixpkgs, nomarchy, home-manager, nixos-hardware, ... }@inputs: + let + system = "x86_64-linux"; + pkgs = import nixpkgs { + inherit system; + overlays = [ nomarchy.overlays.default ]; + config.allowUnfree = true; + }; + in + { + nixosConfigurations. = nixpkgs.lib.nixosSystem { + inherit pkgs; + specialArgs = { inputs = nomarchy.inputs // inputs; }; + modules = [ + ./hardware-configuration.nix + nomarchy.nixosModules.system + ./system.nix + ]; + }; + + homeConfigurations. = home-manager.lib.homeManagerConfiguration { + inherit pkgs; + extraSpecialArgs = { inputs = nomarchy.inputs // inputs; }; + modules = [ + nomarchy.nixosModules.home + ./home.nix + { + home.username = ""; + home.homeDirectory = "/home/"; + home.stateVersion = "25.11"; + } + ]; + }; + }; +} +``` + +Replace `` and `` with your real values. Two-track Nomarchy: +the system block uses `nomarchy.nixosModules.system`; the standalone +home-manager block uses `nomarchy.nixosModules.home`. Both consume the same +`pkgs` so overlays stay in sync. + +## 2. Move your existing settings into `system.nix` and `home.nix` + +The Nomarchy installer also generates these files — copy that template, or +create minimal versions to start: + +`/etc/nixos/system.nix`: + +```nix +{ pkgs, ... }: +{ + networking.hostName = ""; + time.timeZone = ""; + + users.users."" = { + isNormalUser = true; + extraGroups = [ "wheel" "video" "render" "audio" "networkmanager" ]; + }; + + # Compressed RAM swap — near-free memory headroom. + zramSwap.enable = true; + + system.stateVersion = "25.11"; +} +``` + +`/etc/nixos/home.nix`: + +```nix +{ pkgs, ... }: +{ + home.packages = with pkgs; [ + btop + fastfetch + chromium + # …add anything you want; firefox/thunar/mpv/mako/etc. ship with Nomarchy. + ]; +} +``` + +Move any user/services/packages you had in `configuration.nix` over to +`system.nix`. Do **not** redefine things Nomarchy already provides (display +manager, Hyprland, PipeWire, NetworkManager) unless you want to override +them — see the [conflicts](#conflicts-to-resolve-before-rebuild) section. + +## 3. (Optional) Pick up hardware-specific tuning + +Nomarchy ships a `nixos-hardware` matcher. From any shell on your existing +system: + +```bash +nix shell nixpkgs#git -c \ + bash -c 'tmp=$(mktemp -d); git clone --depth=1 https://github.com/bemagri/nomarchy "$tmp" >/dev/null 2>&1; \ + source "$tmp/installer/hardware-db.sh"; nomarchy_detect_hw' +``` + +Output is a list like: + +``` +MODULE common-cpu-amd +MODULE common-gpu-amd +MODULE common-pc-laptop +MODULE framework-13-amd-ai-300-series +OPT isFramework=true +``` + +Drop a `hardware-selection.nix` next to your flake: + +```nix +{ inputs, ... }: +{ + imports = [ + inputs.nixos-hardware.nixosModules.common-cpu-amd + inputs.nixos-hardware.nixosModules.common-gpu-amd + inputs.nixos-hardware.nixosModules.framework-13-amd-ai-300-series + ]; + nomarchy.hardware.isFramework = true; +} +``` + +…and add `./hardware-selection.nix` to the system module list in `flake.nix`. +Skip this entirely if you don't have a matching device. + +## 4. Rebuild + +```bash +sudo nixos-rebuild switch --flake /etc/nixos# +home-manager switch --flake /etc/nixos# --impure +``` + +Reboot or `systemctl restart display-manager`. SDDM comes up with the +Nomarchy theme; logging in as `` lands you in Hyprland with the full +Nomarchy desktop. + +After this, the daily workflow is two commands: + +- **System changes** (services, kernel, hardware) → + `sudo nixos-rebuild switch --flake /etc/nixos#` +- **Dotfiles, themes, user packages** → `nomarchy-env-update` (runs the + standalone `home-manager switch` for you, no system rebuild) + +--- + +## Conflicts to resolve before rebuild + +`nomarchy.nixosModules.system` enables a desktop stack. If your existing +`configuration.nix` already configures any of these, only one setting wins +and it's whichever has higher Nix priority. Fix these explicitly: + +| Area | Nomarchy default | What to do if you already have it | +| --- | --- | --- | +| Display manager | SDDM (Wayland) | Disable yours: `services.xserver.displayManager.gdm.enable = lib.mkForce false;` (or whatever you had) | +| Default session | `hyprland-uwsm` | Drop your `services.displayManager.defaultSession` | +| Hyprland | `programs.hyprland.enable = true; withUWSM = true;` | Drop your `programs.hyprland` setting | +| Audio | PipeWire (alsa+pulse+jack) | Remove `services.pulseaudio.enable = true;` — NixOS errors if both are on | +| Networking | NetworkManager | Drop `networking.wireless.enable = true;` (if set) | +| Graphics | `hardware.graphics.enable = true` (was `hardware.opengl`) | Probably already enabled — fine | +| User groups | needs `video render networkmanager` | Add to your `users.users..extraGroups` | +| `/etc/os-release` | `ID=nomarchy`, `NAME=Nomarchy` | A few third-party scripts grep `ID=nixos` — adjust them or rely on `ID_LIKE` (TBD) | +| autoLogin | `enable = true; user = "nomarchy";` (mkDefault) | Override with `services.displayManager.autoLogin.user = ""` or disable | + +Impermanence is **off** unless you set `nomarchy.system.impermanence.enable = true`, +and it requires a BTRFS layout with a `root-blank` snapshot. Don't enable it +on an existing install — the live ISO is the right path for that. + +--- + +## Fallback: clean install via the live ISO + +```bash +# In a checkout of the Nomarchy repo: +nomarchy-test-live-iso # boots the ISO in QEMU to evaluate +# Or burn the produced .iso to a USB and boot it on real hardware. +``` + +The ISO autologins to a Hyprland live session that points you at: + +- `sudo /etc/install.sh` — install (BTRFS + LUKS + subvolumes per + `installer/disko-golden.nix`, auto-detects hardware via `hardware-db.sh`, + runs `home-manager switch` inside `nixos-enter` so the first login is + fully themed). +- `sudo /etc/install.sh --dry-run` — generate the flake into a tmpdir and + parse-check it without touching the disk. +- `sudo /etc/install.sh --resume` — pick up an interrupted run. + +After install, the system at `/etc/nixos/` is the same shape this guide +produces by hand. + +--- + +## Verification (in-place migration) + +1. `cat /etc/os-release` → `NAME=Nomarchy`, `ID=nomarchy`. +2. SDDM theme is the Nomarchy purple/blue panel. +3. After login: waybar shows the Nomarchy logo on the left, theme switcher + under Style → Theme works. +4. `which btop fastfetch waybar walker nomarchy-env-update` → all on PATH. +5. `nomarchy-env-update` returns clean (proves standalone HM is wired and + `nomarchy.nixosModules.home` is in scope). + +If anything is wrong, your old config is intact at +`/etc/nixos/configuration.nix.bak` — `sudo nixos-rebuild switch -I nixos-config=/etc/nixos/configuration.nix.bak` +will roll back.