61 lines
2.9 KiB
Markdown
61 lines
2.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What This Is
|
|
|
|
Personal NixOS system configuration for host `cesium` — a QEMU/KVM-virtualized x86_64 desktop workstation. Uses NixOS with Home Manager (channel-based, no Flakes). NixOS version is locked to 25.11.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Rebuild and apply configuration (aliased as 'rebuild')
|
|
sudo nixos-rebuild switch
|
|
|
|
# Rebuild with package upgrades (aliased as 'update')
|
|
sudo nixos-rebuild switch --upgrade
|
|
|
|
# Test configuration without persisting (loads into current session only)
|
|
sudo nixos-rebuild test
|
|
|
|
# Build without applying (useful to check for errors)
|
|
sudo nixos-rebuild build
|
|
|
|
# Optimize store and garbage collect (aliased as 'ngc')
|
|
sudo nix-store --optimise && sudo nix-collect-garbage -d
|
|
|
|
# After first install: setup SMB credentials
|
|
sudo /etc/nixos/setup-smb-credentials.sh
|
|
```
|
|
|
|
## Architecture
|
|
|
|
Entry point is `config/configuration.nix`, which imports all other modules:
|
|
|
|
```
|
|
config/configuration.nix # Top-level: imports all modules, enables Home Manager
|
|
├── hardware-configuration.nix # Auto-generated (gitignored), QEMU guest hardware
|
|
├── common.nix # System-wide: bootloader, locale, GNOME, PipeWire, packages
|
|
├── mounts.nix # CIFS/SMB mounts to TrueNAS (automount with systemd)
|
|
├── services.nix # Docker (custom data root /home/docker), ddev
|
|
├── users/sebastian.nix # User account, groups, SSH askpass
|
|
│ └── imports home.nix # Home Manager config for this user
|
|
├── home.nix # User environment: apps, shell, git, scripts, Flatpak
|
|
├── scripts.nix # Custom shell scripts (composer, lazydocker, gclb)
|
|
├── vm-guest.nix # Optional: SPICE agent for VM clipboard/file sharing
|
|
└── vm-host.nix # Optional: KVM/QEMU host with libvirtd, virt-manager
|
|
```
|
|
|
|
Key design patterns:
|
|
- `common.nix` handles all system-level config (boot, locale, desktop, audio, auto-updates, garbage collection)
|
|
- `home.nix` handles all user-level config via Home Manager (applications, shell aliases, git, vim, GTK theme, GNOME extensions, Flatpak activation scripts)
|
|
- `scripts.nix` defines Docker-wrapped CLI tools (composer, lazydocker) and git helpers using `writeShellScriptBin`
|
|
- `mounts.nix` uses systemd automount with 60s idle timeout for TrueNAS SMB shares
|
|
- `vm-guest.nix` and `vm-host.nix` are optional modules (not imported by default in configuration.nix)
|
|
|
|
## Conventions
|
|
|
|
- **Commit messages** use `[TASK]` prefix (e.g., `[TASK] Add filemounts`)
|
|
- **Formatting**: 2-space indentation for `.nix` files, 4-space for everything else (see `.editorconfig`)
|
|
- **Unfree packages** are allowed (`nixpkgs.config.allowUnfree = true`)
|
|
- `hardware-configuration.nix` is gitignored — it's auto-generated per machine |