This repository has no description
3.1 kB
94 lines
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Repository Overview
6
7This is lassulus's personal NixOS/nix-darwin configuration repository, built on clan-core for managing multiple machines. It includes:
8- Multiple machine configurations in `machines/`
9- Configuration modules in `2configs/` and `3modules/`
10- Custom packages in `5pkgs/`
11- Various network overlays (retiolum, spora, nether, zerotier, mycelium)
12
13## Key Architecture Components
14
15### Machine Management
16- **Clan-core**: Primary framework for managing multiple machines
17- **Inventory**: Machines are tagged in `flake.nix` (laptop/server tags)
18- **Secrets**: Uses password-store for secrets management via clan.core.facts
19
20### Network Overlays
21The repository manages multiple overlay networks:
22- **Retiolum**: VPN network (access via `.r` suffix)
23- **Spora**: Mycelium-based P2P network (access via `.s` suffix)
24- **Nether**: ZeroTier-based network overlay (access via `.n` suffix)
25- **Tor**: Anonymous network access
26
27### Module System
28- `2configs/`: Main configuration modules (imported by all machines)
29- `3modules/`: Custom NixOS module definitions
30- Stockholm modules are also imported for krebs infrastructure
31
32## Common Development Commands
33
34```bash
35# Enter development shell
36nix develop
37
38# Run interactive menu (default package)
39nix run
40
41# Deploy to a specific machine
42nix run .#deploy -- <MACHINE_NAME>
43
44# Format code
45nix fmt
46
47# Build NixOS configuration
48nix build .#nixosConfigurations.<machine-name>.config.system.build.toplevel
49
50# Build Darwin configuration
51nix build .#darwinConfigurations.barnacle.system
52
53# Deploy/rebuild Darwin configuration (for barnacle)
54sudo darwin-rebuild switch --flake .#barnacle
55
56# Access machines via SSH
57ssh <machine-name>.r # via retiolum
58ssh <machine-name>.s # via spora
59ssh <machine-name>.n # via nether
60torify ssh $(pass show machines/<machine-name>/tor-hostname) # via tor
61```
62
63## Important: Git Staging for Flake Evaluation
64
65**CRITICAL**: New nix files must be staged (git add) before they are available in flake evaluation. When creating new packages, modules, or any nix files, always run `git add <files>` before testing with `nix build`, `nix run`, etc.
66
67## Machine Facts and Secrets
68
69Each machine stores its public facts in `machines/<name>/facts/` including:
70- SSH public keys
71- Network identities (retiolum, mycelium, zerotier)
72- Syncthing IDs
73- DKIM keys (for mail servers)
74
75Secrets are managed via password-store and uploaded to `/etc/secrets` on deployment.
76
77## Adding New Machines
78
791. Create directory `machines/<name>/`
802. Add `config.nix`, `physical.nix`, and optionally `disk.nix`
813. Generate facts using clan-cli
824. Add to inventory in `flake.nix`
835. Deploy using `nix run .#deploy -- <name>`
84
85## Testing
86
87- VM tests: `./5pkgs/init/test.sh`
88- Container tests are configured in `2configs/container-tests.nix`
89
90## Commit Message Guidelines
91
92- Use simple, descriptive commit messages without attribution footers
93- For flake.lock updates, use: "flake.lock: update"
94- Follow existing patterns seen in git log