91 lines
4.5 KiB
Markdown
91 lines
4.5 KiB
Markdown
# NixOS configuration
|
|
|
|
One shared daily environment on Polaris and Zenith, with shared services on Orion.
|
|
NixOS and Home Manager are composed through flake-parts and import-tree.
|
|
|
|
## Start here
|
|
|
|
- [Design](docs/design.md): vocabulary, ownership, and rationale.
|
|
- [Agent instructions](AGENTS.md): repository collaboration boundaries.
|
|
- [Current work](docs/current-work.md): accepted scope, open decisions, and next step.
|
|
|
|
## Configuration map
|
|
|
|
| Owner | Location | Responsibility |
|
|
| --- | --- | --- |
|
|
| Hosts | `modules/hosts/<host>/` | Identity, hardware, machine-specific selection |
|
|
| Profiles | `modules/profiles/` | Combinations of capabilities |
|
|
| Capabilities | `modules/capabilities/` | Behavior and integration across NixOS and Home Manager |
|
|
| Facts | `modules/facts.nix` | Shared identity and topology; host facts are declared with hosts |
|
|
| Composition | `flake.nix`, `modules/flake-parts.nix` | Inputs, discovery, host construction |
|
|
| Secrets | `modules/secrets/` | Existing SOPS declarations and encrypted data |
|
|
|
|
Discovery makes named modules available; imports select them. Underscore-prefixed
|
|
helpers and directories are excluded from automatic discovery and imported explicitly.
|
|
Add shared behavior to its capability and select it through the relevant profile.
|
|
Keep machine differences in hosts. A capability can own system and user modules.
|
|
|
|
The primary editor is selected in `host-base.nix`, the primary terminal in
|
|
`workstation-base.nix`. `modules/capabilities/theme.nix` selects the complete theme;
|
|
Kanagawa lives in `modules/capabilities/_themes/kanagawa.nix`. Appearance belongs
|
|
there; interaction and layout belong with the capability.
|
|
|
|
## Work environment (provisional)
|
|
|
|
Both workstations import `modules/profiles/work.nix`: company network/development
|
|
integration, Garden tools, and work Git settings. This is a trial boundary, not
|
|
an independent workstation variant. SharePoint remains Zenith-only for now.
|
|
|
|
The tools-only environment is owned by
|
|
`modules/capabilities/yookr-dev/environment.nix`. It shares Garden definitions in
|
|
`_packages.nix` with installed tools and uses the system's nixpkgs pin:
|
|
|
|
```console
|
|
nix develop --quiet ~/.config/nixos#workbench --command bash --norc
|
|
```
|
|
|
|
This does not clear inherited credentials; start from a clean environment for
|
|
agent work. It does not load secrets, mount storage, or install Python dependencies.
|
|
Workspace `.envrc` files select it; the workbench's human credential and mount
|
|
steps remain workspace-owned. Requests, queries, analysis, and `uv.lock` stay there.
|
|
After loader changes, the user must review and re-allow the changed `.envrc` files
|
|
with direnv. No loader is sourced as part of validation.
|
|
|
|
## Maintenance
|
|
|
|
Run from this repository:
|
|
|
|
```console
|
|
just validate # format, evaluate, build every host and the workbench
|
|
just validate polaris # same workflow, build only the named host(s)
|
|
```
|
|
|
|
The command includes current tracked files and non-ignored new files, respects
|
|
working-tree deletions, and never changes the Git index. It resolves the pinned
|
|
formatter from a temporary source snapshot, formats included Nix files in the
|
|
working tree, then refreshes the snapshot for evaluation and builds. Ignored
|
|
untracked files and `.git` are excluded. Avoid concurrent edits during validation:
|
|
results describe the snapshot, not subsequent changes.
|
|
|
|
Output is limited to stage results and a short excerpt on failure. Full logs remain
|
|
in the printed `/tmp/nixos-validate-*` directory; source snapshots are removed on
|
|
exit. Failed stages stop the command. Inputs are not updated, no result links are
|
|
created, and nothing is activated. Host names are discovered from the flake.
|
|
|
|
`just` and Python are already declared for both workstations. The implementation
|
|
is `scripts/validate.py`; the justfile is only its entry point. The formatter output
|
|
currently targets this repository's sole system, `x86_64-linux`.
|
|
|
|
Use full validation after a configuration batch and targeted hosts during iteration.
|
|
Documentation-only edits need review, local link checks, and `git diff --check`,
|
|
not system builds. Evaluation, build, activation, and confirmed behavior are
|
|
separate evidence. Outside this wrapper, ordinary Git-backed flake commands still
|
|
require intended new files to be added to Git.
|
|
|
|
The user activates with `nh os switch`. Edit encrypted data with
|
|
`sops edit modules/secrets/secrets.yaml`; keep plaintext out of Nix expressions
|
|
and the store. No new credential-delivery design is selected yet.
|
|
|
|
Historical material under `docs/.archive/` is evidence, not current instructions
|
|
or a backlog. Consult it only for relevant unresolved questions.
|