nix-los/README.md

# Portable NixOS Configuration

A production-ready, modular NixOS + Home Manager setup with automatic disk
partitioning, secrets management, and support for both new and existing
systems.

## Features

- ✅ **Modular**: Configure system and home separately or together
- ✅ **Portable**: Works on new machines, existing NixOS, or non-NixOS (home-manager only)
- ✅ **Auto-partitioning**: Disko handles disk setup automatically
- ✅ **Secrets**: sops-nix for encrypted, portable secrets
- ✅ **Unstable packages**: Mix stable and unstable nixpkgs
- ✅ **Single command**: Deploy entire system with one command

## Directory Structure

```
nix-config/
├── flake.nix                     # Main entry point (inputs + outputs)
├── flake.lock                    # Pinned versions
├── hosts/                        # Per-machine configs
│   ├── laptop/default.nix        # Machine-specific settings
│   └── server/default.nix
├── nixos/                        # Shared NixOS modules
│   ├── default.nix
│   └── modules/
│       ├── system.nix            # User creation, sudo
│       ├── development.nix       # Languages, tools
│       └── shell.nix             # Shell config
├── home/                         # Shared Home Manager modules
│   ├── default.nix
│   └── modules/
│       ├── shell.nix             # Zsh + direnv
│       ├── editor.nix            # Neovim/VSCode
│       ├── git.nix               # Git config
│       └── dev-tools.nix         # tmux, etc
├── secrets/
│   ├── .sops.yaml                # Encryption config
│   └── secrets.yaml              # Encrypted secrets
└── README.md
```

## Quick Start

### 1. Initial Setup

```bash
# Clone repository
git clone <repo-url> nix-los
cd nix-los

# Generate age keypair (one-time)
age-keygen -o -f ~/.config/sops/age/keys.txt

# Update .sops.yaml with your public key
age-keygen -y ~/.config/sops/age/keys.txt
# Copy the output and update secrets/.sops.yaml
```

### 2. Personalize Your Config

Edit these files to match your setup:

**flake.nix:**
- Change `youruser` to your actual username (3 places)

**hosts/laptop/default.nix:**
- Set `networking.hostName`
- Verify disk device (change `/dev/sda` if needed)

**home/default.nix & home/modules/git.nix:**
- Set your username and email
- Customize home packages

**secrets/secrets.yaml:**
- Add your SSH keys, API tokens, passwords

### 3. Deploy to Existing NixOS

```bash
# Rebuild the entire system
sudo nixos-rebuild switch --flake .#laptop

# Or, just update home-manager
home-manager switch --flake .#youruser@linux
```

### 4. Deploy to New Machine (ISO Install)

```bash
# Boot NixOS live ISO, then:
# (Option A) Manual installation
sudo nix run github:nix-community/disko -- --mode zap --flake .#laptop

# (Option B) Automated with nixos-anywhere (from another machine)
nix run github:nix-community/nixos-anywhere -- --flake .#laptop root@192.168.1.100

# (Option C) One-liner installer
nix run .#installer -- laptop
```

### 5. Non-NixOS Machine (Home Manager Only)

```bash
# Install home-manager and apply config
home-manager switch --flake .#youruser@linux

# Or use the installer script
nix run .#installer -- laptop
```

## Usage Patterns

### Rebuild After Changes

```bash
# System + home
sudo nixos-rebuild switch --flake .#laptop

# Just home-manager
home-manager switch --flake .#youruser@linux

# Dry-run to see what changes
sudo nixos-rebuild test --flake .#laptop
```

### Manage Secrets

```bash
# Edit encrypted secrets (requires age key)
sops secrets/secrets.yaml

# Reference in NixOS config:
# sops.secrets."ssh/github_key".owner = "youruser";
# sops.secrets."ssh/github_key".path = "/home/youruser/.ssh/github_key";

# Access in shell:
# cat ${config.sops.secrets."ssh/github_key".path}
```

### Enable/Disable Features

Edit host config (e.g., `hosts/laptop/default.nix`):

```nix
# Enable development tools for specific languages
custom.development.enable = true;
custom.development.languages = [ "rust" "python" "nodejs" ];

# Disable specific modules
custom.shell.enable = false;
```

### Add New Modules

Create `nixos/modules/myfeature.nix`:

```nix
{ config, lib, pkgs, ... }:

{
  options.custom.myfeature = {
    enable = lib.mkEnableOption "My feature";
  };

  config = lib.mkIf config.custom.myfeature.enable {
    # Your config here
  };
}
```

Then import in `nixos/default.nix`:
```nix
imports = [ ./modules/myfeature.nix ];
```

### Development Shell

```bash
# Load dev environment
nix flake show

# Enter dev shell with all tools
nix develop
```

## Multi-Machine Setup

To support multiple machines:

1. Create new host:
```bash
mkdir -p hosts/newhost
cp hosts/laptop/default.nix hosts/newhost/default.nix
```

2. Edit `flake.nix` and add:
```nix
newhost = nixpkgs.lib.nixosSystem {
  inherit system;
  specialArgs = { inherit sops-nix disko; pkgs-unstable = pkgs-unstable; };
  modules = [
    overlayUnstable
    sops-nix.nixosModules.sops
    disko.nixosModules.disko
    ./hosts/newhost/default.nix
    ./nixos/default.nix
    home-manager.nixosModules.home-manager
    { home-manager.users.youruser = import ./home/default.nix; }
  ];
};
```

3. Deploy:
```bash
sudo nixos-rebuild switch --flake .#newhost
```

## Troubleshooting

### Secrets decryption fails
```bash
# Check your age key exists
ls ~/.config/sops/age/keys.txt

# Verify sops config
sops -d secrets/secrets.yaml

# Regenerate .sops.yaml with your key
age-keygen -y ~/.config/sops/age/keys.txt
```

### Disko disk errors
```bash
# List available disks
lsblk

# Manually run disko (test mode)
sudo nix run github:nix-community/disko -- --mode doit --flake .#laptop
```

### Home-manager import errors
```bash
# Check flake validity
nix flake check

# Validate syntax
nix flake show
```

## Resources

- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
- [Home Manager](https://nix-community.github.io/home-manager/)
- [sops-nix Documentation](https://github.com/mic92/sops-nix)
- [disko](https://github.com/nix-community/disko)
- [Flakes Guide](https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-flake.html)

## Tips for Portability

1. **Keep secrets encrypted**: Always use sops, never commit plain text secrets
2. **Machine-specific overrides**: Use `lib.mkDefault` in shared modules
3. **Conditionally enable features**: Use `options` + `config = mkIf cfg.enable`
4. **Test before deploying**: Use `nixos-rebuild test` or `home-manager build`
5. **Version your flake**: Commit `flake.lock` for reproducibility
6. **Separate concerns**: System settings → nixos/, User env → home/