Nomarchy/docs/MIGRATION.md

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.

---

Prerequisites

• NixOS 25.11. Older releases are not supported by the current Nomarchy modules.
• Flakes enabled. If you don't have them yet:

  # 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:

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.)

{
  description = "My Nomarchy Configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";
    nomarchy.url = "git+https://git.bemagri.xyz/bernardo/Nomarchy.git";
    # …or pin: "git+https://git.bemagri.xyz/bernardo/Nomarchy.git?rev=<sha>"
    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.<hostname> = nixpkgs.lib.nixosSystem {
        inherit pkgs;
        specialArgs = { inputs = nomarchy.inputs // inputs; };
        modules = [
          ./hardware-configuration.nix
          nomarchy.nixosModules.system
          ./system.nix
        ];
      };

      homeConfigurations.<user> = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        extraSpecialArgs = { inputs = nomarchy.inputs // inputs; };
        modules = [
          nomarchy.nixosModules.home
          ./home.nix
          {
            home.username = "<user>";
            home.homeDirectory = "/home/<user>";
            home.stateVersion = "25.11";
          }
        ];
      };
    };
}

Replace <hostname> and <user> 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:

{ pkgs, ... }:
{
  networking.hostName = "<hostname>";
  time.timeZone = "<your-timezone>";

  users.users."<user>" = {
    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:

{ 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 section.

3. (Optional) Pick up hardware-specific tuning

Nomarchy ships a nixos-hardware matcher. From any shell on your existing system:

nix shell nixpkgs#git -c \
  bash -c 'tmp=$(mktemp -d); git clone --depth=1 https://git.bemagri.xyz/bernardo/Nomarchy.git "$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:

{ 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

sudo nixos-rebuild switch --flake /etc/nixos#<hostname>
home-manager switch --flake /etc/nixos#<user> --impure

Reboot or systemctl restart display-manager. SDDM comes up with the Nomarchy theme; logging in as <user> 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#<hostname>
• 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.<user>.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 = "<your 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.

If your first rebuild errors out, the five most common failures and their fixes live in Troubleshooting.

---

Fallback: clean install via the live ISO

# 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.