Add agent skills
This commit is contained in:
296
.agents/skills/nixos-best-practices/rules/host-organization.md
Normal file
296
.agents/skills/nixos-best-practices/rules/host-organization.md
Normal file
@@ -0,0 +1,296 @@
|
||||
---
|
||||
title: Host Configuration Organization
|
||||
impact: HIGH
|
||||
impactDescription: Prevents configuration chaos across multiple hosts
|
||||
tags: hosts,modules,base-config,directory-structure
|
||||
---
|
||||
|
||||
|
||||
## Why This Matters
|
||||
|
||||
Proper host configuration organization prevents duplication, makes maintenance easier, and ensures consistency across multiple machines.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
nixos-config/
|
||||
├── flake.nix # Top-level flake
|
||||
├── hosts/
|
||||
│ ├── laptop/
|
||||
│ │ ├── default.nix # Host-specific config
|
||||
│ │ ├── hardware-configuration.nix # Generated (don't edit)
|
||||
│ │ └── home.nix # Home Manager config
|
||||
│ ├── desktop/
|
||||
│ │ ├── default.nix
|
||||
│ │ ├── hardware-configuration.nix
|
||||
│ │ └── home.nix
|
||||
│ └── base.nix # Shared by all hosts (optional)
|
||||
├── modules/ # Reusable NixOS modules
|
||||
├── overlays/ # Custom overlays
|
||||
├── home-manager/ # Shared Home Manager configs
|
||||
│ ├── shell/
|
||||
│ ├── applications/
|
||||
│ └── common.nix
|
||||
└── secrets/ # Age-encrypted secrets
|
||||
```
|
||||
|
||||
## Host Configuration Pattern
|
||||
|
||||
### Incorrect: Everything in one file
|
||||
|
||||
```nix
|
||||
# hosts/laptop/default.nix
|
||||
{ config, pkgs, ... }:
|
||||
{
|
||||
# Hardware config (copied from hardware-configuration.nix)
|
||||
boot.initrd.availableKernelModules = [ "xhci_pci" "nvme" "usb_storage" ];
|
||||
# ... 50 lines of hardware config ...
|
||||
|
||||
# Network config
|
||||
networking.hostName = "laptop";
|
||||
networking.networkmanager.enable = true;
|
||||
|
||||
# User config
|
||||
users.users.john = {
|
||||
isNormalUser = true;
|
||||
extraGroups = [ "wheel" "networkmanager" ];
|
||||
};
|
||||
|
||||
# Packages
|
||||
environment.systemPackages = with pkgs; [ vim git wget ];
|
||||
|
||||
# Services
|
||||
services.openssh.enable = true;
|
||||
|
||||
# Home Manager
|
||||
imports = [
|
||||
./home.nix # Or inline the entire home config
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
**Problems:**
|
||||
- Hardware config duplicated (should import hardware-configuration.nix)
|
||||
- User config duplicated across hosts
|
||||
- No shared configuration
|
||||
- Hard to maintain
|
||||
|
||||
### Correct: Modular structure
|
||||
|
||||
```nix
|
||||
# hosts/laptop/default.nix
|
||||
{ inputs, pkgs, pkgs-stable, system, ... }:
|
||||
{
|
||||
imports = [
|
||||
./hardware-configuration.nix # Import hardware config
|
||||
../base.nix # Import shared config
|
||||
inputs.home-manager.nixosModules.home-manager
|
||||
{
|
||||
home-manager.useGlobalPkgs = true;
|
||||
home-manager.useUserPackages = true;
|
||||
home-manager.users.john = import ./home.nix;
|
||||
home-manager.extraSpecialArgs = {
|
||||
inherit inputs pkgs-stable system;
|
||||
};
|
||||
nixpkgs.overlays = [ inputs.some-overlay.overlays.default ];
|
||||
}
|
||||
];
|
||||
|
||||
# Host-specific config only
|
||||
networking.hostName = "laptop";
|
||||
}
|
||||
```
|
||||
|
||||
## Shared Base Configuration
|
||||
|
||||
```nix
|
||||
# hosts/base.nix
|
||||
{ config, pkgs, inputs, ... }:
|
||||
{
|
||||
# Network
|
||||
networking.networkmanager.enable = true;
|
||||
|
||||
# Time and locale
|
||||
time.timeZone = "America/New_York";
|
||||
i18n.defaultLocale = "en_US.UTF-8";
|
||||
|
||||
# Users (shared across all hosts)
|
||||
users.users.john = {
|
||||
isNormalUser = true;
|
||||
extraGroups = [ "wheel" "networkmanager" ];
|
||||
};
|
||||
|
||||
# Common packages
|
||||
environment.systemPackages = with pkgs; [
|
||||
vim
|
||||
git
|
||||
wget
|
||||
tmux
|
||||
];
|
||||
|
||||
# Common services
|
||||
services.openssh.enable = true;
|
||||
|
||||
# Nix settings
|
||||
nix.settings.experimental-features = [ "nix-command" "flakes" ];
|
||||
}
|
||||
```
|
||||
|
||||
## Hardware Configuration
|
||||
|
||||
```nix
|
||||
# hosts/laptop/default.nix
|
||||
{ ... }:
|
||||
{
|
||||
imports = [
|
||||
./hardware-configuration.nix # Generated by nixos-generate-config
|
||||
../base.nix
|
||||
# ...
|
||||
];
|
||||
|
||||
networking.hostName = "laptop";
|
||||
}
|
||||
```
|
||||
|
||||
**Important:** Don't edit `hardware-configuration.nix` manually. It's generated by `nixos-generate-config` and should be replaced when hardware changes.
|
||||
|
||||
## Home Manager Configuration
|
||||
|
||||
### Host-specific home.nix
|
||||
|
||||
```nix
|
||||
# hosts/laptop/home.nix
|
||||
{ config, pkgs, inputs, ... }:
|
||||
{
|
||||
imports = [
|
||||
../../home-manager/shell
|
||||
../../home-manager/applications
|
||||
../../home-manager/common.nix
|
||||
];
|
||||
|
||||
# Host-specific user config
|
||||
home.packages = with pkgs; [
|
||||
laptop-specific-package
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
### Shared Home Manager configs
|
||||
|
||||
```nix
|
||||
# home-manager/shell/default.nix
|
||||
{ config, pkgs, ... }:
|
||||
{
|
||||
imports = [
|
||||
./fish
|
||||
./neovim
|
||||
./git
|
||||
];
|
||||
}
|
||||
|
||||
# home-manager/common.nix
|
||||
{ config, pkgs, ... }:
|
||||
{
|
||||
home.packages = with pkgs; [
|
||||
jq
|
||||
ripgrep
|
||||
fzf
|
||||
];
|
||||
|
||||
programs.git.enable = true;
|
||||
programs.git.userName = "John Doe";
|
||||
programs.git.userEmail = "john@example.com";
|
||||
}
|
||||
```
|
||||
|
||||
## Multiple Hosts Example
|
||||
|
||||
```nix
|
||||
# flake.nix
|
||||
outputs = { self, nixpkgs, home-manager, ... }@inputs: {
|
||||
nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
|
||||
specialArgs = { inherit inputs; };
|
||||
modules = [ ./hosts/laptop ];
|
||||
};
|
||||
|
||||
nixosConfigurations.desktop = nixpkgs.lib.nixosSystem {
|
||||
specialArgs = { inherit inputs; };
|
||||
modules = [ ./hosts/desktop ];
|
||||
};
|
||||
|
||||
nixosConfigurations.server = nixpkgs.lib.nixosSystem {
|
||||
specialArgs = { inherit inputs; };
|
||||
modules = [ ./hosts/server ];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Each host uses the same `base.nix` but can override settings:
|
||||
|
||||
```nix
|
||||
# hosts/server/default.nix
|
||||
{ ... }:
|
||||
{
|
||||
imports = [ ../base.nix ./hardware-configuration.nix ];
|
||||
|
||||
# Override time zone for server
|
||||
time.timeZone = "UTC";
|
||||
|
||||
# Add server-specific packages
|
||||
environment.systemPackages = with pkgs; [
|
||||
htop
|
||||
iotop
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
## Module Pattern
|
||||
|
||||
For reusable functionality, create modules:
|
||||
|
||||
```nix
|
||||
# modules/docker.nix
|
||||
{ config, pkgs, ... }:
|
||||
{
|
||||
virtualisation.docker = {
|
||||
enable = true;
|
||||
enableOnBoot = true;
|
||||
};
|
||||
|
||||
users.users.john.extraGroups = [ "docker" ];
|
||||
}
|
||||
```
|
||||
|
||||
Use in host config:
|
||||
|
||||
```nix
|
||||
# hosts/laptop/default.nix
|
||||
{ ... }:
|
||||
{
|
||||
imports = [
|
||||
../base.nix
|
||||
../../modules/docker # Import module
|
||||
./hardware-configuration.nix
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
1. **Editing hardware-configuration.nix**: Changes are lost when regenerating. Put host-specific config in `default.nix` instead.
|
||||
|
||||
2. **Duplicating config across hosts**: Use `base.nix` or modules for shared configuration.
|
||||
|
||||
3. **Not separating host-specific and user-specific**: Keep host config in `hosts/*/default.nix`, user config in `home.nix` or `home-manager/`.
|
||||
|
||||
4. **Mixing concerns**: Don't put shell config in system packages. Use Home Manager for user-level packages.
|
||||
|
||||
## Quick Checklist
|
||||
|
||||
- [ ] Each host imports hardware-configuration.nix
|
||||
- [ ] Shared config in base.nix or modules
|
||||
- [ ] Home Manager configured in host file
|
||||
- [ ] Host-specific settings only in host's default.nix
|
||||
- [ ] User config in home.nix or home-manager/
|
||||
- [ ] No duplication of hardware config
|
||||
- [ ] No duplication of user config
|
||||
Reference in New Issue
Block a user