109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What This Repo Is
|
|
|
|
A NixOS flake configuration managing multiple hosts (desktops, laptops, servers). All hosts share common settings via `hosts/configuration_common.nix` and are assembled in `hosts/default.nix`.
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Format all nix files
|
|
nix fmt
|
|
|
|
# Build a host configuration (no activation)
|
|
nixos-rebuild build --flake .#<host>
|
|
|
|
# Switch the current host
|
|
sudo nixos-rebuild switch --flake .#<host>
|
|
|
|
# Build a custom package
|
|
nix build .#<package>
|
|
|
|
# Edit an age-encrypted secret
|
|
agenix -e secrets/<path>.age
|
|
|
|
# Re-key all secrets after adding a new host key to secrets/secrets.nix
|
|
agenix -r
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Entry Points
|
|
|
|
- `flake.nix` — defines inputs (nixpkgs stable=25.11, unstable, home-manager, agenix, lanzaboote, jovian-nixos, microvm, impermanence, noctalia) and calls `hosts/default.nix` for `nixosConfigurations`
|
|
- `hosts/default.nix` — instantiates every host via `lib.nixosSystem`; contains the `mkHM` helper that wires home-manager into a host's modules list
|
|
|
|
### Host Structure
|
|
|
|
Each host lives in `hosts/<name>/`:
|
|
- `default.nix` — imports either `../../modules/desktop` or `../../modules/server`, sets the module options (`myDesktop.*` / `myServer.*`), and adds host-specific settings
|
|
- `home.nix` — host-specific home-manager config (merged with `hosts/home.nix` for desktops or `hosts/home_server.nix` for servers)
|
|
- `hardware-configuration.nix` — generated hardware config
|
|
|
|
Shared host-level files:
|
|
- `hosts/configuration_common.nix` — applied to every host: SSH (key-only, no root), locale, nix GC/settings, zsh, fonts, auto-upgrade flake URL
|
|
- `hosts/home.nix` — desktop home-manager base
|
|
- `hosts/home_server.nix` — server home-manager base
|
|
|
|
### Module System
|
|
|
|
Two top-level NixOS modules expose all major knobs as typed options:
|
|
|
|
**`modules/desktop/default.nix`** — `myDesktop.*`
|
|
- `windowManager`: `"niri"` (default) | `"sway"` | `"kde"`
|
|
- `cpu`: `"amd"` | `"intel"` | `"none"` — selects KVM kernel params
|
|
- `virtualisation.enable` — podman (docker-compat) + qemu/libvirt + virt-manager
|
|
- `syncthing.{enable,devices,folders}`
|
|
- `openrgb.{enable,motherboard}`
|
|
- `laptop.{enable,lidSwitch,hibernateDelaySec}`
|
|
- `nitrokey.enable`
|
|
- `niri.hotkeyVariant`: `"default"` | `"lifebook"`
|
|
- `git.signingKey` — SSH key for commit signing
|
|
- `extraSystemPackages`
|
|
|
|
**`modules/server/default.nix`** — `myServer.*`
|
|
- `sshPort` (default 2220)
|
|
- `virtualisation.{enable,cpu}` — podman only (no libvirt)
|
|
- `fail2ban.enable`
|
|
- `autoUpgrade.enable` (default true)
|
|
- `uid`, `sudoRequiresPassword`, `extraGroups`, `extraSystemPackages`
|
|
|
|
Service bundles are imported as lists in host `default.nix`:
|
|
- `modules/services/server/` — kabtop services (gitea, nextcloud, matrix, coturn, hydra, mealie, etc.)
|
|
- `modules/services/nas/` — jupiter services (nfs, vaultwarden, syncthing, paperless)
|
|
- `modules/services/dmz/` — dmz services (gitea runner microVM)
|
|
- `modules/services/kabtopci/` — kabtopci services (hydra, gitea runner)
|
|
- `modules/services/nasbackup/` — nasbak backup jobs
|
|
|
|
### Secrets (agenix)
|
|
|
|
`secrets/secrets.nix` declares which age public keys (users + host SSH keys) can decrypt each `.age` file. Add a new host: add its `ssh-ed25519` host key to `secrets/secrets.nix` in the relevant groups, then run `agenix -r` to re-key.
|
|
|
|
### Custom Packages & Overlays
|
|
|
|
- `packages/` — custom packages (e.g. `corosync-qdevice`), imported at `flake.nix` level
|
|
- `overlays/` — nixpkgs overlays applied globally
|
|
- Per-host overlays: set `nixpkgs.overlays` inside the host's `default.nix` so only that host is affected
|
|
|
|
### Disk Layouts
|
|
|
|
`disko/` contains reusable disko modules: `btrfs.nix`, `btrfs_luks.nix`, `nas_luks.nix` — referenced during initial install.
|
|
|
|
## Active Hosts
|
|
|
|
| Host | Role | WM / Notes |
|
|
|---|---|---|
|
|
| hades | Desktop | niri, AMD, Secure Boot (lanzaboote) |
|
|
| lifebook | Laptop | niri, Intel, Secure Boot |
|
|
| steamdeck | Gaming | KDE/Jovian-NixOS, Secure Boot |
|
|
| kabtop | Main server | gitea, nextcloud, matrix+bridges, coturn, hydra, mealie |
|
|
| kabtopci | CI server | hydra, nix-serve |
|
|
| jupiter | NAS | nfs, vaultwarden, syncthing, paperless |
|
|
| dmz | DMZ | gitea Actions homerunner microVM |
|
|
| nasbak | NAS backup | — |
|
|
| kubemaster-1 | K8s master | — |
|
|
|
|
See `SERVICES.md` for port-level service details per host.
|