From f1ed0d7f47110e4989ef259c7abe95accf9313e1 Mon Sep 17 00:00:00 2001 From: Bernardo Magri Date: Fri, 3 Apr 2026 21:11:03 +0100 Subject: [PATCH] docs: update README with new architecture and installer guide - Document the Modular Merging Architecture - Add step-by-step installation instructions for VM and ISO - Include configuration examples for system.nix and home.nix - Update keybindings and utility script documentation --- README.md | 145 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 91 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index aaf8842..048c05b 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,96 @@ -# Nomarchy +# 👑 Nomarchy -**Nomarchy** is a professional-grade NixOS-based distribution monorepo that replicates and enhances the Wayland workflow. It is built on a strictly declarative Nix Flake setup, providing a unified aesthetic and robust functionality while allowing users complete freedom to customize their environment. +**Nomarchy** is a professional-grade NixOS distribution that replicates the Omarchy Wayland workflow with a strictly declarative, flake-based architecture. It provides a highly polished, "it just works" experience for power users who want a beautiful Hyprland environment without sacrificing the reliability of NixOS. -## 🚀 Key Features +## ✨ Key Features -- **Purely Declarative:** Everything from system themes and fonts to wallpapers is managed via Nix. -- **Intelligent Hardware Detection:** The installer automatically identifies your hardware (CPU vendor, specific laptop models like XPS, Framework, T2 Mac) and applies optimized `nixos-hardware` profiles. -- **Modular Downstream Architecture:** Your personal customizations live in separate files (`system.nix`, `home.nix`), keeping the core "Nomarchy engine" clean and easily updatable. -- **Robust Scripting:** 150+ utility scripts are bundled with explicitly wrapped dependencies, ensuring they work regardless of your global system state. -- **Dynamic Theming:** Seamlessly switch between 20+ Base16 themes using `nomarchy-theme-selector` with automatic wallpaper and font synchronization. -- **CI/CD Ready:** Automated ISO building via GitHub Actions ensures a verified installer is always available. - -## 📦 Installation - -### 1. Build the Installer ISO -You can build the ISO locally using the provided script: -```bash -./bin/nomarchy-build-iso -``` -Alternatively, download the latest ISO from the "Actions" tab in this repository. - -### 2. Run the Installer -Once booted into the Live ISO, run the interactive installer: -```bash -/etc/install-nomarchy.sh -``` -The installer will guide you through hardware detection, disk partitioning (Ext4 or Encrypted BTRFS), and user setup. - -## 🛠️ Customization (Downstream) - -After installation, your configuration is located in `/etc/nixos/`. To customize your system without interfering with Nomarchy core: - -- **System-level:** Add NixOS modules or extra packages to `/etc/nixos/system.nix`. -- **User-level:** Add Home Manager modules or dotfiles to `/etc/nixos/home.nix`. - -To apply changes: -```bash -nomarchy-update -``` - -## 🔄 Updating - -To pull the latest Nomarchy improvements and update your system: -```bash -nomarchy-update -``` -This script will update flake inputs, rebuild your NixOS system, and switch your Home Manager environment. - -## 🎨 Controls - -- `Super + Alt + Space`: Theme Selector -- `Super + Ctrl + Space`: Font Selector -- `Super + Shift + Space`: Wallpaper Selector -- `Super + Return`: Terminal (Alacritty) -- `Super + Q`: Kill Active Window +- **Purely Declarative:** Your entire desktop—themes, fonts, wallpapers, and toolchains—is defined in code. +- **Modular Merging Architecture:** Distro code and user code are strictly separated. You can update the distro core without ever touching or breaking your personal configurations. +- **Interactive "Smart" Installer:** Detects hardware, sets up networking, localizes timezones/keymaps, and offers multi-select software profiles. +- **Erase Your Darlings (Optional):** Optional BTRFS root-wipe on boot ensures your system stays pristine and 100% declarative. +- **Dynamic Theming Engine:** 20+ built-in themes with instant UI feedback via IPC (swww, waybar, and stylix). +- **Portable State (`nomarchy-sync`):** Easily backup and sync your declarative config and dynamic state (theme/wallpaper choices) to a private Git repo. --- -*Built with ❤️ using NixOS, Hyprland, and Stylix.* + +## 📥 Installation + +### 1. Try it in a VM (Recommended) +Verify the experience without touching your hardware: +```bash +./bin/nomarchy-test-installer +``` +This builds a full graphical VM of the installer environment. Once inside, click the **Install Nomarchy** icon or run `sudo /etc/install-nomarchy.sh`. + +### 2. Build the Installer ISO +To install on physical hardware, generate your own bootable image: +```bash +nix build .#nixosConfigurations.installerIso.config.system.build.isoImage +``` +The ISO will be located at `./result/iso/nixos-*.iso`. Flash it to a USB drive and boot. + +### 3. Run the Installer +Once booted into the Live environment, launch the installer: +```bash +sudo /etc/install-nomarchy.sh +``` +The wizard will guide you through: +- **Networking:** An interactive wizard to connect to Wi-Fi if needed. +- **Hardware:** Optimized profiles for Dell XPS, Framework, Apple T2, and more. +- **Storage:** Choice between Standard Ext4 or Encrypted BTRFS with optional **Impermanence**. +- **Localization:** Searchable timezones and keyboard layout selection. +- **Profiles:** One-click setups for Development, Gaming, and Media Production. + +--- + +## 🛠️ Configuration & Usage + +Nomarchy uses a "Downstream" model. After installation, your configuration lives in `/etc/nixos/` and is split into three main parts: + +### 1. Distro Core (Upstream) +Located in `/etc/nixos/nomarchy/`. This is the engine. You should generally not modify files here. + +### 2. Your System (`system.nix`) +Add system-wide packages, services, and hardware tweaks here. +*Example: Adding a persistent directory for Docker if using Impermanence:* +```nix +environment.persistence."/persist" = { + directories = [ "/var/lib/docker" ]; +}; +``` + +### 3. Your User Environment (`home.nix`) +Add user-level packages, aliases, and dotfiles here. +*Example: Overriding the default terminal:* +```nix +nomarchy.home.terminal = "kitty"; +``` + +### Applying Changes +After editing your files, apply them instantly: +```bash +sys-update # Rebuilds the NixOS system +env-update # Reloads your Home Manager environment +``` + +--- + +## 🚀 Commands & Keybindings + +| Keybinding | Action | +| :--- | :--- | +| `Super + Alt + Space` | **Theme Selector** (Walker) | +| `Super + Ctrl + Space` | **Font Selector** | +| `Super + Shift + Space`| **Wallpaper Selector** | +| `Super + Space` | **App Launcher** (Walker) | +| `Super + Return` | Open Terminal | +| `Super + Q` | Close Window | + +### Utility Scripts +Nomarchy includes 150+ productivity scripts available in your PATH: +- `nomarchy-sync push `: Backup your setup to Git. +- `nomarchy-theme-bg-next`: Cycle to the next wallpaper in the current theme. +- `nomarchy-doctor`: (Coming Soon) Diagnose system health and state. + +--- +*Built with ❤️ using NixOS, Hyprland, Stylix, and the spirit of Omarchy.*