nix-los/SETUP.md

# Setup Guide - Step by Step

This guide walks you through setting up your portable NixOS configuration from scratch.

## Prerequisites

- **For new NixOS machines**: NixOS ISO boot media
- **For existing NixOS**: SSH access or local terminal
- **For non-NixOS**: curl, bash

## Phase 1: Initialize Secrets (One-time)

### Generate Your Age Key

```bash
# Create age directory
mkdir -p ~/.config/sops/age

# Generate keypair
age-keygen -o -f ~/.config/sops/age/keys.txt

# Extract public key
age-keygen -y ~/.config/sops/age/keys.txt
# Output: age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### Update Encryption Config

Edit `secrets/.sops.yaml`:

```yaml
keys:
  - &users |
    - -----BEGIN AGE PUBLIC KEY-----
      age1YOUR_KEY_HERE_FROM_ABOVE
      -----END AGE PUBLIC KEY-----
```

### Encrypt Your Secrets

```bash
# First install sops and age
nix shell nixpkgs#sops nixpkgs#age

# Edit secrets
sops secrets/secrets.yaml

# Add your SSH keys, API keys, etc.
# File will be encrypted automatically on save
```

## Phase 2: Personalize Configuration

### Step 1: Update flake.nix

Replace `youruser` with your actual username:

```bash
sed -i 's/youruser/myusername/g' flake.nix
sed -i 's/youruser/myusername/g' home/default.nix
```

### Step 2: Configure Your Laptop Host

Edit `hosts/laptop/default.nix`:

```nix
{
  networking.hostName = "mylaptop";  # Change this

  disko.devices = {
    disk.main = {
      type = "disk";
      device = "/dev/sda";  # Run 'lsblk' to find your disk

      # For NVMe: device = "/dev/nvme0n1";
      # For SATA: device = "/dev/sda";
      # For RAID: add multiple disks
    };
    # ... rest stays the same
  };

  # Enable tools you want
  custom.development.enable = true;
  custom.development.languages = [ "rust" "python" "nodejs" ];
}
```

### Step 3: Customize Home Configuration

Edit `home/default.nix`:

```nix
home.username = "myusername";  # Match your username
home.homeDirectory = "/home/myusername";
```

Edit `home/modules/git.nix`:

```nix
programs.git = {
  enable = true;
  userName = "Your Real Name";
  userEmail = "you@example.com";
  # ... rest of config
};
```

## Phase 3: Deploy Strategy Based on Your Situation

### Scenario A: Deploying to Existing NixOS

```bash
# 1. Clone repo to your home directory
git clone <your-repo> ~/nix-config
cd ~/nix-config

# 2. Test the configuration (dry-run)
sudo nixos-rebuild test --flake .#laptop

# 3. If tests pass, apply the configuration
sudo nixos-rebuild switch --flake .#laptop

# 4. Also apply home-manager
home-manager switch --flake .#myusername@linux
```

### Scenario B: Fresh NixOS Installation (with Auto-Partitioning)

**On a machine running the NixOS ISO:**

```bash
# 1. Boot NixOS live ISO
# 2. Connect to network (if needed)
# 3. Clone the repo (copy files via USB or git clone)

nix flake update  # Update to latest packages

# Option 1: Use disko directly
sudo nix run github:nix-community/disko -- \
  --mode zap \
  --flake .#laptop

# Option 2: Use nixos-anywhere from another machine
nix run github:nix-community/nixos-anywhere -- \
  --flake .#laptop \
  --build-on-remote \
  root@<your-target-ip>

# Option 3: Manual installation
# 1. Partition disk manually: `sudo fdisk /dev/sda`
# 2. Mount partitions: `sudo mount /dev/sda2 /mnt && sudo mount /dev/sda1 /mnt/boot`
# 3. Generate initial config: `sudo nixos-generate-config --root /mnt`
# 4. Copy your flake.nix to /mnt/etc/nixos/flake.nix
# 5. Install: `sudo nixos-install --flake .#laptop`
```

### Scenario C: Non-NixOS Machine (Linux/macOS)

```bash
# 1. Install nix (if not present)
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | \
  sh -s -- install

