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 <noreply@anthropic.com>
This commit is contained in:
Bernardo Magri
255
MIGRATION.md
Normal file
255
MIGRATION.md
Normal file
@@ -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.<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`:
|
||||||
|
|
||||||
|
```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`:
|
||||||
|
|
||||||
|
```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#<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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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.
|
||||||
Reference in New Issue
Block a user