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