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
This commit is contained in:
Bernardo Magri
145
README.md
145
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 <repo>`: 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.*
|
||||
|
||||
Reference in New Issue
Block a user