docs: comprehensive README with architecture, identity system, feature flags, work profile
This commit is contained in:
243
README.md
243
README.md
@@ -1,38 +1,253 @@
|
|||||||
# m3ta-home — Portable User Profiles
|
# m3ta-home — Portable User Profiles for NixOS
|
||||||
|
|
||||||
Centralized home-manager configurations for NixOS systems.
|
Centralized, portable Home-Manager configurations. Manages user identities, preferences, feature sets, and assets across multiple NixOS hosts — from desktops and laptops to headless servers.
|
||||||
Separates user identity, preferences, and feature sets for portable deployment.
|
|
||||||
|
|
||||||
## Structure
|
One repo, all your machines. Change once, deploy everywhere.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
```
|
```
|
||||||
m3ta-home/
|
m3ta-home/
|
||||||
├── lib/ ← mkHome, mkDevShell
|
├── flake.nix ← Entry point: inputs, lib, homeManagerModules
|
||||||
├── modules/ ← Home-Manager module exports
|
├── lib/
|
||||||
├── profiles/ ← base, contexts, sets
|
│ ├── default.nix ← Re-exports mkHome
|
||||||
├── users/ ← identity, preferences, secrets
|
│ └── mkHome.nix ← Composition engine (WHO + WHERE + WHAT)
|
||||||
└── secrets/ ← Agenix-encrypted user secrets
|
├── modules/
|
||||||
|
│ ├── default.nix ← Module aggregation for flake export
|
||||||
|
│ └── paths.nix ← "m3ta-home".paths.srcRoot (pure eval compatibility)
|
||||||
|
├── profiles/
|
||||||
|
│ ├── base/ ← Always loaded: shell, CLI tools, secrets, nix settings
|
||||||
|
│ ├── contexts/
|
||||||
|
│ │ ├── desktop/ ← GUI host: WM, apps, theme, terminal, XDG
|
||||||
|
│ │ └── server/ ← Headless: minimal
|
||||||
|
│ └── sets/ ← Optional feature bundles
|
||||||
|
│ ├── coding/ ← core, editors, languages, LSP, agents
|
||||||
|
│ ├── gaming/ ← Steam, Gamescope, GPU tools
|
||||||
|
│ └── media/ ← OBS, ffmpeg, kdenlive, yt-dlp
|
||||||
|
├── users/
|
||||||
|
│ └── m3tam3re/
|
||||||
|
│ ├── identities/
|
||||||
|
│ │ ├── private.nix ← Personal: git (m3tm3re), SSH, JJ
|
||||||
|
│ │ └── work.nix ← Work: git (sascha.koenig), SSH, JJ
|
||||||
|
│ └── preferences/ ← Identity-independent: cliphist, difftastic
|
||||||
|
└── assets/
|
||||||
|
└── wallpapers/ ← Wallpaper collection (referenced via srcRoot)
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage in nixos-config
|
## The Three Dimensions
|
||||||
|
|
||||||
|
`mkHome` composes a complete Home-Manager configuration from three axes:
|
||||||
|
|
||||||
|
| Dimension | Options | Description |
|
||||||
|
|-----------|---------|-------------|
|
||||||
|
| **WHO** | `user` + `identity` | Which user, which identity (private/work) |
|
||||||
|
| **WHERE** | `context` | `desktop` or `server` — mutually exclusive |
|
||||||
|
| **WHAT** | `sets` | `coding`, `gaming`, `media` — freely combinable |
|
||||||
|
|
||||||
|
```nix
|
||||||
|
mkHome {
|
||||||
|
user = "m3tam3re";
|
||||||
|
identity = "private"; # ← "private" or "work"
|
||||||
|
context = "desktop"; # ← "desktop" or "server"
|
||||||
|
sets = ["coding" "gaming" "media"];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **Base** is always imported (shell, CLI tools, nix settings, nix-colors/dracula theme)
|
||||||
|
2. **Context** is loaded based on `context` — exactly one of `desktop` or `server`
|
||||||
|
3. **Sets** are loaded on top — any combination of `coding`, `gaming`, `media`
|
||||||
|
4. **Identity** overrides git username/email, SSH match blocks, and Jujutsu config
|
||||||
|
5. **Feature flags** in the consuming host selectively enable/disable individual modules
|
||||||
|
|
||||||
|
### Assertions
|
||||||
|
|
||||||
|
- `gaming` and `media` sets require `desktop` context (enforced via Nix assertions)
|
||||||
|
- `coding` works in both `desktop` and `server` contexts
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### In nixos-config (flake.nix)
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
inputs.m3ta-home = {
|
inputs.m3ta-home = {
|
||||||
url = "git+ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-home.git";
|
url = "git+ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-home";
|
||||||
inputs.nixpkgs.follows = "nixpkgs";
|
inputs.nixpkgs.follows = "nixpkgs";
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Per-Host Configuration
|
||||||
|
|
||||||
|
The consuming repo (`nixos-config`) maps hosts to profiles:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
# hosts/common/users/m3tam3re.nix
|
# hosts/common/users/m3tam3re.nix
|
||||||
|
hostProfiles = {
|
||||||
|
m3-kratos = { context = "desktop"; sets = ["coding" "gaming" "media"]; };
|
||||||
|
m3-atlas = { context = "server"; sets = ["coding"]; };
|
||||||
|
m3-helios = { context = "server"; sets = []; };
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Then enables specific feature flags per host:
|
||||||
|
|
||||||
|
```nix
|
||||||
home-manager.users.m3tam3re = {
|
home-manager.users.m3tam3re = {
|
||||||
imports = [
|
imports = [
|
||||||
(inputs.m3ta-home.lib.mkHome {
|
(m3ta-lib.mkHome {
|
||||||
user = "m3tam3re";
|
user = "m3tam3re";
|
||||||
identity = "private";
|
identity = "private";
|
||||||
context = "desktop";
|
inherit (profile) context sets;
|
||||||
sets = [ "coding" "gaming" "media" ];
|
|
||||||
})
|
})
|
||||||
|
hostFlags # ← per-host enable/disable of individual modules
|
||||||
];
|
];
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Host-Specific Overrides
|
||||||
|
|
||||||
|
Monitor layouts, window rules, and XDG/MIME settings stay in `nixos-config`:
|
||||||
|
- `hosts/m3-kratos/home.nix` — dual DP monitors, Hyprland workspaces
|
||||||
|
- `hosts/m3-ares/home.nix` — laptop eDP + HDMI, tuxedo-backlight
|
||||||
|
- Server hosts need no `home.nix` (no desktop config)
|
||||||
|
|
||||||
|
## Identity System: Private vs. Work
|
||||||
|
|
||||||
|
The identity system allows switching between personal and work contexts on any machine — same dotfiles, different git identity, SSH config, and Jujutsu settings.
|
||||||
|
|
||||||
|
### How Identities Work
|
||||||
|
|
||||||
|
| | **Private** | **Work** |
|
||||||
|
|---|---|---|
|
||||||
|
| **Git user** | m3tm3re | sascha.koenig |
|
||||||
|
| **Git email** | p@m3ta.dev | sascha.koenig@azintec.com |
|
||||||
|
| **JJ email** | m@m3tam3re.com | sascha.koenig@azintec.com |
|
||||||
|
| **SSH hosts** | code.m3ta.dev, github.com, private infra | git.az-gruppe.com, AZ servers |
|
||||||
|
|
||||||
|
### Use Case: Work Laptop
|
||||||
|
|
||||||
|
If you bring a work NixOS machine into your fleet, you can use the same `m3ta-home` repo with a different identity:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
# On the work machine's nixos-config:
|
||||||
|
(m3ta-lib.mkHome {
|
||||||
|
user = "m3tam3re";
|
||||||
|
identity = "work"; # ← switches git, SSH, JJ to work profile
|
||||||
|
context = "desktop";
|
||||||
|
sets = ["coding"];
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
This gives you:
|
||||||
|
- Your familiar shell setup (fish, starship, nushell)
|
||||||
|
- Your CLI tools (fzf, bat, eza, zoxide, etc.)
|
||||||
|
- Your editor configs (neovim, zed)
|
||||||
|
- Work git identity and SSH configuration automatically
|
||||||
|
- No gaming, media, or personal apps
|
||||||
|
|
||||||
|
### Adding a New Identity
|
||||||
|
|
||||||
|
1. Create `users/<username>/identities/<identity>.nix`
|
||||||
|
2. Define git, SSH, and JJ settings for that identity
|
||||||
|
3. Reference it via `identity = "<identity>"` in mkHome
|
||||||
|
|
||||||
|
## Feature Flags
|
||||||
|
|
||||||
|
Every module in m3ta-home has an `enable` option. Base modules default to `true`, everything else defaults to `false`. Flags are set per-host in the consuming repo.
|
||||||
|
|
||||||
|
### Available Flags
|
||||||
|
|
||||||
|
```
|
||||||
|
base.shell.fish.enable # Fish shell
|
||||||
|
base.shell.nushell.enable # Nushell
|
||||||
|
base.shell.starship.enable # Starship prompt
|
||||||
|
base.cliTools.fzf.enable # Fuzzy finder
|
||||||
|
base.cliTools.bat.enable # Cat replacement
|
||||||
|
base.cliTools.eza.enable # Ls replacement
|
||||||
|
base.cliTools.zellij.enable # Terminal multiplexer
|
||||||
|
base.cliTools.zoxide.enable # Smarter cd
|
||||||
|
base.cliTools.direnv.enable # Directory-based env
|
||||||
|
base.cliTools.television.enable # TV fuzzy finder
|
||||||
|
base.cliTools.nitch.enable # System info
|
||||||
|
base.secrets.enable # pass-wayland, pinentry
|
||||||
|
|
||||||
|
desktop.wm.hyprland.enable # Hyprland window manager
|
||||||
|
desktop.wm.rofi.enable # Rofi launcher
|
||||||
|
desktop.wm.wayland.enable # Wayland tools (grim, slurp, etc.)
|
||||||
|
desktop.apps.obsidian.enable # Obsidian
|
||||||
|
desktop.apps.office.enable # LibreOffice
|
||||||
|
desktop.apps.crypto.enable # Bisq2, Monero, Trezor
|
||||||
|
desktop.theme.fonts.enable # Desktop fonts
|
||||||
|
desktop.theme.wallpapers.enable # Wallpaper collection
|
||||||
|
|
||||||
|
coding.editors.neovim.enable # Neovim
|
||||||
|
coding.editors.zed.enable # Zed editor (desktop only)
|
||||||
|
coding.lsp.enable # Language servers
|
||||||
|
coding.packages.enable # Bruno, Insomnia
|
||||||
|
coding.languages.python.enable
|
||||||
|
coding.languages.javascript.enable
|
||||||
|
coding.languages.typescript.enable
|
||||||
|
coding.languages.rustToolchain.enable
|
||||||
|
coding.languages.go.enable
|
||||||
|
|
||||||
|
profiles.gaming.steam.enable
|
||||||
|
profiles.gaming.gamescope.enable
|
||||||
|
profiles.gaming.gpu.enable
|
||||||
|
|
||||||
|
profiles.media.obs.enable
|
||||||
|
profiles.media.ffmpeg.enable
|
||||||
|
profiles.media.kdenlive.enable
|
||||||
|
profiles.media.ytDlp.enable
|
||||||
|
profiles.media.handbrake.enable
|
||||||
|
```
|
||||||
|
|
||||||
|
## Adding a New Module
|
||||||
|
|
||||||
|
1. Create the `.nix` file in the appropriate directory under `profiles/`
|
||||||
|
2. Define an `options` block with `mkEnableOption`
|
||||||
|
3. Define a `config` block with `mkIf cfg.enable`
|
||||||
|
4. Add the import to the parent `default.nix`
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
# profiles/sets/coding/languages/elixir.nix
|
||||||
|
{ config, lib, pkgs, ... }:
|
||||||
|
with lib; let
|
||||||
|
cfg = config.coding.languages.elixir;
|
||||||
|
in {
|
||||||
|
options.coding.languages.elixir.enable = mkEnableOption "Elixir language support";
|
||||||
|
|
||||||
|
config = mkIf cfg.enable {
|
||||||
|
home.packages = with pkgs; [ elixir ];
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Then add `./elixir` to `profiles/sets/coding/languages/default.nix`.
|
||||||
|
|
||||||
|
## Assets
|
||||||
|
|
||||||
|
Static assets (wallpapers, etc.) live in `assets/`. They are referenced via the `"m3ta-home".paths.srcRoot` option, which points to the flake source root and works in pure evaluation mode:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
source = "${config."m3ta-home".paths.srcRoot}/assets/wallpapers";
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
| Input | Purpose |
|
||||||
|
|-------|---------|
|
||||||
|
| `nixpkgs` | Package set (follows nixos-config's nixpkgs) |
|
||||||
|
| `home-manager` | Home-Manager modules |
|
||||||
|
| `nix-colors` | Dracula theme palette (used everywhere) |
|
||||||
|
| `m3ta-nixpkgs` | Custom packages (zellij-ps, rofi-project-opener) and HM modules |
|
||||||
|
| `agenix` | Secret management |
|
||||||
|
| `NUR` | Additional packages |
|
||||||
|
|
||||||
|
## Important Notes
|
||||||
|
|
||||||
|
- **Overlays** are managed at the NixOS level in `nixos-config`, not here. `home-manager.useGlobalPkgs = true` ensures HM sees them.
|
||||||
|
- **Host-specific config** (monitor layouts, window rules, XDG/MIME) belongs in `nixos-config/hosts/<name>/home.nix`, not here.
|
||||||
|
- **Pure evaluation**: All file references use `"m3ta-home".paths.srcRoot` instead of relative `../..` paths.
|
||||||
|
|||||||
Reference in New Issue
Block a user