docs: add CLAUDE.md with repository architecture guidance
Create comprehensive documentation for Claude Code instances working in this repository, including build commands, architectural patterns, and workflows.
This commit is contained in:
parent
5bd15ecc5d
commit
65f6a14f69
GPG key ID:
8563E358D4E8040E
1 changed files with 213 additions and 0 deletions
213
CLAUDE.md
Normal file
213
CLAUDE.md
Normal file
|
|
@ -0,0 +1,213 @@
|
||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## Build and Deployment Commands
|
||||||
|
|
||||||
|
### Building Configurations
|
||||||
|
```bash
|
||||||
|
# Build a NixOS configuration (creates ./result symlink)
|
||||||
|
just build <hostname>
|
||||||
|
# or
|
||||||
|
nixos-rebuild build --flake .#<hostname>
|
||||||
|
|
||||||
|
# Build home-manager configuration
|
||||||
|
home-manager build --flake .#sajenim@<hostname>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deploying Changes
|
||||||
|
```bash
|
||||||
|
# Apply NixOS configuration locally (requires sudo)
|
||||||
|
just switch <hostname>
|
||||||
|
# or
|
||||||
|
sudo nixos-rebuild switch --flake .#<hostname>
|
||||||
|
|
||||||
|
# Deploy to remote host
|
||||||
|
just deploy <hostname>
|
||||||
|
# or
|
||||||
|
nixos-rebuild switch --flake .#<hostname> --target-host <hostname> --use-remote-sudo
|
||||||
|
|
||||||
|
# Apply home-manager configuration
|
||||||
|
home-manager switch --flake .#sajenim@<hostname>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Code Quality
|
||||||
|
```bash
|
||||||
|
# Format all Nix files using alejandra
|
||||||
|
nix fmt
|
||||||
|
|
||||||
|
# Check flake and evaluate all configurations
|
||||||
|
nix flake check
|
||||||
|
```
|
||||||
|
|
||||||
|
### Secret Management
|
||||||
|
```bash
|
||||||
|
# Rekey secrets using YubiKey (after adding/modifying secrets)
|
||||||
|
agenix-rekey edit <secret-name>
|
||||||
|
agenix-rekey rekey
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
### Flake Structure
|
||||||
|
This is a NixOS flake-based configuration managing two hosts:
|
||||||
|
- **fuchsia**: Desktop workstation (gaming, development, XMonad)
|
||||||
|
- **viridian**: Server (multimedia, services, containers)
|
||||||
|
|
||||||
|
The flake follows the standard structure from Misterio77's starter configs.
|
||||||
|
|
||||||
|
### Configuration Layers
|
||||||
|
|
||||||
|
**NixOS System Configuration** (`nixos/`):
|
||||||
|
```
|
||||||
|
nixos/
|
||||||
|
├── common/
|
||||||
|
│ ├── global/ # Base system config for all hosts
|
||||||
|
│ │ ├── age.nix # Agenix secret management with YubiKey
|
||||||
|
│ │ ├── env.nix # Environment variables
|
||||||
|
│ │ ├── nix.nix # Nix daemon, flakes, garbage collection
|
||||||
|
│ │ └── ssh.nix # SSH server config
|
||||||
|
│ ├── optional/ # Opt-in features
|
||||||
|
│ │ ├── ephemeral-btrfs.nix # Impermanence with btrfs root wipe
|
||||||
|
│ │ ├── persist.nix # Persistence paths for ephemeral root
|
||||||
|
│ │ └── yubikey.nix # YubiKey support
|
||||||
|
│ └── users/ # User-specific system settings
|
||||||
|
├── fuchsia/
|
||||||
|
│ ├── configuration.nix
|
||||||
|
│ └── services/ # Desktop services (X11, pipewire, flatpak, etc.)
|
||||||
|
└── viridian/
|
||||||
|
├── configuration.nix
|
||||||
|
├── services/ # Server services (traefik, minecraft, IRC, etc.)
|
||||||
|
└── multimedia/ # *arr stack (sonarr, radarr, jellyfin, etc.)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Home-Manager User Configuration** (`home-manager/`):
|
||||||
|
```
|
||||||
|
home-manager/sajenim/
|
||||||
|
├── global/ # Base home config
|
||||||
|
├── features/ # Modular user features
|
||||||
|
│ ├── cli/ # Shell, terminal utilities
|
||||||
|
│ ├── desktop/ # GUI applications, window manager
|
||||||
|
│ ├── editors/ # Text editors configuration
|
||||||
|
│ ├── games/ # Gaming-related configs
|
||||||
|
│ ├── printing/ # Printer utilities
|
||||||
|
│ └── university/ # Academic tools
|
||||||
|
├── fuchsia.nix # Desktop profile
|
||||||
|
└── viridian.nix # Server profile (minimal)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Architectural Patterns
|
||||||
|
|
||||||
|
**Module Organization**: Configuration is split between:
|
||||||
|
- `nixos/common/global/`: Imported by ALL hosts (mandatory base config)
|
||||||
|
- `nixos/common/optional/`: Opt-in features imported per-host
|
||||||
|
- `nixos/<hostname>/`: Host-specific hardware and services
|
||||||
|
- `home-manager/sajenim/features/`: Composable user environment features
|
||||||
|
|
||||||
|
**Imports Pattern**: Each host's `configuration.nix` composes its full system by:
|
||||||
|
1. Importing `../common/global` (base system)
|
||||||
|
2. Importing selected `../common/optional/*` modules
|
||||||
|
3. Importing `../common/users/<username>` (user accounts)
|
||||||
|
4. Importing host-specific services from `./services/`
|
||||||
|
5. Setting host-specific options (hostname, firewall, etc.)
|
||||||
|
|
||||||
|
**Impermanence**: Uses opt-in persistence with ephemeral btrfs root:
|
||||||
|
- Root filesystem (`/`) wiped on every boot
|
||||||
|
- Only `/nix`, `/persist`, and `/boot` survive reboots
|
||||||
|
- Services must explicitly declare what to persist in `/persist`
|
||||||
|
- Secrets use persistent SSH keys at `/persist/etc/ssh/` for decryption
|
||||||
|
|
||||||
|
**Secret Management**:
|
||||||
|
- Encrypted with agenix using host SSH keys
|
||||||
|
- Master key stored on YubiKey for rekeying
|
||||||
|
- Rekeyed secrets stored in `nixos/common/global/secrets/rekeyed/<hostname>/`
|
||||||
|
- Decryption happens during system activation using persistent SSH keys
|
||||||
|
|
||||||
|
**Overlays**: Applied globally via `nixos/common/global/default.nix`:
|
||||||
|
- `additions`: Custom packages from `pkgs/`
|
||||||
|
- `modifications`: Patches to existing packages (e.g., dmenu theming)
|
||||||
|
- `unstable-packages`: Makes `pkgs.unstable.*` available for newer versions
|
||||||
|
|
||||||
|
**Unfree Packages**: Allowlist is centralized in `nixos/common/global/default.nix`
|
||||||
|
- Default policy: only free software
|
||||||
|
- Exceptions listed explicitly (steam, minecraft-server)
|
||||||
|
- Do NOT use `allowUnfreePredicate` in other modules (won't merge)
|
||||||
|
|
||||||
|
### Flake Inputs
|
||||||
|
External dependencies include:
|
||||||
|
- `nixpkgs` (25.05 stable), `nixpkgs-unstable`
|
||||||
|
- `home-manager` (follows nixpkgs)
|
||||||
|
- `agenix`, `agenix-rekey` (secret management)
|
||||||
|
- `impermanence` (ephemeral root filesystem)
|
||||||
|
- `crowdsec` (security)
|
||||||
|
- `nixvim` (personal Neovim config, external flake)
|
||||||
|
- `xmonad-config` (personal XMonad config, external flake)
|
||||||
|
- `nix-minecraft` (declarative Minecraft server)
|
||||||
|
|
||||||
|
Personal flakes (nixvim, xmonad-config) are maintained in separate repositories
|
||||||
|
and imported as flake inputs. They are updated independently via `nix flake update`.
|
||||||
|
|
||||||
|
## Working with This Configuration
|
||||||
|
|
||||||
|
### Adding a New Host
|
||||||
|
1. Create `nixos/<hostname>/` directory
|
||||||
|
2. Add `configuration.nix` and `hardware-configuration.nix`
|
||||||
|
3. Add SSH host keys (ed25519 and RSA) to the host directory
|
||||||
|
4. Update `flake.nix` to add the new `nixosConfiguration`
|
||||||
|
5. Configure secrets: update age.rekey to include new host key
|
||||||
|
|
||||||
|
### Adding a Service
|
||||||
|
Services are organized by host in `nixos/<hostname>/services/`:
|
||||||
|
- Create a subdirectory for complex services (e.g., `traefik/`)
|
||||||
|
- Each service gets its own `default.nix`
|
||||||
|
- Import in `nixos/<hostname>/services/default.nix` or `configuration.nix`
|
||||||
|
- Declare persistence paths if using ephemeral root
|
||||||
|
- Use agenix for any credentials
|
||||||
|
|
||||||
|
### Modifying Packages
|
||||||
|
- **Custom packages**: Add to `pkgs/` and reference in `pkgs/default.nix`
|
||||||
|
- **Patching packages**: Add patches to `overlays/patches/`, modify overlay in
|
||||||
|
`overlays/default.nix`
|
||||||
|
- **Unfree packages**: Add to allowlist in `nixos/common/global/default.nix`
|
||||||
|
|
||||||
|
### Testing Changes
|
||||||
|
1. Build configuration: `just build <hostname>`
|
||||||
|
2. Check for evaluation errors: `nix flake check`
|
||||||
|
3. Review changes before switching
|
||||||
|
4. Switch: `just switch <hostname>` (local) or `just deploy <hostname>` (remote)
|
||||||
|
|
||||||
|
### Managing Secrets
|
||||||
|
- Secrets are encrypted per-host and stored in
|
||||||
|
`nixos/common/global/secrets/rekeyed/<hostname>/`
|
||||||
|
- Edit secrets: `agenix-rekey edit <secret-name>`
|
||||||
|
- After editing, rekey all hosts: `agenix-rekey rekey`
|
||||||
|
- YubiKey required for rekeying operations
|
||||||
|
- Host SSH keys at `/persist/etc/ssh/` are used for automatic decryption
|
||||||
|
|
||||||
|
## Important Conventions
|
||||||
|
|
||||||
|
### Line Length
|
||||||
|
Keep all Nix code to a maximum of 100 characters per line for consistency.
|
||||||
|
|
||||||
|
### Module Naming
|
||||||
|
- System-level services: `nixos/<hostname>/services/<service-name>/default.nix`
|
||||||
|
- User-level features: `home-manager/sajenim/features/<category>/<feature>.nix`
|
||||||
|
|
||||||
|
### Persistence Declarations
|
||||||
|
When adding services to hosts with ephemeral root, declare persistence:
|
||||||
|
```nix
|
||||||
|
environment.persistence."/persist" = {
|
||||||
|
directories = [
|
||||||
|
"/var/lib/service-name"
|
||||||
|
];
|
||||||
|
files = [
|
||||||
|
"/var/lib/service-name/config.conf"
|
||||||
|
];
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Comments
|
||||||
|
This codebase uses structured comments to explain configuration choices:
|
||||||
|
- Block comments at file top explain module purpose
|
||||||
|
- Inline comments explain non-obvious configuration decisions
|
||||||
|
- Group related options with visual separators when helpful
|
||||||
Loading…
Add table
Add a link
Reference in a new issue