nixos-configurations/README.md

# NixOS Configuration

Personal NixOS system configuration using Flakes and Home Manager for declarative system management.

## System Overview

- **OS**: NixOS 25.11
- **Desktop Environment**: GNOME (Wayland/X11)
- **Terminal**: Ghostty + tmux
- **Shell**: Zsh with Oh-My-Zsh (agnoster theme)
- **Editor**: Neovim with [kickstart.nvim](https://github.com/0xWheatyz/kickstart.nvim)
- **Hostname**: nixos

## Features

### Core System
- **Bootloader**: GRUB with EFI support and OS Prober (dual-boot ready)
- **Timezone**: America/New_York
- **Locale**: en_US.UTF-8
- **Networking**: NetworkManager enabled

### Hardware Support
- **Bluetooth**: Enabled with Blueman
- **Fingerprint Sensor**: fprintd enabled
- **Audio**: PipeWire with ALSA and PulseAudio compatibility
- **Printing**: CUPS enabled

### Security & Authentication
- **YubiKey Support**: Configured for login and sudo authentication
- **Auto-lock on YubiKey removal**: Sessions lock when YubiKey is disconnected
- **Fingerprint Authentication**: Available for compatible hardware

### Development Environment
- **Docker**: Rootless mode enabled with proper namespace configuration
- **VMware Workstation**: Host support enabled
- **Nix Flakes**: Experimental features enabled

### Networking
- **Tailscale VPN**: Enabled with client routing features
- **Firewall**: Configured with Tailscale trusted interface
- **Editable /etc/hosts**: Permissions set to 0644 for easy modification

### Desktop Customization
- **GNOME Extensions**:
  - Blur My Shell
  - Just Perfection
  - Arc Menu
- **Fonts**: 0xProto Nerd Font, Adwaita icons
- **Scaling**: Experimental fractional scaling and xwayland-native-scaling enabled
- **QT Integration**: QT apps use GNOME theme (Adwaita Dark)

### Alternative Window Manager
- **Hyprland**: Configured but not currently active (see `home.nix` for configuration)

## Installed Software

### System Packages
- Firefox
- VMware Workstation
- Lunar Client (Minecraft)
- JetBrains Rust Rover
- Cursor (VS Code fork)
- Obsidian
- Claude Code

### User Packages
- Kate (KDE text editor)
- Bitwarden (desktop + CLI)
- LunarVim
- KiCad
- Ghostty terminal
- Python 3
- nmap
- minicom
- freerdp

## Configuration Files

```
.
├── configuration.nix          # System-level configuration
├── home.nix                   # User-level configuration (Home Manager)
├── hardware-configuration.nix # Auto-generated hardware config
└── flake.nix                  # Flake inputs and outputs
```

## Getting Started

### First Time Setup

1. Clone this repository:
```bash
git clone <your-repo-url> ~/Documents/nixos-configuration
cd ~/Documents/nixos-configuration
```

2. Review and customize configurations:
   - Edit `configuration.nix` for system-wide changes
   - Edit `home.nix` for user-specific settings

3. Apply the configuration:
```bash
sudo nixos-rebuild switch --flake .#nixos
```

### Making Changes

#### System-Level Changes
Edit `configuration.nix` and rebuild:
```bash
sudo nixos-rebuild switch --flake .#nixos
```

#### User-Level Changes
Edit `home.nix` and rebuild:
```bash
sudo nixos-rebuild switch --flake .#nixos
# or use home-manager directly:
home-manager switch
```

### Adding Packages

**System-wide** (available to all users):
Add to `environment.systemPackages` in `configuration.nix`:
```nix
environment.systemPackages = with pkgs; [
  # your-package-here
];
```

**User-specific**:
Add to `home.packages` in `home.nix`:
```nix
home.packages = with pkgs; [
  # your-package-here
];
```

### Updating the System

Update flake inputs and rebuild:
```bash
nix flake update
sudo nixos-rebuild switch --flake .#nixos
```

## Key Configurations

### Git Configuration
Managed declaratively in `home.nix`:
- **User**: 0xWheatyz
- **Email**: wyatt@leeworks.dev
- **Default Branch**: master
- **Auto push remote setup**: Enabled
- **Custom alias**: `git lg` for pretty log visualization

### SSH Configuration
Custom SSH hosts configured in `home.nix`:
- **vps**: Direct connection to 45.79.198.105
- **home**: Via jump host proxy
- **git**: Local git server at 10.0.1.10
- Connection multiplexing enabled for faster subsequent connections

### Tmux
- Mouse support enabled
- Window numbering starts at 1
- 256-color terminal support
- Auto-starts on terminal launch

### Zsh
- Oh-My-Zsh with agnoster theme
- Custom `nix develop` wrapper that launches in zsh
- Tmux auto-start on interactive terminals
- Project shell indicator in prompt

## Neovim Configuration

Using [kickstart.nvim](https://github.com/0xWheatyz/kickstart.nvim) as the base configuration, managed through Flakes.

Required dependencies are automatically installed:
- Neovim
- ripgrep
- fd
- gcc
- gnumake
- git

Configuration is synchronized from the GitHub repository and placed in `~/.config/nvim`.

## Docker Configuration

Docker is configured in rootless mode:
- Unprivileged user namespaces enabled
- Socket variable automatically set
- User `l-wyatt` is in the `docker` group

Usage:
```bash
docker ps  # No sudo required
```

## Troubleshooting

### Slow Shutdown
The configuration includes optimizations for shutdown handling:
- User manager timeout reduced to 30s (from default 90s)
- Prevents hangs when user linger is enabled

### Building from Flake
If you encounter issues, try:
```bash
# Rebuild with verbose output
sudo nixos-rebuild switch --flake .#nixos --show-trace

# Check flake validity
nix flake check

# Update flake lock file
nix flake update
```

### YubiKey Issues
If YubiKey authentication isn't working:
```bash
# Check PAM configuration
cat /etc/pam.d/login
cat /etc/pam.d/sudo

# Verify udev rules
udevadm control --reload-rules
```

## Important Notes

- **stateVersion**: Set to 25.11 - do not change after initial installation
- **Home Manager stateVersion**: Also 25.11 - keep in sync with system version
- **Unfree packages**: Enabled system-wide via `nixpkgs.config.allowUnfree`
- **User groups**: l-wyatt is member of: networkmanager, wheel, docker, dialout
- **User linger**: Enabled for background services

## Additional Resources

- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
- [Home Manager Manual](https://nix-community.github.io/home-manager/)
- [Nix Flakes](https://nixos.wiki/wiki/Flakes)
- [kickstart.nvim Documentation](https://github.com/nvim-lua/kickstart.nvim)

## License

This configuration is personal and provided as-is for reference.