626 lines
12 KiB
Markdown
626 lines
12 KiB
Markdown
# Usage Guide
|
|
|
|
This guide provides detailed instructions for using and maintaining your Nix Home Manager configuration.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Initial Setup on a New Machine](#initial-setup-on-a-new-machine)
|
|
2. [Switching Between Profiles](#switching-between-profiles)
|
|
3. [Adding New Packages](#adding-new-packages)
|
|
4. [Adding New Configuration Modules](#adding-new-configuration-modules)
|
|
5. [Updating Flake Inputs](#updating-flake-inputs)
|
|
6. [Day-to-Day Operations](#day-to-day-operations)
|
|
7. [Troubleshooting](#troubleshooting)
|
|
|
|
---
|
|
|
|
## Initial Setup on a New Machine
|
|
|
|
### Step 1: Install Nix
|
|
|
|
```bash
|
|
# Install Nix with the official installer
|
|
curl -L https://nixos.org/nix/install | sh
|
|
|
|
# Follow the prompts and restart your terminal
|
|
# Or source the nix profile manually:
|
|
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
|
|
```
|
|
|
|
### Step 2: Enable Flakes
|
|
|
|
Flakes are an experimental feature that needs to be enabled:
|
|
|
|
```bash
|
|
mkdir -p ~/.config/nix
|
|
cat >> ~/.config/nix/nix.conf << EOF
|
|
experimental-features = nix-command flakes
|
|
EOF
|
|
```
|
|
|
|
### Step 3: Install Homebrew (macOS only)
|
|
|
|
Homebrew is required for GUI applications:
|
|
|
|
```bash
|
|
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
|
|
|
# Add Homebrew to PATH (for Apple Silicon Macs)
|
|
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
|
|
eval "$(/opt/homebrew/bin/brew shellenv)"
|
|
```
|
|
|
|
### Step 4: Install 1Password and Configure SSH Agent
|
|
|
|
1. Download and install [1Password](https://1password.com/downloads/mac/)
|
|
2. Sign in to your 1Password account
|
|
3. Enable SSH Agent:
|
|
- Open 1Password → Settings → Developer
|
|
- Enable "SSH Agent"
|
|
- Enable "Use the SSH agent"
|
|
4. Enable CLI integration:
|
|
- In the same Developer settings
|
|
- Enable "Integrate with 1Password CLI"
|
|
|
|
### Step 5: Clone the Repository
|
|
|
|
```bash
|
|
# Clone to ~/.dotfiles (recommended location)
|
|
git clone <repository-url> ~/.dotfiles
|
|
cd ~/.dotfiles
|
|
```
|
|
|
|
### Step 6: Build and Apply Configuration
|
|
|
|
For a **personal machine**:
|
|
|
|
```bash
|
|
# First-time build (creates darwin-rebuild command)
|
|
nix build .#darwinConfigurations.personal.system
|
|
|
|
# Apply the configuration
|
|
./result/sw/bin/darwin-rebuild switch --flake .#personal
|
|
```
|
|
|
|
For a **work machine**:
|
|
|
|
```bash
|
|
# First-time build
|
|
nix build .#darwinConfigurations.work.system
|
|
|
|
# Apply the configuration
|
|
./result/sw/bin/darwin-rebuild switch --flake .#work
|
|
```
|
|
|
|
### Step 7: Restart Your Shell
|
|
|
|
```bash
|
|
# Start a new shell to pick up all changes
|
|
exec zsh
|
|
```
|
|
|
|
### Step 8: Verify Installation
|
|
|
|
```bash
|
|
# Check that key tools are available
|
|
which starship # Should show nix store path
|
|
which atuin # Should show nix store path
|
|
which nvim # Should show nix store path
|
|
|
|
# Verify git configuration
|
|
git config --get user.email
|
|
git config --get user.signingkey
|
|
```
|
|
|
|
---
|
|
|
|
## Switching Between Profiles
|
|
|
|
### Switching from Personal to Work
|
|
|
|
If you need to reconfigure a machine from personal to work:
|
|
|
|
```bash
|
|
cd ~/.dotfiles
|
|
darwin-rebuild switch --flake .#work
|
|
```
|
|
|
|
**Note:** This will:
|
|
- Change git configuration (email, signing key)
|
|
- Update SSH hosts
|
|
- Remove personal-only Homebrew casks
|
|
- Disable personal-only features (like jellyfin-tui)
|
|
|
|
### Switching from Work to Personal
|
|
|
|
```bash
|
|
cd ~/.dotfiles
|
|
darwin-rebuild switch --flake .#personal
|
|
```
|
|
|
|
**Note:** This will:
|
|
- Change git configuration to personal settings
|
|
- Update SSH hosts
|
|
- Install personal Homebrew casks (darktable, signal, proton-*, steam)
|
|
- Enable personal features
|
|
|
|
### Temporary Profile Testing
|
|
|
|
To test a profile without fully switching:
|
|
|
|
```bash
|
|
# Build without applying
|
|
darwin-rebuild build --flake .#work
|
|
|
|
# Inspect what would change
|
|
ls -la result/
|
|
```
|
|
|
|
---
|
|
|
|
## Adding New Packages
|
|
|
|
### Adding CLI Tools via Nix (Recommended)
|
|
|
|
Edit [`modules/home/packages.nix`](../modules/home/packages.nix):
|
|
|
|
```nix
|
|
home.packages = with pkgs; [
|
|
# ... existing packages ...
|
|
|
|
# Add your new package
|
|
your-new-package
|
|
];
|
|
```
|
|
|
|
Then rebuild:
|
|
|
|
```bash
|
|
darwin-rebuild switch --flake .#personal # or .#work
|
|
```
|
|
|
|
#### Finding Package Names
|
|
|
|
```bash
|
|
# Search for packages
|
|
nix search nixpkgs your-package-name
|
|
|
|
# Or use the online search
|
|
# https://search.nixos.org/packages
|
|
```
|
|
|
|
### Adding GUI Applications via Homebrew
|
|
|
|
Edit [`modules/darwin/homebrew.nix`](../modules/darwin/homebrew.nix):
|
|
|
|
#### For All Machines (Shared)
|
|
|
|
```nix
|
|
casks = {
|
|
shared = [
|
|
# ... existing casks ...
|
|
"your-new-app"
|
|
];
|
|
};
|
|
```
|
|
|
|
#### For Personal Machine Only
|
|
|
|
```nix
|
|
casks = {
|
|
personal = [
|
|
# ... existing personal casks ...
|
|
"personal-only-app"
|
|
];
|
|
};
|
|
```
|
|
|
|
Then rebuild:
|
|
|
|
```bash
|
|
darwin-rebuild switch --flake .#personal
|
|
```
|
|
|
|
### Adding Homebrew Formulae (Non-Nix CLI tools)
|
|
|
|
For CLI tools that must come from Homebrew (e.g., from custom taps):
|
|
|
|
```nix
|
|
# In modules/darwin/homebrew.nix
|
|
brews = [
|
|
# ... existing brews ...
|
|
"tap-name/formula-name"
|
|
];
|
|
```
|
|
|
|
### Adding Homebrew Taps
|
|
|
|
```nix
|
|
# In modules/darwin/homebrew.nix
|
|
taps = [
|
|
# ... existing taps ...
|
|
"owner/repo"
|
|
];
|
|
```
|
|
|
|
---
|
|
|
|
## Adding New Configuration Modules
|
|
|
|
### Creating a New Home Manager Module
|
|
|
|
1. Create a new file in `modules/home/`:
|
|
|
|
```bash
|
|
touch modules/home/your-module.nix
|
|
```
|
|
|
|
2. Add the module structure:
|
|
|
|
```nix
|
|
# modules/home/your-module.nix
|
|
{ config, pkgs, lib, ... }:
|
|
|
|
with lib;
|
|
|
|
let
|
|
cfg = config.modules.yourModule;
|
|
in {
|
|
options.modules.yourModule = {
|
|
enable = mkEnableOption "Your module description";
|
|
|
|
# Add your options here
|
|
someSetting = mkOption {
|
|
type = types.str;
|
|
default = "default-value";
|
|
description = "Description of this setting";
|
|
};
|
|
};
|
|
|
|
config = mkIf cfg.enable {
|
|
# Your configuration here
|
|
programs.someProgram = {
|
|
enable = true;
|
|
# ...
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
3. Import the module in [`home/default.nix`](../home/default.nix):
|
|
|
|
```nix
|
|
imports = [
|
|
# ... existing imports ...
|
|
../modules/home/your-module.nix
|
|
];
|
|
```
|
|
|
|
4. Enable the module:
|
|
|
|
```nix
|
|
# In home/default.nix or profile-specific file
|
|
modules.yourModule = {
|
|
enable = true;
|
|
someSetting = "custom-value";
|
|
};
|
|
```
|
|
|
|
### Creating Profile-Specific Configuration
|
|
|
|
For settings that differ between personal and work:
|
|
|
|
1. Add options to your module with sensible defaults
|
|
2. Override in profile files:
|
|
|
|
```nix
|
|
# home/personal.nix
|
|
modules.yourModule = {
|
|
enable = true;
|
|
someSetting = "personal-value";
|
|
};
|
|
|
|
# home/work.nix
|
|
modules.yourModule = {
|
|
enable = true;
|
|
someSetting = "work-value";
|
|
};
|
|
```
|
|
|
|
### Adding Application Configuration Files
|
|
|
|
For apps without Home Manager modules, use `home.file`:
|
|
|
|
```nix
|
|
# In modules/home/apps.nix or a new module
|
|
home.file = {
|
|
".config/your-app/config.toml".text = ''
|
|
# Your config content
|
|
setting = "value"
|
|
'';
|
|
|
|
# Or copy from a file
|
|
".config/your-app/config.toml".source = ./files/your-app-config.toml;
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Updating Flake Inputs
|
|
|
|
### Update All Inputs
|
|
|
|
```bash
|
|
cd ~/.dotfiles
|
|
|
|
# Update all inputs to their latest versions
|
|
nix flake update
|
|
|
|
# Review changes
|
|
git diff flake.lock
|
|
|
|
# Apply the updates
|
|
darwin-rebuild switch --flake .#personal
|
|
```
|
|
|
|
### Update Specific Input
|
|
|
|
```bash
|
|
# Update only nixpkgs
|
|
nix flake lock --update-input nixpkgs
|
|
|
|
# Update only home-manager
|
|
nix flake lock --update-input home-manager
|
|
|
|
# Update only nix-darwin
|
|
nix flake lock --update-input nix-darwin
|
|
```
|
|
|
|
### Pin to Specific Version
|
|
|
|
Edit `flake.nix` to pin an input:
|
|
|
|
```nix
|
|
inputs = {
|
|
# Pin to specific commit
|
|
nixpkgs.url = "github:nixos/nixpkgs/abc123...";
|
|
|
|
# Pin to specific branch
|
|
nixpkgs.url = "github:nixos/nixpkgs/nixos-24.05";
|
|
};
|
|
```
|
|
|
|
### Check for Updates
|
|
|
|
```bash
|
|
# Show current input versions
|
|
nix flake metadata
|
|
|
|
# Show what would be updated
|
|
nix flake update --dry-run
|
|
```
|
|
|
|
---
|
|
|
|
## Day-to-Day Operations
|
|
|
|
### Rebuilding After Changes
|
|
|
|
```bash
|
|
cd ~/.dotfiles
|
|
|
|
# Make your changes to .nix files
|
|
vim modules/home/packages.nix
|
|
|
|
# Rebuild and switch
|
|
darwin-rebuild switch --flake .#personal
|
|
```
|
|
|
|
### Quick Rebuild Alias
|
|
|
|
Add to your shell configuration or use directly:
|
|
|
|
```bash
|
|
# Alias for quick rebuilds
|
|
alias rebuild="darwin-rebuild switch --flake ~/.dotfiles#personal"
|
|
alias rebuild-work="darwin-rebuild switch --flake ~/.dotfiles#work"
|
|
```
|
|
|
|
### Checking Configuration Validity
|
|
|
|
```bash
|
|
# Validate the flake
|
|
nix flake check
|
|
|
|
# Build without switching (dry run)
|
|
darwin-rebuild build --flake .#personal
|
|
```
|
|
|
|
### Viewing Generation History
|
|
|
|
```bash
|
|
# List all generations
|
|
darwin-rebuild --list-generations
|
|
|
|
# See what's in the current generation
|
|
ls -la /run/current-system
|
|
```
|
|
|
|
### Rolling Back
|
|
|
|
```bash
|
|
# Rollback to previous generation
|
|
darwin-rebuild --rollback
|
|
|
|
# Switch to specific generation
|
|
darwin-rebuild switch --generation 42
|
|
```
|
|
|
|
### Garbage Collection
|
|
|
|
```bash
|
|
# Remove old generations (keeps current)
|
|
nix-collect-garbage
|
|
|
|
# Remove all old generations
|
|
nix-collect-garbage -d
|
|
|
|
# Remove generations older than 30 days
|
|
nix-collect-garbage --delete-older-than 30d
|
|
```
|
|
|
|
### Development Shell
|
|
|
|
For working on this repository:
|
|
|
|
```bash
|
|
cd ~/.dotfiles
|
|
|
|
# Enter development shell with formatting tools
|
|
nix develop
|
|
|
|
# Format all Nix files
|
|
nixfmt **/*.nix
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### "experimental-features" Error
|
|
|
|
**Problem:** `error: experimental Nix feature 'flakes' is disabled`
|
|
|
|
**Solution:**
|
|
```bash
|
|
mkdir -p ~/.config/nix
|
|
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
|
|
```
|
|
|
|
#### Homebrew Cask Installation Fails
|
|
|
|
**Problem:** A cask fails to install during rebuild
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Update Homebrew
|
|
brew update
|
|
|
|
# Check for issues
|
|
brew doctor
|
|
|
|
# Try installing manually first
|
|
brew install --cask problematic-cask
|
|
|
|
# Then rebuild
|
|
darwin-rebuild switch --flake .#personal
|
|
```
|
|
|
|
#### SSH Key Not Found
|
|
|
|
**Problem:** Git operations fail with SSH key errors
|
|
|
|
**Solution:**
|
|
1. Ensure 1Password SSH agent is enabled
|
|
2. Check the key is in 1Password
|
|
3. Verify the public key file exists:
|
|
```bash
|
|
ls -la ~/.ssh/keys/
|
|
```
|
|
4. Test SSH connection:
|
|
```bash
|
|
ssh -T git@github.com
|
|
```
|
|
|
|
#### Build Fails with "attribute not found"
|
|
|
|
**Problem:** `error: attribute 'somePackage' missing`
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Update flake inputs
|
|
nix flake update
|
|
|
|
# Search for correct package name
|
|
nix search nixpkgs package-name
|
|
```
|
|
|
|
#### Conflicting Files
|
|
|
|
**Problem:** `error: collision between ... and ...`
|
|
|
|
**Solution:**
|
|
1. Check if the file is managed by multiple sources
|
|
2. Remove manual file if it exists:
|
|
```bash
|
|
rm ~/.config/conflicting-file
|
|
```
|
|
3. Rebuild
|
|
|
|
### Debug Mode
|
|
|
|
For detailed error information:
|
|
|
|
```bash
|
|
# Build with trace
|
|
darwin-rebuild switch --flake .#personal --show-trace
|
|
|
|
# Even more verbose
|
|
darwin-rebuild switch --flake .#personal --show-trace --verbose
|
|
```
|
|
|
|
### Interactive Debugging
|
|
|
|
```bash
|
|
# Open Nix REPL with flake loaded
|
|
nix repl
|
|
:lf .
|
|
# Now you can inspect the configuration
|
|
darwinConfigurations.personal.config.home-manager.users.alice.home.packages
|
|
```
|
|
|
|
### Reset to Clean State
|
|
|
|
If things are badly broken:
|
|
|
|
```bash
|
|
# Remove result symlink
|
|
rm -f result
|
|
|
|
# Clean Nix store
|
|
nix-collect-garbage -d
|
|
|
|
# Remove home-manager generations
|
|
rm -rf ~/.local/state/home-manager
|
|
|
|
# Rebuild from scratch
|
|
nix build .#darwinConfigurations.personal.system
|
|
./result/sw/bin/darwin-rebuild switch --flake .#personal
|
|
```
|
|
|
|
### Getting Help
|
|
|
|
```bash
|
|
# Home Manager options
|
|
man home-configuration.nix
|
|
|
|
# nix-darwin options
|
|
man darwin-configuration.nix
|
|
|
|
# Search for options online
|
|
# https://home-manager-options.extranix.com/
|
|
# https://daiderd.com/nix-darwin/manual/
|
|
```
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
1. **Commit changes before rebuilding** - Makes it easy to rollback
|
|
2. **Test builds before switching** - Use `darwin-rebuild build` first
|
|
3. **Update inputs regularly** - Keep packages up to date
|
|
4. **Use garbage collection** - Prevent disk space issues
|
|
5. **Document custom modules** - Add comments explaining purpose
|
|
6. **Keep secrets out of Nix** - Use 1Password or sops-nix for secrets |