panotaka/nix-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
87a2314170e6500c6d1784f343177106e690c6cf
nix-config/.github/copilot-instructions.md

5.0 KiB
Raw Blame History

Copilot Instructions for EmergentMind's Nix-Config

Project Overview

  • This is a modular, flake-based NixOS configuration system, designed for multi-host, multi-user, and reproducible setups.
  • Major directories and their roles:
    • hosts/: Per-host NixOS configs (e.g., hosts/nixos/Bellerophon/). Each host has its own directory with a default.nix entrypoint, plus hardware, disk, and optional feature overrides.
    • home/: Per-user Home Manager configs. User-specific and shared configs, with common/ for reusable modules and optional/ for opt-in features.
    • modules/: Reusable NixOS and Home Manager modules, auto-imported via lib.custom.scanPaths. This is where most custom logic, options, and abstractions live—including CLI tool modules, system services, and shared config patterns.
    • overlays/, pkgs/: Custom packages and overlays. CLI tools that are not in upstream Nixpkgs are typically defined here (see pkgs/common/ for examples like cd-gitroot).
    • nixos-installer/: Standalone flake for bootstrapping new hosts, with its own README and workflows.
    • docs/: Project documentation, including secrets management and architecture guides.
    • scripts/: Helper scripts for bootstrap, rebuild, sops, etc. Used in developer workflows and automation.
    • tests/: Automated tests (Bats), with fixtures and helpers for validating secrets, modules, and workflows.
  • Desktop Environments & Optional Features:
    • Desktop environments (GNOME, KDE, XFCE, etc.) and other optional system features are modularized under hosts/common/core/optional/ and its subfolders (e.g., gnome.nix, kde.nix, xfce.nix).
    • These are imported by hosts as needed, allowing flexible, DRY configuration.
  • CLI Tools:
    • System-wide CLI tools are typically declared in modules/ (as NixOS or Home Manager modules), or in pkgs/ if packaged locally.
    • User-level CLI tools are managed via Home Manager modules in home/<user>/common/core/shell/ (e.g., fish.nix, bat.nix, eza.nix).
    • Many tools are grouped by function (shell, coding, productivity, etc.) for clarity and reusability.
  • Disk Layout: Disk setup is handled by disko modules, with per-host overrides for device and swap in hosts/common/core/disks/.
  • Secrets: Secrets are managed via a private nix-secrets repo and sops-nix. See docs/secretsmgmt.md and nixos-installer/README.md for details.
  • VSCode/Language Support: Language-specific VSCode configs live in home/panotaka/common/optional/coding/vscode/languages/ and are imported via the main VSCode module.

Key Patterns & Conventions

  • Imports: Use lib.custom.relativeToRoot and lib.custom.scanPaths for DRY, recursive module imports.
  • Host/Module Structure: Each host and user has a directory with a default.nix as entrypoint. Common/optional configs are split for clarity.
  • Disk Layout: Disk setup is handled by disko modules, with per-host overrides for device and swap.
  • Secrets: Secrets are managed via a private nix-secrets repo and sops-nix. See docs/secretsmgmt.md and nixos-installer/README.md for details.
  • VSCode/Language Support: Language-specific VSCode configs live in home/panotaka/common/optional/coding/vscode/languages/ and are imported via the main VSCode module.

Developer Workflows

  • Build & Rebuild: Use just rebuild (runs pre/post hooks, see justfile). For full checks: just rebuild-full or just check.
  • ISO Generation: just iso builds a custom NixOS installer ISO.
  • Secrets: Use just rekey, just sops-add-creation-rules, and related commands for sops/age key management.
  • Sync/Deploy: Use just sync and just build-host for remote deployment.
  • Testing: Tests live in tests/ and use bats.

Integration Points

  • External: Relies on nix-secrets (private), sops-nix, disko, stylix, nix4vscode, and nixos-hardware modules.
  • Cross-Component: Host configs import common modules and optional features via mapped imports. Home Manager and NixOS modules are kept separate but coordinated.

Examples

  • To add a new host: copy an existing host dir in hosts/nixos/, update disk and user settings, and add secrets as per nixos-installer/README.md.
  • To add a new language to VSCode: add a .nix file to vscode/languages/ and import it in the main VSCode module.
  • To add a new CLI tool: create a module in modules/ or a package in pkgs/, then import it in the relevant host or user config.
  • To enable a desktop environment: import the relevant module from hosts/common/core/optional/ in your host's default.nix.
  • To update secrets: run just rekey and follow the documented workflow.

References

  • See README.md, nixos-installer/README.md, and docs/secretsmgmt.md for deep dives on architecture and workflows.
  • For module patterns, see modules/ and hosts/common/core/.
  • For CLI tool packaging, see pkgs/ and modules/.
  • For desktop environment modules, see hosts/common/core/optional/.

If you are unsure about a workflow or pattern, check the referenced docs or ask for clarification in your PR.