diff --git a/docs/getting-started.md b/docs/getting-started.md index 7eabcbe..360c8e3 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,201 +1,243 @@ -# Getting Started — adopting Omnixient on your machine +# Getting Started — adopting Omnixient -Omnixient is a personal NixOS config published as a starting point, not a -turnkey distro installer. Adopting it means **forking it and making it -yours**. Almost everything you need to change is funnelled through one -file (`settings.nix`) plus your machine's hardware scan. +Omnixient is a Hyprland desktop you build on top of, not a turnkey installer. +There are **two ways to adopt it**: -This guide assumes you already have a working NixOS install (or are -installing from the official NixOS ISO). If you don't know NixOS at all, -read [the NixOS manual](https://nixos.org/manual/nixos/stable/) and -[NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/) first. +1. **As a flake input (recommended)** — your own small repo pins Omnixient as + a dependency. You never edit Omnixient's files, so `nix flake update omni` + pulls upstream changes with zero merge conflicts. This is the path below. +2. **By forking** — clone Omnixient and edit it directly. More control over + Omnixient internals, but you maintain a fork. See + [Forking instead](#forking-instead) at the end. -> **Heads-up:** the `omni` host (`hosts/omni/`) is the maintainer's -> actual machine — a Framework Desktop with WireGuard, the aiolabs dev -> environment, and a Bitcoin/Lightning workflow. You'll want your own -> host directory rather than inheriting all of that. See -> [Step 4](#4-make-it-your-host). +This guide assumes a working NixOS install (or the official NixOS ISO). New +to NixOS? Read the [NixOS manual](https://nixos.org/manual/nixos/stable/) +and the [NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/) +first. --- -## The two things that are truly yours +## What's yours vs. what's Omnixient's -1. **`settings.nix`** — identity, hostname, timezone, theme, SSH keys, and - the all-important `stateVersion`. One file, fully commented. -2. **`hosts//hardware-configuration.nix`** — the scan of your - actual hardware. Generated by `nixos-generate-config`; never copy - someone else's. +In the dependency model your repo is tiny and owns only **your** stuff: -Everything else (the desktop, theming, packs) is shared and opt-in. +- `flake.nix` — pins Omnixient + your `settings` (identity, hostname, theme…). +- `hosts//default.nix` — which packs/options you want. +- `hosts//hardware-configuration.nix` — your real hardware scan. + +Omnixient (the desktop, theming, packs, modules) comes from the pinned input. +You update it like any dependency; it never touches your files. --- -## 1. Get the repo +## 1. Scaffold your config ```bash -git clone https://git.atitlan.io/aiolabs/omnixient.git ~/omni -cd ~/omni +nix flake init -t github:/omnixient # writes flake.nix + hosts/myhost/ +cd ``` -You can put it anywhere; `/etc/nixos` and `~/omni` both work. Rebuild -commands below use `--flake .#` from inside the clone. +This drops a starter that already wires `omni.lib.mkSystem` + +`omni.nixosModules.omni`. Open `flake.nix` and: + +- set `omni.url` to the real repo (pin a tag for reproducibility, e.g. + `github:/omnixient/v1.0.0`); +- fill in the `settings` block: + +```nix +settings = { + user = "alice"; + gitName = "Alice Example"; + gitEmail = "alice@example.com"; + hostName = "myhost"; + timeZone = "America/New_York"; + theme = "tokyo-night"; # any module under Omnixient's modules/themes/ + sshKeys = [ ]; # e.g. [ "ssh-ed25519 AAAA… alice@myhost" ] + stateVersion = "24.11"; # ⚠ the release you FIRST installed — never change +}; +``` + +> **`stateVersion`** is the field that bites people: it is *not* your +> current NixOS version. It pins stateful defaults from your original +> install; changing it on a live system can break data. ## 2. Generate your hardware scan ```bash -sudo nixos-generate-config --show-hardware-config > /tmp/hardware-configuration.nix +sudo nixos-generate-config --show-hardware-config \ + > hosts/myhost/hardware-configuration.nix ``` -Review it (it captures your disks, filesystems, kernel modules, CPU -microcode). You'll place it into your host directory in step 4. +This captures your disks, filesystems, kernel modules, and CPU microcode. +The template ships a placeholder — replace it before building on real +hardware. -> A stray `hardware-configuration.nix` at the repo root is gitignored on -> purpose — the tracked copy belongs in your host directory. +## 3. Choose packs and options -## 3. Fill in `settings.nix` - -Open `settings.nix` and set every field for your machine: +Edit `hosts/myhost/default.nix`. Core (base system + Hyprland desktop + +theming) is always on; everything else is opt-in: ```nix -{ - user = "alice"; # your Linux username - gitName = "Alice Example"; - gitEmail = "alice@example.com"; - hostName = "nimbus"; # your machine's hostname - timeZone = "America/New_York"; - theme = "tokyo-night"; # any of modules/themes/*.nix - sshKeys = [ - "ssh-ed25519 AAAAC3Nza... alice@nimbus" - ]; - stateVersion = "24.05"; # ⚠ the release you FIRST installed — never change later -} -``` +omni = { + enable = true; + desktop.enable = true; + user = settings.user; + theme = settings.theme; -The comments in the file explain each field. The **`stateVersion`** -warning is the one that bites people: it is *not* your current NixOS -version — it pins stateful defaults from your original install, and -changing it on a live system can break data. - -## 4. Make it your host - -The cleanest path is your own host directory, and there's a ready-made -template to copy — **`hosts/example/`** (a minimal, generic host, kept -build-checked in `flake.nix` so it never rots): - -```bash -cp -r hosts/example hosts/nimbus # name it your host -cp /tmp/hardware-configuration.nix \ - hosts/nimbus/hardware-configuration.nix # your real scan (step 2) -``` - -`hosts/example/default.nix` imports your hardware scan + the shared Omnixient -base and enables a sensible starter set of packs — edit it to taste (it's -fully commented). Then register the host in `flake.nix` (copy the -`example` block, rename it): - -```nix -# flake.nix → nixosConfigurations -nimbus = mkSystem "nimbus" { - inherit system; - user = settings.user; # add `devEnv = true;` if you want the dev-env - extraSpecialArgs = { inherit settings; }; - extraHmArgs = { inherit settings; }; - modules = [ - { home-manager.sharedModules = [ - inputs.nix-colors.homeManagerModules.default - inputs.lazyvim.homeManagerModules.default - inputs.walker.homeManagerModules.default - ]; - } - ]; + packs.development.enable = true; # editors, LSPs, compilers, container CLIs + packs.media.enable = true; # gimp, inkscape, mpv, obs, … + # packs.gaming.enable = true; # Steam, Lutris, Wine + # packs.bitcoin.enable = true; # a real bitcoind + lightning node }; ``` -If your username differs from the template's, also create -`users//home-manager.nix` — copy `users/user/home-manager.nix`, -a one-line shim to the shared `home.nix`. +The full catalog is in **[docs/packs.md](packs.md)**. -**What's maintainer-specific in `hosts/omni/` — leave it out of yours:** -the `framework-desktop-*` hardware module, `wireguard.nix` (a private -tunnel), `omni.packs.aiolabs.enable` and the whole `dev-env { … }` block -(the aiolabs Lightning workflow), and the Framework `fwupd`/polkit rule. +## 4. Track your files, then build -> Prefer the absolute-minimum change? You *can* skip renaming: replace -> `hosts/omni/hardware-configuration.nix` with your scan, strip the -> maintainer-specific lines from `hosts/omni/default.nix`, set -> `settings.hostName`, and build `.#omni`. The flake attribute name and -> your machine's hostname are independent. A dedicated host dir is just -> tidier once you have more than one machine. - -## 5. Choose your packs - -Core (base system + Hyprland desktop + theming) is always on. Everything -else is opt-in via `omni.packs..enable`. The full catalog and the -standalone-import story are in **[docs/packs.md](packs.md)**. - -```nix -omni.packs.media.enable = true; # gimp, inkscape, mpv, obs, … -omni.packs.development.enable = true; # editors, LSPs, compilers, container CLIs -omni.packs.gaming.enable = true; # Steam, Lutris, Wine -# omni.packs.bitcoin.enable = true; # a real bitcoind + lightning node (opt-in import) -``` - -## 6. Build and switch +Flakes only see **git-tracked** files, so stage everything first: ```bash -sudo nixos-rebuild switch --flake .# +git init && git add . +sudo nixos-rebuild switch --flake .#myhost ``` -> **Flakes not enabled yet?** If your existing NixOS install hasn't -> turned on flakes, this first command fails with something like -> `experimental Nix feature 'nix-command' is disabled` — flakes are -> opt-in on stock NixOS. Bootstrap the first build with a one-shot flag: +> **Flakes not enabled yet?** On a stock NixOS install the first command +> fails with `experimental Nix feature 'nix-command' is disabled` — flakes +> are opt-in. Bootstrap the first build with a one-shot flag: > > ```bash -> sudo nixos-rebuild switch --flake .# \ +> sudo nixos-rebuild switch --flake .#myhost \ > --extra-experimental-features "nix-command flakes" > ``` > -> You only need this **once** — Omnixient's own config enables -> `nix-command` and `flakes` (`configuration.nix`), so every later -> `nixos-rebuild` / `omni-rebuild` works without the flag. -> (Alternatively, add -> `nix.settings.experimental-features = [ "nix-command" "flakes" ];` -> to your *current* `/etc/nixos/configuration.nix`, run -> `sudo nixos-rebuild switch`, then come back to this step.) +> Your `hosts/myhost/default.nix` enables flakes permanently, so later +> rebuilds don't need the flag. -On the next boot you'll have the Omnixient desktop. After that, the bundled -helpers take over (`omni-rebuild`, `omni-update`, `omni-theme`, -`omni-help` lists them all — note they're individual `omni-*` -commands, not a single dispatcher). +On the next boot you'll have the Omnixient desktop, plus the bundled helpers +(`omni-rebuild`, `omni-update`, `omni-theme`; `omni-help` lists them). -## 7. Set your password +## 5. Set your password -The template ships `initialPassword = "omni"` (`modules/users.nix`). -Change it immediately after first login: +The default is `initialPassword = "omni"`. Change it after first login: ```bash passwd ``` -For a permanent declarative password, switch to -`hashedPasswordFile` with a sops-managed secret (see -`modules/secrets.nix` and `.sops.yaml`). +For a declarative password, use `hashedPasswordFile` with a sops secret +(see [Secrets](#secrets-optional)). + +--- + +## Already on NixOS? + +Adopting Omnixient on a machine you already run is the same flow, with three +differences — because you're protecting a working system: + +1. **Enable flakes first** (if you're on channels): add + `nix.settings.experimental-features = [ "nix-command" "flakes" ];` to your + current `/etc/nixos/configuration.nix` and `sudo nixos-rebuild switch`. +2. **Reuse what you have** — copy your existing + `hardware-configuration.nix` into `hosts/myhost/`, and carry your + **existing `stateVersion` across verbatim** (never bump it). +3. **Preview before you switch** — Omnixient is a full opinionated desktop + (Hyprland + greetd login manager + services), so it *will* change your + desktop: + ```bash + sudo nixos-rebuild build --flake .#myhost # build only, catch errors + sudo nixos-rebuild build-vm --flake .#myhost && ./result/bin/run-*-vm # try it in a VM + ``` + When happy, `switch`. If it's not what you want, roll back instantly from + the boot menu or `sudo nixos-rebuild switch --rollback` — your old + generation is untouched. + +> If you currently run GNOME/KDE/another login manager, expect overlap with +> greetd + Hyprland; preview in the VM first and disable the old desktop in +> the same switch. + +--- + +## Updating + +```bash +nix flake update omni # pull the latest Omnixient +sudo nixos-rebuild switch --flake .#myhost +``` + +This **can't** conflict with your config — Omnixient is a pinned dependency, +not a checkout. Roll back by reverting `flake.lock`; pin a release with +`omni.url = "github:/omnixient/v1.0.0"`. + +--- + +## Secrets (optional) + +Secrets are **off by default** — a fresh config builds with zero secret +setup. Enable them only if you turn on something that needs one (e.g. an +MCP server) or add your own. Omnixient ships the sops-nix *module*; you supply +the *data*, with **your own** age key: + +```bash +# 1. your master key (back this up!) +nix-shell -p age --run 'age-keygen -o ~/.config/sops/age/keys.txt' # prints age1… + +# 2. declare yourself the recipient (copy Omnixient's .sops.yaml.example) +$EDITOR .sops.yaml # paste your age1… public key + +# 3. create + encrypt your secrets (copy secrets/omni.yaml.example) +nix-shell -p sops --run 'sops secrets/omni.yaml' + +# 4. TRACK the encrypted file — flakes only see git-tracked files +git add .sops.yaml secrets/omni.yaml +``` + +Then enable it in `hosts/myhost/default.nix` and rebuild: + +```nix +omni.secrets.enable = true; +``` + +`modules/secrets.nix` reads `/home//.config/sops/age/keys.txt`, and +only activates when the flag is set *and* `secrets/omni.yaml` exists — so +it never gets in your way until you ask for it. --- ## Building a custom ISO (optional) +From an Omnixient checkout (or `nix build github:/omnixient#omni-iso`): + ```bash -nix build .#omni-iso # → result/iso/nixos-*.iso +nix build .#omni-iso # → result/iso/nixos-*.iso ``` -The ISO is a live Omnixient environment for installing onto new hardware. +A live Omnixient environment for installing onto new hardware. + +--- + +## Forking instead + +If you want to modify Omnixient's own modules/themes rather than just consume +them, fork the repo and edit in place: + +```bash +git clone https://github.com//omnixient.git ~/omni && cd ~/omni +``` + +Then model a host on **`hosts/example/`** (copy it to `hosts//`, +drop in your hardware scan, register it in `flake.nix`), and edit +`settings.nix`. The trade-off is the usual fork one: to get upstream +changes you `git pull` / rebase and resolve conflicts in any files you've +edited. The dependency model above avoids that entirely, which is why it's +recommended for most adopters. + +--- ## Where to go next - **[docs/packs.md](packs.md)** — the pack catalog, enabling/disabling, and reusing packs on a non-Omnixient NixOS. -- **[docs/ARCHITECTURE.md](ARCHITECTURE.md)** — how the flake, `mksystem`, +- **[docs/ARCHITECTURE.md](ARCHITECTURE.md)** — how the flake, `mkSystem`, modules, and theming fit together. - **[docs/system-map.md](system-map.md)** — a file-by-file map of the repo.