From 61a50dad27e5376077cd5967796437cf3c2ca900 Mon Sep 17 00:00:00 2001 From: Geir Okkenhaug Jerstad Date: Thu, 5 Jun 2025 10:03:01 +0200 Subject: [PATCH] Updated README --- README.md | 305 +++++++++++++++++++++++++++--------------------------- 1 file changed, 154 insertions(+), 151 deletions(-) diff --git a/README.md b/README.md index 4f7b46d..e65b9c3 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,47 @@ -# ๐Ÿ  NixOS Home Lab Infrastructure +# ๐Ÿ  NixOS Home Lab Adventures [![NixOS](https://img.shields.io/badge/NixOS-25.05-blue.svg)](https://nixos.org/) [![Flakes](https://img.shields.io/badge/Nix-Flakes-green.svg)](https://nixos.wiki/wiki/Flakes) [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -Infrastructure as Code for a multi-machine NixOS home lab environment using flakes and modular configuration. +A personal journey into NixOS flakes and home lab tinkering. This is my playground for learning declarative system configuration and building a multi-machine setup that's both fun and functional. -## ๐Ÿš€ Quick Start +## ๐Ÿš€ Getting Started + +Want to try this out? Here's how to get rolling: ```bash -# Clone the repository +# Grab the repo git clone Home-lab cd Home-lab -# Check flake configuration +# Make sure everything looks good nix flake check -# Build configuration (test) +# Test it out (won't mess with your current setup) sudo nixos-rebuild test --flake .#congenital-optimist -# Apply configuration (permanent) +# If you're happy with it, make it permanent sudo nixos-rebuild switch --flake .#congenital-optimist ``` -## ๐Ÿ—๏ธ Architecture Overview +## ๐Ÿ—๏ธ What We're Working With -### Machines -- **`congenital-optimist`** - AMD Threadripper workstation (primary development) -- **`sleeper-service`** - Intel Xeon E3-1230 V2 file server (network storage) +### The Machines +- **`congenital-optimist`** - My main AMD Threadripper beast for development and experimentation +- **`sleeper-service`** - Intel Xeon E3-1230 V2 running file server duties (the quiet workhorse) -### Technology Stack -- **OS**: NixOS 25.05 (Warbler) -- **Configuration**: Nix Flakes with modular structure -- **Virtualization**: Incus, Libvirt/QEMU, Podman -- **Desktop**: GNOME, Cosmic, Sway -- **Storage**: ZFS with snapshots and NFS -- **Network**: Tailscale mesh networking +### The Stack +- **OS**: NixOS 25.05 (Warbler) - because reproducible builds are beautiful +- **Configuration**: Nix Flakes with modular approach - keeping things organized +- **Virtualization**: Incus, Libvirt/QEMU, Podman - gotta test stuff somewhere +- **Desktop**: GNOME, Cosmic, Sway - variety is the spice of life +- **Storage**: ZFS with snapshots and NFS - never lose data again +- **Network**: Tailscale mesh - because VPNs should just work -## ๐Ÿ“ Repository Structure +## ๐Ÿ“ How It's Organized + +Everything's broken down into logical chunks to keep things manageable: ``` Home-lab/ @@ -64,190 +68,189 @@ Home-lab/ โ””โ”€โ”€ secrets/ # Encrypted secrets (future) ``` -## ๐Ÿ”ง Configuration Management +## ๐Ÿ”ง How I Manage This Chaos -### Modular Design -Each aspect of the system is organized into focused modules: +### Keeping Things Modular +I've split everything into focused modules so I don't go insane: -- **Desktop Environments**: Separate modules for GNOME, Cosmic, and Sway -- **Virtualization**: Independent Incus, Libvirt, and Podman configurations -- **Development**: Modular tool configurations for different workflows -- **Hardware**: Hardware-specific optimizations and drivers +- **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 -User configurations use Emacs org-mode for literate programming: -- Self-documenting configuration files -- Automatic tangling from `.org` to configuration files -- Version-controlled documentation alongside code +### 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 -## ๐Ÿš€ Deployment Workflow +## ๐Ÿš€ My Workflow -### Local Development +### Tinkering Locally ```bash -# Check configuration syntax +# Check if I broke anything nix flake check -# Test configuration without switching +# Test changes without committing to them sudo nixos-rebuild test --flake .# -# Build configuration +# Build and see what happens sudo nixos-rebuild build --flake .# -# Apply configuration +# Ship it! sudo nixos-rebuild switch --flake .# ``` -### GitOps Workflow -1. **Feature Branch**: Create branch for configuration changes -2. **Local Testing**: Test changes with `nixos-rebuild test` -3. **Pull Request**: Submit PR with configuration validation -4. **Automated Testing**: CI pipeline validates configuration -5. **Review & Merge**: Code review and merge to main -6. **Deployment**: Automated or manual deployment to machines +### 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" -## ๐Ÿ” Security & Secrets +## ๐Ÿ” Secrets and Security -### Current Approach -- No secrets in git repository -- Manual secret management during initial setup -- ZFS encryption for sensitive data +### Current Reality +- No secrets in git (obviously) +- Manual secret juggling during setup (it's fine, really) +- ZFS encryption for the important stuff -### Planned Improvements -- **agenix** or **sops-nix** for encrypted secrets in git -- **age** keys for secret encryption/decryption -- **CI/CD** integration with secret management +### Future Dreams +- **agenix** or **sops-nix** for proper secret management +- **age** keys for encryption magic +- **CI/CD** that doesn't leak passwords everywhere -## ๐ŸŽฏ Machine Specifications +## ๐ŸŽฏ The Hardware -### CongenitalOptimist (AMD Workstation) -- **CPU**: AMD Threadripper (details in hardware-configuration.nix) -- **GPU**: AMD (with proper drivers and virtualization passthrough) -- **Storage**: ZFS pools (zpool + stuffpool) -- **Use Case**: Primary development, virtualization, desktop environments -- **Services**: Development tools, desktop environments, VM host +### 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 (Intel File Server) -- **CPU**: Intel Xeon E3-1230 V2 @ 3.70GHz (4 cores, 8 threads) -- **Memory**: 16GB RAM -- **Storage**: ZFS with redundancy -- **Use Case**: Network storage, file sharing, backup services -- **Services**: NFS, Samba, automated backups, monitoring +### 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 Strategy +## ๐Ÿงช Testing (The "Does It Work?" Phase) -### Automated Testing (Planned) -- **Configuration Validation**: `nix flake check` in CI -- **Build Testing**: Test builds for all machines -- **Module Testing**: Individual module validation -- **Integration Testing**: Full system build verification +### 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 -### Manual Testing Checklist -- [ ] System boots successfully -- [ ] Desktop environments functional -- [ ] Virtualization stack operational -- [ ] Network services accessible -- [ ] User environment complete -- [ ] Development tools working +### 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 -## ๐Ÿ“ˆ Monitoring & Maintenance +## ๐Ÿ“ˆ Keeping Things Running -### Health Checks -- System generation switching -- Service status monitoring -- ZFS pool health -- Network connectivity -- Resource utilization +### 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 -- **ZFS Snapshots**: Automatic filesystem snapshots -- **Configuration Backups**: Git repository with full history -- **Data Backups**: Automated backup services on SleeperService -- **Recovery Procedures**: Documented rollback processes +### 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 Pipeline (Planned) +## ๐Ÿ”„ CI/CD Dreams (Work in Progress) -### Validation Pipeline +### Validation Pipeline (The Plan) ```yaml -# Planned GitHub Actions workflow -- Syntax Check: nix flake check -- Build Test: nix build .#nixosConfigurations. -- Security Scan: Nix security auditing -- Documentation: Update system documentation +# What I want GitHub Actions to do +- Syntax Check: nix flake check # Catch the obvious stuff +- Build Test: nix build .#nixosConfigurations. # 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 +### Deployment Pipeline (The Dream) ```yaml -# Planned deployment automation -- Staging: Deploy to test environment -- Integration Tests: Automated system testing -- Production: Deploy to production machines -- Rollback: Automatic rollback on failure +# 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) ``` -## ๐Ÿค Contributing +## ๐Ÿค Want to Contribute? -### Development Workflow -1. Fork/clone repository -2. Create feature branch -3. Make configuration changes -4. Test locally with `nixos-rebuild test` -5. Submit pull request -6. Address review feedback -7. Merge after approval +### 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 Guidelines -- Keep modules focused and single-purpose -- Document module options and usage -- Test modules independently when possible -- Follow consistent naming conventions -- Include example configurations +### 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](plan.md)**: Detailed migration and development plan -- **[Instructions](instruction.md)**: Step-by-step setup instructions -- **[Machine Documentation](machines/)**: Per-machine documentation -- **[Module Documentation](modules/)**: Module-specific documentation -- **[User Documentation](users/)**: User configuration documentation +- **[Plan](plan.md)**: The grand vision and migration roadmap +- **[Instructions](instruction.md)**: Step-by-step setup and AI agent guidance +- **[Machine Documentation](machines/)**: Individual machine configs and notes +- **[Module Documentation](modules/)**: How each module works +- **[User Documentation](users/)**: User-specific configuration details -## ๐ŸŽฏ Roadmap +## ๐ŸŽฏ The Journey So Far ### Phase 1: Flakes Migration โœ… -- [x] Convert to flake-based configuration -- [x] Modularize desktop environments -- [x] Add comprehensive virtualization -- [x] Set up GitOps foundation +- [x] Converted to flake-based configuration (no more channels!) +- [x] Modularized desktop environments (sanity preserved) +- [x] Added comprehensive virtualization (all the containers) +- [x] Set up GitOps foundation (git-driven everything) -### Phase 2: Configuration Cleanup -- [ ] Optimize modular structure -- [ ] Enhance documentation -- [ ] Standardize module interfaces +### 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 -- [ ] Add SleeperService configuration -- [ ] Implement service modules -- [ ] Set up network storage +### 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 -- [ ] Implement automated testing -- [ ] Set up deployment pipelines -- [ ] Add monitoring and alerting +### 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 -- [ ] Secrets management -- [ ] Advanced monitoring -- [ ] Backup automation +### 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](LICENSE) file for details. +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. Feel free to steal ideas, improve things, or just poke around. -## ๐Ÿ™ Acknowledgments +## ๐Ÿ™ Thanks -- **NixOS Community** for excellent documentation and support -- **Culture Ship Names** for inspiring machine nomenclature -- **Emacs Community** for literate programming inspiration -- **Home Lab Community** for sharing knowledge and experience +- **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 ---