home-lab/README_old.md

NixOS Home Lab Infrastructure

Modular NixOS flake configuration for multi-machine home lab infrastructure. Features declarative system configuration, centralized user management, and scalable service deployment across development workstations and server infrastructure.

Quick Start

# Clone repository
git clone <repository-url> Home-lab
cd Home-lab

# Validate configuration
nix flake check

# Test configuration (temporary, reverts on reboot)
sudo nixos-rebuild test --flake .#<machine-name>

# Apply configuration permanently
sudo nixos-rebuild switch --flake .#<machine-name>

Architecture Overview

Machine Types

• Development Workstation - High-performance AMD Threadripper with desktop environments
• File Server - Intel Xeon with ZFS storage and NFS services
• Application Server - Containerized services (Git hosting, media server)
• Reverse Proxy - External gateway with SSL termination and service routing

Technology Stack

• Base OS: NixOS 25.05 with Nix Flakes
• Configuration: Modular, declarative system configuration
• Virtualization: Incus containers, Libvirt/QEMU VMs, Podman containers
• Desktop: GNOME, Cosmic, Sway window managers
• Storage: ZFS with snapshots, automated mounting, NFS network storage
• Network: Tailscale mesh VPN with centralized hostname resolution

📁 How It's Organized

Everything's broken down into logical chunks to keep things manageable:

Home-lab/
├── flake.nix              # Main flake configuration
├── flake.lock             # Locked dependency versions
├── machines/              # Machine-specific configurations
│   ├── congenital-optimist/  # AMD workstation
│   └── sleeper-service/      # Intel file server
├── modules/               # Reusable NixOS modules
│   ├── common/           # Shared system configuration
│   ├── desktop/          # Desktop environment modules
│   ├── development/      # Development tools and editors
│   ├── hardware/         # Hardware-specific configurations
│   ├── services/         # Service configurations
│   ├── system/           # Core system modules
│   ├── users/            # User configurations
│   └── virtualization/   # Container and VM setup
├── users/                # User-specific configurations
│   └── geir/            # Primary user configuration
│       ├── dotfiles/    # Literate configuration with org-mode
│       └── user.nix     # System-level user config
├── overlays/             # Nix package overlays
├── packages/             # Custom package definitions
└── secrets/              # Encrypted secrets (future)

🔧 How I Manage This Chaos

Keeping Things Modular

I've split everything into focused modules so I don't go insane:

• Desktop Environments: Each DE gets its own module - no more giant config files
• Virtualization: Separate configs for Incus, Libvirt, and Podman - mix and match as needed
• Development: Modular tool setups for different workflows - because context switching is real
• Hardware: Hardware-specific tweaks and drivers - make the silicon sing

Literate Programming (Because Documentation Matters)

My user configs live in Emacs org-mode files - it's like having your documentation and code hold hands:

• Configuration files that explain themselves
• Automatic tangling from .org files to actual configs
• Git tracks both the code and the reasoning behind it

🚀 My Workflow

Tinkering Locally

# Check if I broke anything
nix flake check

# Test changes without committing to them
sudo nixos-rebuild test --flake .#<machine-name>

# Build and see what happens
sudo nixos-rebuild build --flake .#<machine-name>

# Ship it!
sudo nixos-rebuild switch --flake .#<machine-name>

Git-Driven Chaos (In a Good Way)

1. Feature Branch: New idea? New branch.
2. Local Testing: Break things safely with nixos-rebuild test
3. Pull Request: Show off the changes
4. Review: Someone sanity-checks my work
5. Deploy: Either automated or "click the button"

🔐 Secrets and Security

Current Reality

