Compare commits
10 Commits
4f7cdc02c5
...
0f6e780f6c
| Author | SHA1 | Date | |
|---|---|---|---|
| 0f6e780f6c | |||
| bead8ebc6d | |||
| 4b2f1864bf | |||
| 6074d99996 | |||
| 46bb05cec2 | |||
| 5c2083e2da | |||
| b0763e691b | |||
| 9d095ffb7e | |||
| 9c1d77eb47 | |||
| baafd655ca |
159
CLAUDE.md
159
CLAUDE.md
@@ -1,159 +0,0 @@
|
|||||||
# CLAUDE.md
|
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with
|
|
||||||
code in this repository.
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
This is a NixOS flake-based configuration repository managing both system
|
|
||||||
configurations (NixOS) and user environments (home-manager). The repository
|
|
||||||
follows a modular architecture with separate host configurations for physical
|
|
||||||
machines, VMs, and standalone home-manager setups.
|
|
||||||
|
|
||||||
## Essential Commands
|
|
||||||
|
|
||||||
### Building and Testing
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Build a NixOS system configuration
|
|
||||||
nix build -L '.#nixosConfigurations.<hostname>.config.system.build.toplevel'
|
|
||||||
|
|
||||||
# Build and run a VM with disko
|
|
||||||
nix build -L '.#nixosConfigurations.vm.config.system.build.vmWithDisko'
|
|
||||||
./result/bin/disko-vm
|
|
||||||
|
|
||||||
# Build home-manager configuration
|
|
||||||
nix build -L '.#homeConfigurations.work.activationPackage'
|
|
||||||
|
|
||||||
# Build the custom neovim package
|
|
||||||
nix build -L '.#nvim.packages.x86_64-linux.nvim'
|
|
||||||
```
|
|
||||||
|
|
||||||
### Development
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Update flake inputs
|
|
||||||
nix flake update
|
|
||||||
|
|
||||||
# Check flake for errors
|
|
||||||
nix flake check
|
|
||||||
|
|
||||||
# Show flake outputs
|
|
||||||
nix flake show
|
|
||||||
|
|
||||||
# Enter development shell for neovim
|
|
||||||
cd dots/.config/nvim && nix develop
|
|
||||||
```
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
### Repository Structure
|
|
||||||
|
|
||||||
The repository is organized into distinct layers:
|
|
||||||
|
|
||||||
- **`flake.nix`**: Root flake defining inputs and outputs. Uses `utils.dirNames` to automatically discover host directories.
|
|
||||||
- **`hosts/`**: NixOS system configurations (andromache, astyanax, vm). Each host has its own directory with `default.nix` and hardware configuration.
|
|
||||||
- **`home/`**: home-manager configurations, split into `hosts/` (per-host configs) and `modules/` (reusable user-level modules).
|
|
||||||
- **`modules/`**: Reusable NixOS modules for system-level configuration (audio, networking, fonts, etc.).
|
|
||||||
- **`dots/`**: Dotfiles and configurations, including a complete neovim flake at `dots/.config/nvim/`.
|
|
||||||
- **`utils/`**: Helper functions like `dirNames` for discovering directories.
|
|
||||||
|
|
||||||
### Key Architectural Patterns
|
|
||||||
|
|
||||||
**Host Discovery**: The flake uses `lib.genAttrs hostDirNames` to automatically
|
|
||||||
generate `nixosConfigurations` from directories in `hosts/`. Adding a new host
|
|
||||||
only requires creating a directory with a `default.nix`.
|
|
||||||
|
|
||||||
**Secrets Management**: Uses sops-nix with age encryption. Secrets are stored
|
|
||||||
in a separate private repository (`nix-secrets`) referenced as a flake input.
|
|
||||||
The `modules/secrets/default.nix` module provides options and templates for
|
|
||||||
injecting secrets into configurations.
|
|
||||||
|
|
||||||
**Disk Management**: Uses disko for declarative disk partitioning. The
|
|
||||||
`modules/disko.zfs-encrypted-root.nix` module provides a reusable ZFS-on-root
|
|
||||||
setup with encryption, taking a `device` parameter.
|
|
||||||
|
|
||||||
**Neovim as Flake**: The neovim configuration at `dots/.config/nvim/` is a
|
|
||||||
standalone flake using nixCats. It's referenced as a flake input in the root
|
|
||||||
and included in system packages. This allows independent development and
|
|
||||||
version control.
|
|
||||||
|
|
||||||
**Home Manager Integration**: Each NixOS host can include home-manager
|
|
||||||
configuration through `home-manager.users.<username>`, which imports from
|
|
||||||
`home/hosts/<hostname>`. Standalone home-manager configurations (like `work`)
|
|
||||||
are also available for non-NixOS systems.
|
|
||||||
|
|
||||||
**Module Parameterization**: Modules like `networking.nix` and
|
|
||||||
`secrets/default.nix` accept parameters and expose options, making them
|
|
||||||
reusable across hosts with different settings.
|
|
||||||
|
|
||||||
### Input Dependencies
|
|
||||||
|
|
||||||
- **nixpkgs**: Main package source (nixos-unstable)
|
|
||||||
- **nixos-hardware**: Hardware-specific configurations
|
|
||||||
- **disko**: Declarative disk partitioning
|
|
||||||
- **sops-nix**: Secrets management with age/sops
|
|
||||||
- **nix-secrets**: Private repository with encrypted secrets (git+ssh)
|
|
||||||
- **home-manager**: User environment management
|
|
||||||
- **nixgl**: OpenGL wrapper for non-NixOS systems
|
|
||||||
- **firefox-addons**: Firefox extension packages
|
|
||||||
- **nvim**: Local flake at `dots/.config/nvim/`
|
|
||||||
|
|
||||||
## Working with Hosts
|
|
||||||
|
|
||||||
### Adding a New NixOS Host
|
|
||||||
|
|
||||||
1. Create a new directory in `hosts/<hostname>/`
|
|
||||||
2. Add `default.nix` with imports and host-specific configuration
|
|
||||||
3. Add `hard.nix` for hardware configuration (generated by nixos-generate-config)
|
|
||||||
4. The host will automatically be discovered by the flake
|
|
||||||
|
|
||||||
### Adding a New Home Manager Host
|
|
||||||
|
|
||||||
1. Create directory in `home/hosts/<hostname>/`
|
|
||||||
2. Add `default.nix` importing desired modules from `home/modules/`
|
|
||||||
3. For standalone (non-NixOS) configs, add entry to `homeConfigurations` in root `flake.nix`
|
|
||||||
|
|
||||||
## Secrets Workflow
|
|
||||||
|
|
||||||
Secrets are managed with sops-nix and stored in the private `nix-secrets` repository:
|
|
||||||
|
|
||||||
1. Secrets are encrypted with age using keys at `~/.config/sops/age/keys.txt`
|
|
||||||
2. The `modules/secrets/default.nix` module reads from `${nix-secrets}/secrets.yaml`
|
|
||||||
3. Secrets are exposed as files in `/run/secrets/` with proper ownership
|
|
||||||
4. Templates can combine multiple secrets (see taskwarrior sync configuration)
|
|
||||||
|
|
||||||
## Common Patterns
|
|
||||||
|
|
||||||
### Import Patterns
|
|
||||||
|
|
||||||
Modules use different import patterns based on their needs:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
# Simple module (no parameters)
|
|
||||||
imports = [ ../../modules/audio.nix ];
|
|
||||||
|
|
||||||
# Parameterized module (function call)
|
|
||||||
imports = [ (import ../../modules/networking.nix { hostName = "andromache"; }) ];
|
|
||||||
|
|
||||||
# Module with all parameters
|
|
||||||
imports = [
|
|
||||||
(import ../../modules/secrets {
|
|
||||||
inherit lib inputs config;
|
|
||||||
})
|
|
||||||
];
|
|
||||||
```
|
|
||||||
|
|
||||||
### Special Args
|
|
||||||
|
|
||||||
- `inputs`: Flake inputs, passed as `specialArgs` to NixOS and `extraSpecialArgs` to home-manager
|
|
||||||
- `lib`, `config`, `pkgs`: Standard NixOS/home-manager module arguments
|
|
||||||
|
|
||||||
### Username Handling
|
|
||||||
|
|
||||||
Each host defines a `username` variable (either "h" or "hektor") used for:
|
|
||||||
|
|
||||||
- User creation in NixOS
|
|
||||||
- Home directory paths
|
|
||||||
- Secrets ownership
|
|
||||||
- Home-manager configuration
|
|
||||||
Reference in New Issue
Block a user