diff options
| -rw-r--r-- | CLAUDE.md | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..797acd7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,79 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this is + +A flake-based NixOS + home-manager configuration (nixpkgs/home-manager/stylix pinned to the `26.05` release branches) that defines two hosts: + +- **`nixy`**: the desktop/laptop (ASUS TUF, Intel + NVIDIA PRIME offload). Includes home-manager for user `boss`, stylix theming, and the X11 window managers. +- **`nixnode`**: a Linode VPS serving `tehbox.org` (nginx vhosts, ACME, the mailserver, cgit at `git.tehbox.org`, the wireguard hub, ZNC, a SuperTuxKart server, and a goaccess dashboard). There is no home-manager here. + +## Commands + +```bash +# Rebuild and switch the local machine (nixy). Bash alias: flake-rebuild +sudo nixos-rebuild switch --flake ~/nixos-configuration # or: nh os switch ~/nixos-configuration + +# Evaluate/build without switching (the quickest way to check a change) +nixos-rebuild build --flake .#nixy +nix build .#nixosConfigurations.nixnode.config.system.build.toplevel + +# Deploy the server +./server-rebuild.sh # nixos-rebuild --target-host to nixnode +deploy .#nixnode # alternative via deploy-rs (interactive sudo) + +# Flake checks (deploy-rs schema checks) +nix flake check + +# Standalone packages exposed by the flake +nix build .#teh-website +nix build .#stk-installers + +# Secrets +sops secrets/general.yaml +``` + +There are no tests or linter. "Does it evaluate/build" is the check. `nil` is installed as the Nix LSP. + +## Gotchas + +- **Flakes only see git-tracked files.** You must `git add` a new file before a rebuild can see it. This matters even more for `modules/`, which auto-imports files (see below). +- **`flake.lock` is gitignored**, so inputs aren't pinned in the repo. +- The **`YATwm` and `STK` inputs are `git+file://` paths** on this machine (`~/Documents/Coding/WM/YATwm`, `~/stk`). Evaluating either host needs them present. `nixnode` is always built from `nixy` and then pushed. +- Indentation is **4 spaces**. Multi-line `''` strings (shell scripts, configs) usually start at column 0 rather than following the Nix indentation. Match that. +- Leave `system.stateVersion` and `home.stateVersion` alone. + +## Architecture + +### Flake wiring (`flake.nix`) +Each host is assembled as `./modules` + `./hardware-setups/<hw>.nix` + `./computers/<host>.nix`. `nixy` also gets `./my-pkgs`, the home-manager NixOS module, and stylix. `inputs` is passed to every NixOS and home-manager module through `specialArgs`/`extraSpecialArgs`, so third-party modules are imported inline, e.g. `inputs.sops.nixosModules.sops`. + +### `modules/`: custom option modules under the `teh-nix.*` namespace +`modules/default.nix` **auto-imports every `.nix` file in the directory recursively**, except `default.nix`. Both hosts import all of them, so each module has to be gated behind `lib.mkIf config.teh-nix.<name>.enable`, and a host turns on only what it needs: +- `teh-nix.nix`: nix settings, flakes, the registry/NIX_PATH pointing at the flake's nixpkgs, and `nh` cleanup (in place of `nix.gc`). +- `teh-nix.xorg`: X server, and pulls in the YATwm NixOS module. It enables `teh-nix.nvidia` by default. +- `teh-nix.nvidia`: PRIME offload with bus IDs, plus the `prime-run` wrapper. +- `teh-nix.services.cgit`: self-written cgit + nginx + git-over-ssh service, used on nixnode. + +Add new reusable functionality here in the same `options`/`config = mkIf` pattern instead of putting it straight into a host file. + +### `computers/`: per-host config +These are the old `configuration.nix` equivalents. They set the `teh-nix.*` toggles, sops secrets, networking, and the services for the host. The wireguard tunnel spans both files: `nixnode` is the hub (`10.100.0.1`, kernel wireguard), and `nixy` is the peer (`10.100.0.2`, a NetworkManager profile that gets its key from sops through `nm-file-secret-agent`). + +### `home-manager/`: user `boss` on nixy +`home.nix` is the entry point and imports one directory per program (each has a `default.nix`; some ship raw dotfiles next to it, such as `i3/config`, `polybar/config.ini`, `waybar/config/`). Commented-out imports, like `hyprland`, are kept for switching back. Both `i3` and `YATwm` are imported, and `xsession.windowManager.command` is `mkForce`d to `"$@"` so the display manager decides which WM starts. Colors and fonts come from **stylix**, configured in `computers/nixy.nix`, so don't hardcode colors in program configs that stylix targets. + +`claude-code` is pinned by overriding the nixpkgs package with a vendored manifest (`home-manager/claude-code-manifest-<version>.json`). To bump it, add the new manifest and update the filename in `home.nix`. + +### `my-pkgs/` +`default.nix` is a NixOS module that adds an overlay (it currently provides `adom`). `stk-installers.nix` isn't part of the overlay: it's exposed directly as a flake package and served (currently commented out) from nixnode. + +### `website/` +A static site: it copies `src/` into `$out/srv/www`. It's built as the flake package `teh-website`, and the `tehbox.org` vhost references it through `inputs.self.packages`. + +### Secrets (sops-nix) +`secrets/general.yaml` is age-encrypted to both host keys listed in `.sops.yaml`. Each host decrypts with `/home/boss/.config/sops/age/keys.txt`. Secrets are declared per host in `sops.secrets` and consumed via `config.sops.secrets."<path>".path`. + +### Git remotes +`github` (GitHub mirror) and `tehbox`/`nixnode` (the self-hosted cgit on the server). |