docs: project documentation — architecture, getting-started, packs, mcp, regtest
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
7f4a71b98d
commit
2baad92089
9 changed files with 1392 additions and 0 deletions
201
docs/getting-started.md
Normal file
201
docs/getting-started.md
Normal file
|
|
@ -0,0 +1,201 @@
|
|||
# Getting Started — adopting Omnixient on your machine
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
> **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).
|
||||
|
||||
---
|
||||
|
||||
## The two things that are truly yours
|
||||
|
||||
1. **`settings.nix`** — identity, hostname, timezone, theme, SSH keys, and
|
||||
the all-important `stateVersion`. One file, fully commented.
|
||||
2. **`hosts/<yourhost>/hardware-configuration.nix`** — the scan of your
|
||||
actual hardware. Generated by `nixos-generate-config`; never copy
|
||||
someone else's.
|
||||
|
||||
Everything else (the desktop, theming, packs) is shared and opt-in.
|
||||
|
||||
---
|
||||
|
||||
## 1. Get the repo
|
||||
|
||||
```bash
|
||||
git clone https://git.atitlan.io/aiolabs/omnixient.git ~/omni
|
||||
cd ~/omni
|
||||
```
|
||||
|
||||
You can put it anywhere; `/etc/nixos` and `~/omni` both work. Rebuild
|
||||
commands below use `--flake .#<host>` from inside the clone.
|
||||
|
||||
## 2. Generate your hardware scan
|
||||
|
||||
```bash
|
||||
sudo nixos-generate-config --show-hardware-config > /tmp/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.
|
||||
|
||||
> A stray `hardware-configuration.nix` at the repo root is gitignored on
|
||||
> purpose — the tracked copy belongs in your host directory.
|
||||
|
||||
## 3. Fill in `settings.nix`
|
||||
|
||||
Open `settings.nix` and set every field for your machine:
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
];
|
||||
}
|
||||
];
|
||||
};
|
||||
```
|
||||
|
||||
If your username differs from the template's, also create
|
||||
`users/<youruser>/home-manager.nix` — copy `users/user/home-manager.nix`,
|
||||
a one-line shim to the shared `home.nix`.
|
||||
|
||||
**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.
|
||||
|
||||
> 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.<name>.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
|
||||
|
||||
```bash
|
||||
sudo nixos-rebuild switch --flake .#<host>
|
||||
```
|
||||
|
||||
> **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:
|
||||
>
|
||||
> ```bash
|
||||
> sudo nixos-rebuild switch --flake .#<host> \
|
||||
> --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.)
|
||||
|
||||
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).
|
||||
|
||||
## 7. Set your password
|
||||
|
||||
The template ships `initialPassword = "omni"` (`modules/users.nix`).
|
||||
Change it immediately 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`).
|
||||
|
||||
---
|
||||
|
||||
## Building a custom ISO (optional)
|
||||
|
||||
```bash
|
||||
nix build .#omni-iso # → result/iso/nixos-*.iso
|
||||
```
|
||||
|
||||
The ISO is a live Omnixient environment for installing onto new hardware.
|
||||
|
||||
## 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`,
|
||||
modules, and theming fit together.
|
||||
- **[docs/system-map.md](system-map.md)** — a file-by-file map of the repo.
|
||||
Loading…
Add table
Add a link
Reference in a new issue