# 2. Clone and apply home-manager
git clone <your-repo> ~/nix-config
cd ~/nix-config

# 3. Install home-manager
nix run home-manager/release-24.11 -- init --switch

# 4. Apply your config
home-manager switch --flake .#myusername@linux
```

## Phase 4: Verify Everything Works

```bash
# Check flake validity
nix flake check

# Inspect what will be built
nix flake show

# Check secrets decryption (if using sops)
sops -d secrets/secrets.yaml

# Verify home-manager config
home-manager packages 2>&1 | head -20

# Verify NixOS config (on NixOS machines)
sudo nixos-option system.nixos.version
```

## Phase 5: Enable Advanced Features (Optional)

### Using Unstable Packages

In any module, use unstable versions:

```nix
# In home/modules/dev-tools.nix
home.packages = with pkgs; [
  stable_package
  pkgs-unstable.latest_package
];
```

### Adding Secrets to NixOS Config

Create `nixos/modules/secrets.nix`:

```nix
{ config, sops-nix, ... }:

{
  imports = [ sops-nix.nixosModules.sops ];

  sops.defaultSopsFile = ./secrets/secrets.yaml;
  sops.age.keyFile = "/home/youruser/.config/sops/age/keys.txt";

  sops.secrets."ssh/github_key" = {
    owner = "youruser";
    group = "users";
    mode = "0600";
  };

  # Use in config:
  # environment.variables.GITHUB_SSH_KEY = "${config.sops.secrets."ssh/github_key".path}";
}
```

### Custom Per-Language Development Shells

Create `.envrc`:

```bash
use flake

# Per-project overrides
layout python
```

Then:

```bash
direnv allow
```

## Common Customizations

### Add a New Programming Language

Edit `hosts/laptop/default.nix`:

```nix
custom.development.languages = [ "rust" "python" "nodejs" "go" ];
```

Supported: `rust`, `python`, `nodejs`, `go`, `ruby` (in `nixos/modules/development.nix`)

### Change Default Shell

Edit `nixos/modules/shell.nix`:

```nix
custom.shell.defaultShell = "fish";  # or "bash"
```

### Add System Packages

Edit `nixos/default.nix`:

```nix
environment.systemPackages = with pkgs; [
  # ... existing packages
  mynewtool
];
```

### Add User Home Packages

Edit `home/default.nix`:

```nix
home.packages = with pkgs; [
  # ... existing packages
  mynewtool
];
```

## Rebuilding After Changes

```bash
# After modifying any config:

# 1. Check for syntax errors
nix flake check

# 2. Test without committing
sudo nixos-rebuild test --flake .#laptop

# 3. If happy, switch to new config
sudo nixos-rebuild switch --flake .#laptop

# 4. Update lockfile with latest packages
nix flake update

# 5. Commit changes
git add -A
git commit -m "Update: <description of changes>"
```

## Troubleshooting

### "Bad substituter" errors

```bash
# Clear cache
nix store gc

# Update flake
nix flake update

# Rebuild
sudo nixos-rebuild switch --flake .#laptop
```

### Secrets not decrypting

```bash
# Verify key exists
ls ~/.config/sops/age/keys.txt

# Check sops can find the key
sops -d secrets/secrets.yaml

# Verify .sops.yaml has correct key
cat secrets/.sops.yaml
```

### Home-manager conflicts with existing config

```bash
# Move old config
mv ~/.bashrc ~/.bashrc.bak
mv ~/.zshrc ~/.zshrc.bak

# Apply home-manager
home-manager switch --flake .#myusername@linux

# Merge manually if needed
cat ~/.bashrc.bak >> ~/.bashrc
```

## Next Steps

1. **Commit to git**: Version your config
2. **Add to GitHub**: Make it portable between machines
3. **Customize modules**: Create your own in `nixos/modules/`
4. **Backup secrets**: Safely store your age key
5. **Document changes**: Update README as you customize

See README.md for advanced usage patterns.