159 lines
4.2 KiB
Markdown
159 lines
4.2 KiB
Markdown
# Quick Start Guide for NixOS Configuration Repository
|
|
|
|
This guide provides essential information for agents to quickly understand and work with this NixOS configuration repository.
|
|
|
|
## Repository at a Glance
|
|
|
|
- **Type**: Flake-based NixOS configuration
|
|
- **Base**: NixOS 25.05 stable with selective unstable packages
|
|
- **Systems**: framework (laptop), aurora (desktop), labrizor (desktop)
|
|
- **Desktop**: KDE Plasma with modular application sets
|
|
- **Users**: jsutter (primary), isutter, aksutter
|
|
|
|
## Essential Commands
|
|
|
|
### Testing Configuration
|
|
```bash
|
|
# Check flake syntax and outputs
|
|
nix flake check
|
|
|
|
# Dry run for specific system
|
|
sudo nixos-rebuild dry-run --flake .#systemname
|
|
|
|
# Show flake outputs
|
|
nix flake show
|
|
```
|
|
|
|
### Applying Changes
|
|
```bash
|
|
# Apply to specific system
|
|
sudo nixos-rebuild switch --flake .#systemname
|
|
|
|
# Build only (don't switch)
|
|
sudo nixos-rebuild build --flake .#systemname
|
|
|
|
# Test (current generation rollback on reboot)
|
|
sudo nixos-rebuild test --flake .#systemname
|
|
```
|
|
|
|
### Updates
|
|
```bash
|
|
# Update all flake inputs
|
|
nix flake update
|
|
|
|
# Update only unstable packages
|
|
nix flake lock --update-input nixpkgs-unstable
|
|
```
|
|
|
|
## File Locations
|
|
|
|
| What you want to do | Where to edit |
|
|
|---------------------|---------------|
|
|
| Add system packages | `systems/common.nix` |
|
|
| Add development tools | `desktop/dev.nix` |
|
|
| Add desktop apps | `desktop/[category].nix` |
|
|
| Modify user settings | `users/[username].nix` |
|
|
| System-specific settings | `systems/[hostname].nix` |
|
|
| Add new system | Edit `flake.nix` + create `systems/[hostname].nix` |
|
|
|
|
## Adding Packages: Quick Reference
|
|
|
|
```nix
|
|
# In appropriate .nix file
|
|
{ config, pkgs, pkgs-unstable, ... }: # Add pkgs-unstable if needed
|
|
|
|
{
|
|
# Use stable packages
|
|
environment.systemPackages = with pkgs; [
|
|
firefox
|
|
git
|
|
new-package
|
|
];
|
|
|
|
# Use unstable when necessary
|
|
environment.systemPackages = with pkgs; [
|
|
pkgs-unstable.latest-tool # Comment why unstable is needed
|
|
];
|
|
}
|
|
```
|
|
|
|
## System Status
|
|
|
|
### framework (Laptop)
|
|
- Hardware: Framework AMD AI 300 series
|
|
- Special: AMD GPU optimization, power management
|
|
- Users: jsutter
|
|
|
|
### aurora (Desktop)
|
|
- Hardware: Generic desktop
|
|
- Special: 3D/2D printing, multiple users
|
|
- Users: jsutter, isutter, aksutter
|
|
|
|
### labrizor (Desktop)
|
|
- Hardware: Generic desktop
|
|
- Special: 3D printing
|
|
- Users: jsutter
|
|
|
|
## Module Structure
|
|
|
|
### Common Desktop Modules (applied to all desktop systems)
|
|
- `systems/common.nix` - Base system config
|
|
- `desktop/plasma.nix` - KDE Plasma
|
|
- `desktop/dev.nix` - Development tools
|
|
- `desktop/office.nix` - Office applications
|
|
- `desktop/gaming.nix` - Gaming platforms
|
|
- `desktop/media.nix` - Audio/video software
|
|
- `desktop/virtualization.nix` - VM/container support
|
|
- `desktop/tailscale.nix` - VPN for internet archive
|
|
- `desktop/3dprinting.nix` - 3D printing tools
|
|
- `desktop/2dprinting.nix` - 2D printing tools
|
|
|
|
## Critical Rules
|
|
|
|
1. **Always test before applying**: Use `dry-run` first
|
|
2. **Use stable packages unless necessary**: Document unstable usage
|
|
3. **Follow file placement rules**: Put configs in correct directories
|
|
4. **Maintain security**: Never commit secrets or private keys
|
|
|
|
|
|
## Emergency Recovery
|
|
|
|
If system fails to boot:
|
|
```bash
|
|
# Boot from installation media
|
|
mount /dev/disk/by-partlabel/primary /mnt
|
|
cd /mnt/root/nixos
|
|
sudo nixos-rebuild switch --rollback
|
|
```
|
|
|
|
## Common Patterns
|
|
|
|
### Add New Package
|
|
1. Choose appropriate file (see table above)
|
|
2. Add to `environment.systemPackages`
|
|
3. Test: `sudo nixos-rebuild dry-run --flake .#system-name`
|
|
4. Apply: `sudo nixos-rebuild switch --flake .#system-name`
|
|
|
|
### Add New User
|
|
1. Create `users/newuser.nix` following existing pattern
|
|
2. Add to desired system in `flake.nix`
|
|
3. Test and apply
|
|
|
|
### Add New System
|
|
1. Create `systems/hostname.nix` with hardware config
|
|
2. Add to `flake.nix` following existing pattern
|
|
3. Test and apply
|
|
|
|
## Documentation
|
|
|
|
- **Project Guide**: `docs/PROJECT_GUIDE.md` - Comprehensive documentation
|
|
- **File Structure**: `docs/FILE_STRUCTURE.md` - Detailed file reference
|
|
- **Workflows**: `docs/WORKFLOW.md` - Step-by-step procedures
|
|
- **Rules**: `.clinerules` - Agent-specific guidelines
|
|
|
|
## Get Help
|
|
|
|
1. Check existing patterns in similar files
|
|
2. Read `docs/PROJECT_GUIDE.md` for detailed information
|
|
3. Follow `.clinerules` for best practices
|
|
4. Test thoroughly before applying changes
|