• No secrets in git (obviously)
• Manual secret juggling during setup (it's fine, really)
• ZFS encryption for the important stuff

Future Dreams

• agenix or sops-nix for proper secret management
• age keys for encryption magic
• CI/CD that doesn't leak passwords everywhere

🎯 The Hardware

CongenitalOptimist (The Workstation)

• CPU: AMD Threadripper (check hardware-configuration.nix for the gory details)
• GPU: AMD (with proper drivers and GPU passthrough for VMs)
• Storage: ZFS pools (zpool for system, stuffpool for data hoarding)
• Role: Main development machine, VM playground, desktop environment testing ground
• Services: Whatever I'm experimenting with this week

SleeperService (The Quiet One)

• CPU: Intel Xeon E3-1230 V2 @ 3.70GHz (4 cores, 8 threads - still plenty peppy)
• Memory: 16GB RAM (enough for file serving duties)
• Storage: ZFS with redundancy (because data loss is sadness)
• Role: Network storage, file sharing, backup duties, monitoring the other machines
• Services: NFS, Samba, automated backups, keeping an eye on things

🧪 Testing (The "Does It Work?" Phase)

Automated Testing (Someday Soon)

• Configuration Validation: nix flake check in CI - catch dumb mistakes early
• Build Testing: Test builds for all machines - make sure nothing's broken
• Module Testing: Individual module validation - each piece should work alone
• Integration Testing: Full system builds - the moment of truth

My Manual Testing Ritual

• System actually boots (surprisingly important)
• Desktop environments don't crash immediately
• VMs and containers start up
• Network services respond
• Development environment loads
• Can actually get work done

📈 Keeping Things Running

Health Checks (The Boring But Important Stuff)

• Generation switching (did the update work?)
• Service status monitoring (what's broken now?)
• ZFS pool health (happy disks = happy life)
• Network connectivity (can I reach the internet?)
• Resource usage (is something eating all my RAM?)

Backup Strategy (Paranoia Pays Off)

• ZFS Snapshots: Automatic filesystem snapshots - time travel for your data
• Configuration Backups: Git repo with full history - every mistake preserved for posterity
• Data Backups: Automated services on SleeperService - redundancy is key
• Recovery Procedures: Documented rollback processes - for when everything goes sideways

🔄 CI/CD Dreams (Work in Progress)

Validation Pipeline (The Plan)

# What I want GitHub Actions to do
- Syntax Check: nix flake check  # Catch the obvious stuff
- Build Test: nix build .#nixosConfigurations.<machine>  # Does it actually build?
- Security Scan: Nix security auditing  # Keep the bad guys out
- Documentation: Update system docs  # Because future me will forget

Deployment Pipeline (The Dream)

# Automated deployment magic
- Staging: Deploy to test environment  # Break things safely
- Integration Tests: Automated system testing  # Does everything still work?
- Production: Deploy to production machines  # The moment of truth
- Rollback: Automatic rollback on failure  # When things go wrong (they will)

🤝 Want to Contribute?

How to Jump In

1. Fork or clone the repo
2. Create a feature branch for your idea
3. Make your changes
4. Test locally with nixos-rebuild test (don't break my machine)
5. Submit a pull request
6. Chat about it in the review
7. Merge when we're both happy

Module Development Tips

• Keep modules focused - one job, do it well
• Document what your module does and how to use it
• Test modules independently when you can
• Use consistent naming (future you will thank you)
• Include example configurations for others

📖 Documentation

• Plan: The grand vision and migration roadmap
• Instructions: Step-by-step setup and AI agent guidance
• Machine Documentation: Individual machine configs and notes
• Module Documentation: How each module works
• User Documentation: User-specific configuration details

🎯 The Journey So Far

Phase 1: Flakes Migration ✅

• Converted to flake-based configuration (no more channels!)
• Modularized desktop environments (sanity preserved)
• Added comprehensive virtualization (all the containers)
• Set up GitOps foundation (git-driven everything)

Phase 2: Configuration Cleanup (In Progress)

• Optimize modular structure (make it even better)
• Enhance documentation (explain the magic)
• Standardize module interfaces (consistency is king)

Phase 3: Multi-Machine Expansion (Coming Soon)

• Add SleeperService configuration (wake up the sleeper)
• Implement service modules (automate all the things)
• Set up network storage (centralized data paradise)

Phase 4: Automation & CI/CD (The Dream)

• Implement automated testing (catch problems early)
• Set up deployment pipelines (one-click deploys)
• Add monitoring and alerting (know when things break)

Phase 5: Advanced Features (Future Fun)

• Secrets management (proper secret handling)
• Advanced monitoring (graphs and dashboards)
• Backup automation (paranoia made easy)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details. Feel free to steal ideas, improve things, or just poke around.

🙏 Thanks

• NixOS Community for excellent docs and endless patience with newbie questions
• Culture Ship Names for inspiring machine nomenclature (because why not?)
• Emacs Community for literate programming inspiration and org-mode magic
• Home Lab Community for sharing knowledge, war stories, and "it works on my machine" solutions

---

"The ship had decided to call itself the Arbitrary, presumably for much the same reason."