135 lines
5.2 KiB
Markdown
135 lines
5.2 KiB
Markdown
---
|
|
name: nixos-best-practices
|
|
description: Use when configuring NixOS with flakes, managing overlays with home-manager useGlobalPkgs, structuring NixOS configurations, or facing issues where configuration changes don't apply
|
|
license: MIT
|
|
metadata:
|
|
author: chumeng
|
|
version: "1.0.0"
|
|
---
|
|
|
|
# Configuring NixOS Systems with Flakes
|
|
|
|
Configure NixOS systems with flakes, manage overlays properly, and structure configurations for maintainability.
|
|
|
|
## Core Principle
|
|
|
|
**Understand the interaction between NixOS system configuration and Home Manager overlays.**
|
|
|
|
When `useGlobalPkgs = true`, overlays must be defined at the NixOS configuration level, not in Home Manager configuration files.
|
|
|
|
## When to Use
|
|
|
|
- Configuring NixOS with flakes and Home Manager
|
|
- Adding overlays that don't seem to apply
|
|
- Using `useGlobalPkgs = true` with custom overlays
|
|
- Structuring NixOS configurations across multiple hosts
|
|
- Package changes not appearing after rebuild
|
|
- Confused about where to define overlays
|
|
|
|
**Don't use for:**
|
|
- Packaging new software (use nix-packaging-best-practices)
|
|
- Simple package installation without overlays
|
|
- NixOS module development (see NixOS module documentation)
|
|
|
|
## Quick Reference
|
|
|
|
| Topic | Rule File |
|
|
|-------|-----------|
|
|
| Overlay scope and useGlobalPkgs | [overlay-scope](rules/overlay-scope.md) |
|
|
| Flakes configuration structure | [flakes-structure](rules/flakes-structure.md) |
|
|
| Host configuration organization | [host-organization](rules/host-organization.md) |
|
|
| Package installation best practices | [package-installation](rules/package-installation.md) |
|
|
| Common configuration mistakes | [common-mistakes](rules/common-mistakes.md) |
|
|
| Debugging configuration issues | [troubleshooting](rules/troubleshooting.md) |
|
|
|
|
## Essential Pattern: Overlay with useGlobalPkgs
|
|
|
|
```nix
|
|
# ❌ WRONG: Overlay in home.nix (doesn't apply)
|
|
# home-manager/home.nix
|
|
{
|
|
nixpkgs.overlays = [ inputs.claude-code.overlays.default ]; # Ignored!
|
|
home.packages = with pkgs; [ claude-code ]; # Not found!
|
|
}
|
|
|
|
# ✅ CORRECT: Overlay in NixOS home-manager block
|
|
# hosts/home/default.nix
|
|
{
|
|
home-manager.useGlobalPkgs = true;
|
|
home-manager.useUserPackages = true;
|
|
home-manager.users.chumeng = import ./home.nix;
|
|
home-manager.extraSpecialArgs = { inherit inputs pkgs-stable system; };
|
|
# Overlay must be HERE when useGlobalPkgs = true
|
|
nixpkgs.overlays = [ inputs.claude-code.overlays.default ];
|
|
}
|
|
```
|
|
|
|
## Common Tasks
|
|
|
|
| Task | Solution |
|
|
|------|----------|
|
|
| Add flake input | Add to `inputs` in flake.nix |
|
|
| Add overlay for system packages | Define in `nixpkgs.overlays` in system configuration |
|
|
| Add overlay for home-manager (useGlobalPkgs=true) | Define in `home-manager.nixpkgs.overlays` in host config |
|
|
| Add overlay for home-manager (useGlobalPkgs=false) | Define in `home.nix` with `nixpkgs.overlays` |
|
|
| Pass inputs to modules | Use `specialArgs` in nixosSystem or home-manager |
|
|
| Multiple host configurations | Create separate host files in `hosts/` |
|
|
| Shared configuration modules | Create modules in `modules/` and import in each host |
|
|
| Package not found after overlay | Check overlay scope vs useGlobalPkgs setting |
|
|
|
|
## Overlay Scope Decision Matrix
|
|
|
|
| useGlobalPkgs | Overlay Definition Location | Affects |
|
|
|---------------|---------------------------|---------|
|
|
| `true` | `home-manager.nixpkgs.overlays` | System + Home Manager packages |
|
|
| `true` | `home.nix` with `nixpkgs.overlays` | **Nothing** (ignored!) |
|
|
| `false` | `home.nix` with `nixpkgs.overlays` | Home Manager packages only |
|
|
| `false` | `home-manager.nixpkgs.overlays` | Home Manager packages only |
|
|
| Any | System `nixpkgs.overlays` | System packages only |
|
|
|
|
## Configuration Layers (Bottom to Top)
|
|
|
|
1. **System configuration** (`/etc/nixos/configuration.nix` or host files)
|
|
- System-wide services
|
|
- System packages
|
|
- System overlays only affect this layer
|
|
|
|
2. **Home Manager (useGlobalPkgs=true)**
|
|
- Uses system pkgs (includes system overlays)
|
|
- Home Manager overlays affect both system and user packages
|
|
- Most efficient for single-user systems
|
|
|
|
3. **Home Manager (useGlobalPkgs=false)**
|
|
- Creates separate pkgs instance
|
|
- Home Manager overlays affect user packages only
|
|
- Useful for multi-user systems with different needs
|
|
|
|
## Red Flags - STOP
|
|
|
|
- "Overlay in home.nix isn't working" → Check if useGlobalPkgs=true, move to host config
|
|
- "I'll just add overlays everywhere" → Define once at appropriate scope
|
|
- "Package works in nix repl but not installed" → Check overlay scope
|
|
- "Changes don't apply after rebuild" → Verify overlay is in correct location
|
|
- "useGlobalPkgs=false for no reason" → Use true unless you need separate package sets
|
|
|
|
## How to Use
|
|
|
|
Read individual rule files for detailed explanations and code examples:
|
|
|
|
```
|
|
rules/overlay-scope.md # The core overlay scope issue
|
|
rules/flakes-structure.md # How to organize flake.nix
|
|
rules/host-organization.md # How to structure host configs
|
|
rules/common-mistakes.md # Pitfalls and how to avoid them
|
|
```
|
|
|
|
Each rule file contains:
|
|
- Brief explanation of why it matters
|
|
- Incorrect code example with explanation
|
|
- Correct code example with explanation
|
|
- Additional context and references
|
|
|
|
## Full Compiled Document
|
|
|
|
For the complete guide with all rules expanded: `AGENTS.md`
|