johno/nixos-configs

Fork 0

Files

John Ogle c1d6663a36 bd init

2026-01-09 11:21:49 -08:00

8.4 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a NixOS configuration repository using flakes, managing multiple machines and home-manager configurations. The repository follows a modular architecture with reusable "roles" that can be composed for different machines.

Architecture

Flake Structure

flake.nix: Main entry point defining inputs (nixpkgs, home-manager, plasma-manager, etc.) and outputs for multiple NixOS configurations
Machines: nix-book, boxy, wixos (WSL configuration), zix790prors, live-usb, johno-macbookpro (Darwin/macOS)
Home configurations: Standalone home-manager configuration for user johno

Directory Structure

machines/: Machine-specific configurations with hardware-configuration.nix
roles/: Modular system configurations (audio, bluetooth, desktop, users, etc.)
home/: Home Manager configurations and user-specific modules
home/modules/: User environment modules (emacs, i3+sway, plasma-manager, tmux)
packages/: Custom package definitions

Role-Based Configuration System

The repository uses a custom "roles" system where each role is a NixOS module with enable options:

roles.desktop: Desktop environment with sub-options for X11, Wayland, KDE, gaming, SDDM
roles.audio: Audio configuration
roles.bluetooth: Bluetooth support
roles.users: User account management
roles.virtualisation: Virtualization setup
roles.kodi: Kodi media center
roles.nvidia: NVIDIA GPU configuration
roles.printing: Printing support (CUPS)
roles.spotifyd: Spotify daemon
roles.btrfs: Btrfs filesystem configuration
roles.nfs-mounts: NFS mount configuration
roles.darwin: macOS-specific configurations

Example role usage in machine configuration:

roles = {
  audio.enable = true;
  desktop = {
    enable = true;
    gaming = true;
    kde = true;
    wayland = true;
  };
  users.enable = true;
};

Home-Manager Role System

The repository also uses a modular home-manager role system for user-space configuration:

Available Home Roles:

home.roles.base: Core CLI tools, git, ssh, bash, rbw (enabled everywhere)
home.roles.desktop: GUI applications, Firefox, KDE services
home.roles.office: LibreOffice, OpenSCAD (heavy packages)
home.roles.media: VLC, Jellyfin, Moonlight (media consumption)
home.roles.development: Custom packages, kubectl, development tools
home.roles.communication: Element, Nextcloud Talk, Google cookie tools
home.roles.sync: Syncthing service and tray (for file synchronization)
home.roles.kdeconnect: KDE Connect for device integration
home.roles.gaming: Gaming applications (future expansion)

Role-Based Home Configurations:

home-desktop.nix: Full-featured desktop for development workstations
home-media-center.nix: Living room media consumption and gaming setup (boxy)
home-laptop-compact.nix: Essential tools only, excludes office/media for storage constraints (nix-book)
home-live-usb.nix: Minimal setup for live environments, no persistent services
home-darwin-work.nix: macOS work laptop configuration

Machine-Specific Role Usage:

nix-book: Compact laptop → excludes office/media roles due to SSD space constraints
boxy: Living room media center → optimized for media consumption, excludes sync/office (shared machine)
zix790prors: All-purpose workstation → full desktop experience with all roles enabled
wixos: WSL2 development → full desktop experience, inherits from zix790prors Windows host
live-usb: Temporary environment → only base + desktop roles, no persistent services
johno-macbookpro: macOS work laptop → Darwin-specific configuration with development tools

Common Commands

Building and Switching Configurations

NixOS (Linux):

# Build and switch to a specific machine configuration
sudo nixos-rebuild switch --flake .#<hostname>

# Build without switching
nixos-rebuild build --flake .#<hostname>

# Build home-manager configuration only
home-manager switch --flake .#johno

Darwin (macOS):

# Build and switch to Darwin configuration
darwin-rebuild switch --flake .#johno-macbookpro

# Build without switching
darwin-rebuild build --flake .#johno-macbookpro

Available Machine Configurations

nix-book: Compact laptop with storage constraints, uses home/home-laptop-compact.nix
boxy: Shared living room media center/gaming desktop with AMD GPU, uses home/home-media-center.nix
zix790prors: Powerful all-purpose workstation (gaming, 3D modeling, development), dual-boots Windows 11 with shared btrfs /games partition, uses home/home-desktop.nix
wixos: WSL2 development environment running in Windows partition of zix790prors, uses home/home-desktop.nix
live-usb: Bootable ISO configuration, uses home/home-live-usb.nix
johno-macbookpro: macOS work laptop, uses home/home-darwin-work.nix

Flake Operations

# Update flake inputs
nix flake update

# Check flake
nix flake check

# Show flake info
nix flake show

Bootstrap New Machine

Use the provided bootstrap script:

sudo ./bootstrap.sh <hostname>

This script pulls from the remote git repository and applies the configuration.

Build Live USB ISO

Use the provided script to build a bootable ISO:

./build-liveusb.sh

Creates an ISO suitable for Ventoy and other USB boot tools in ./result/iso/.

Development Workflow

Adding New Machines

NixOS:

Create new directory in machines/<hostname>/
Add configuration.nix with role assignments
Include hardware-configuration.nix (generated by nixos-generate-config)
Add nixosConfiguration to flake.nix outputs

Darwin (macOS):

Create new directory in machines/<hostname>/
Add configuration.nix with Darwin role assignments
Add darwinConfiguration to flake.nix outputs

Adding New Roles

Create directory in roles/<role-name>/
Create default.nix with module definition using mkEnableOption
Add role import to roles/default.nix
Configure role options in machine configurations

Home Manager Modules

Located in home/modules/
Each module has its own default.nix
Imported in main home configuration files

Key Configuration Details

Experimental features: nix-command and flakes are enabled
User: Primary user is johno with trusted-user privileges
Locale: en_US.UTF-8, America/Los_Angeles timezone
SSH: OpenSSH enabled on all configurations
Garbage collection: Automatic, deletes older than 10 days
Unfree packages: Allowed globally

Issue Tracking (Gitea)

Tea CLI for Gitea:

# Note: When using tea CLI, you must specify --repo johno/nixos-configs
# The CLI doesn't automatically detect the repo from git remote

# List all issues (open by default)
tea issues --repo johno/nixos-configs

# List closed issues
tea issues --repo johno/nixos-configs --state closed

# View specific issue
tea issue --repo johno/nixos-configs 2

# Create new issue
tea issues create --repo johno/nixos-configs --title "Issue title" --body "Description"

# Add comment to issue
tea comment --repo johno/nixos-configs 2 "Comment text"

# Close issue (note: 'issues' is plural, issue number comes last)
tea issues close --repo johno/nixos-configs 2

Important Notes

Sudo access: Claude Code does not have sudo access. Ask the user to run elevated commands like sudo nixos-rebuild switch

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

File issues for remaining work - Create issues for anything that needs follow-up
Run quality gates (if code changed) - Tests, linters, builds
Update issue status - Close finished work, update in-progress items

PUSH TO REMOTE - This is MANDATORY:

git pull --rebase
bd sync
git push
git status  # MUST show "up to date with origin"

Clean up - Clear stashes, prune remote branches
Verify - All changes committed AND pushed
Hand off - Provide context for next session

CRITICAL RULES:

Work is NOT complete until git push succeeds
NEVER stop before pushing - that leaves work stranded locally
NEVER say "ready to push when you are" - YOU must push
If push fails, resolve and retry until it succeeds

8.4 KiB Raw Blame History