init
This commit is contained in:
Morten Olsen
626
docs/usage.md
Normal file
626
docs/usage.md
Normal file
@@ -0,0 +1,626 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user