geir/home-lab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated README
Some checks are pending
🏠 Home Lab CI/CD Pipeline / 🔍 Validate Configuration (push) Waiting to run
Details
🏠 Home Lab CI/CD Pipeline / 🔨 Build Configurations (push) Blocked by required conditions
Details
🏠 Home Lab CI/CD Pipeline / 🔒 Security Audit (push) Blocked by required conditions
Details
🏠 Home Lab CI/CD Pipeline / 📚 Documentation & Modules (push) Blocked by required conditions
Details
🏠 Home Lab CI/CD Pipeline / 🔄 Update Dependencies (push) Waiting to run
Details
🏠 Home Lab CI/CD Pipeline / 🚀 Deploy Configuration (push) Blocked by required conditions
Details
🏠 Home Lab CI/CD Pipeline / 📢 Notify Results (push) Blocked by required conditions
Details

Browse source
This commit is contained in:
Geir Okkenhaug Jerstad 2025-06-05 10:03:01 +02:00
parent 5b3a058e7e
commit 61a50dad27
1 changed files with 154 additions and 151 deletions
Download patch file Download diff file Expand all files Collapse all files

305
README.md
View file

@ -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/) [![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) [![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) [![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 ```bash
# Clone the repository # Grab the repo
git clone <repository-url> Home-lab git clone <repository-url> Home-lab
cd Home-lab cd Home-lab
# Check flake configuration # Make sure everything looks good
nix flake check nix flake check
# Build configuration (test) # Test it out (won't mess with your current setup)
sudo nixos-rebuild test --flake .#congenital-optimist 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 sudo nixos-rebuild switch --flake .#congenital-optimist
``` ```
## 🏗️ Architecture Overview ## 🏗️ What We're Working With
### Machines ### The Machines
- **`congenital-optimist`** - AMD Threadripper workstation (primary development) - **`congenital-optimist`** - My main AMD Threadripper beast for development and experimentation
- **`sleeper-service`** - Intel Xeon E3-1230 V2 file server (network storage) - **`sleeper-service`** - Intel Xeon E3-1230 V2 running file server duties (the quiet workhorse)
### Technology Stack ### The Stack
- **OS**: NixOS 25.05 (Warbler) - **OS**: NixOS 25.05 (Warbler) - because reproducible builds are beautiful
- **Configuration**: Nix Flakes with modular structure - **Configuration**: Nix Flakes with modular approach - keeping things organized
- **Virtualization**: Incus, Libvirt/QEMU, Podman - **Virtualization**: Incus, Libvirt/QEMU, Podman - gotta test stuff somewhere
- **Desktop**: GNOME, Cosmic, Sway - **Desktop**: GNOME, Cosmic, Sway - variety is the spice of life
- **Storage**: ZFS with snapshots and NFS - **Storage**: ZFS with snapshots and NFS - never lose data again
- **Network**: Tailscale mesh networking - **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/ Home-lab/
@ -64,190 +68,189 @@ Home-lab/
└── secrets/ # Encrypted secrets (future) └── secrets/ # Encrypted secrets (future)
``` ```
## 🔧 Configuration Management ## 🔧 How I Manage This Chaos
### Modular Design ### Keeping Things Modular
Each aspect of the system is organized into focused modules: I've split everything into focused modules so I don't go insane:
- **Desktop Environments**: Separate modules for GNOME, Cosmic, and Sway - **Desktop Environments**: Each DE gets its own module - no more giant config files
- **Virtualization**: Independent Incus, Libvirt, and Podman configurations - **Virtualization**: Separate configs for Incus, Libvirt, and Podman - mix and match as needed
- **Development**: Modular tool configurations for different workflows - **Development**: Modular tool setups for different workflows - because context switching is real
- **Hardware**: Hardware-specific optimizations and drivers - **Hardware**: Hardware-specific tweaks and drivers - make the silicon sing
### Literate Programming ### Literate Programming (Because Documentation Matters)
User configurations use Emacs org-mode for literate programming: My user configs live in Emacs org-mode files - it's like having your documentation and code hold hands:
- Self-documenting configuration files - Configuration files that explain themselves
- Automatic tangling from `.org` to configuration files - Automatic tangling from `.org` files to actual configs
- Version-controlled documentation alongside code - Git tracks both the code and the reasoning behind it
## 🚀 Deployment Workflow ## 🚀 My Workflow
### Local Development ### Tinkering Locally
```bash ```bash
# Check configuration syntax # Check if I broke anything
nix flake check nix flake check
# Test configuration without switching # Test changes without committing to them
sudo nixos-rebuild test --flake .#<machine-name> sudo nixos-rebuild test --flake .#<machine-name>
# Build configuration # Build and see what happens
sudo nixos-rebuild build --flake .#<machine-name> sudo nixos-rebuild build --flake .#<machine-name>
# Apply configuration # Ship it!
sudo nixos-rebuild switch --flake .#<machine-name> sudo nixos-rebuild switch --flake .#<machine-name>
``` ```
### GitOps Workflow ### Git-Driven Chaos (In a Good Way)
1. **Feature Branch**: Create branch for configuration changes 1. **Feature Branch**: New idea? New branch.
2. **Local Testing**: Test changes with `nixos-rebuild test` 2. **Local Testing**: Break things safely with `nixos-rebuild test`
3. **Pull Request**: Submit PR with configuration validation 3. **Pull Request**: Show off the changes
4. **Automated Testing**: CI pipeline validates configuration 4. **Review**: Someone sanity-checks my work
5. **Review & Merge**: Code review and merge to main 5. **Deploy**: Either automated or "click the button"
6. **Deployment**: Automated or manual deployment to machines
## 🔐 Security & Secrets ## 🔐 Secrets and Security
### Current Approach ### Current Reality
- No secrets in git repository - No secrets in git (obviously)
- Manual secret management during initial setup - Manual secret juggling during setup (it's fine, really)
- ZFS encryption for sensitive data - ZFS encryption for the important stuff
### Planned Improvements ### Future Dreams
- **agenix** or **sops-nix** for encrypted secrets in git - **agenix** or **sops-nix** for proper secret management
- **age** keys for secret encryption/decryption - **age** keys for encryption magic
- **CI/CD** integration with secret management - **CI/CD** that doesn't leak passwords everywhere
## 🎯 Machine Specifications ## 🎯 The Hardware
### CongenitalOptimist (AMD Workstation) ### CongenitalOptimist (The Workstation)
- **CPU**: AMD Threadripper (details in hardware-configuration.nix) - **CPU**: AMD Threadripper (check hardware-configuration.nix for the gory details)
- **GPU**: AMD (with proper drivers and virtualization passthrough) - **GPU**: AMD (with proper drivers and GPU passthrough for VMs)
- **Storage**: ZFS pools (zpool + stuffpool) - **Storage**: ZFS pools (zpool for system, stuffpool for data hoarding)
- **Use Case**: Primary development, virtualization, desktop environments - **Role**: Main development machine, VM playground, desktop environment testing ground
- **Services**: Development tools, desktop environments, VM host - **Services**: Whatever I'm experimenting with this week
### SleeperService (Intel File Server) ### SleeperService (The Quiet One)
- **CPU**: Intel Xeon E3-1230 V2 @ 3.70GHz (4 cores, 8 threads) - **CPU**: Intel Xeon E3-1230 V2 @ 3.70GHz (4 cores, 8 threads - still plenty peppy)
- **Memory**: 16GB RAM - **Memory**: 16GB RAM (enough for file serving duties)
- **Storage**: ZFS with redundancy - **Storage**: ZFS with redundancy (because data loss is sadness)
- **Use Case**: Network storage, file sharing, backup services - **Role**: Network storage, file sharing, backup duties, monitoring the other machines
- **Services**: NFS, Samba, automated backups, monitoring - **Services**: NFS, Samba, automated backups, keeping an eye on things
## 🧪 Testing Strategy ## 🧪 Testing (The "Does It Work?" Phase)
### Automated Testing (Planned) ### Automated Testing (Someday Soon)
- **Configuration Validation**: `nix flake check` in CI - **Configuration Validation**: `nix flake check` in CI - catch dumb mistakes early
- **Build Testing**: Test builds for all machines - **Build Testing**: Test builds for all machines - make sure nothing's broken
- **Module Testing**: Individual module validation - **Module Testing**: Individual module validation - each piece should work alone
- **Integration Testing**: Full system build verification - **Integration Testing**: Full system builds - the moment of truth
### Manual Testing Checklist ### My Manual Testing Ritual
- [ ] System boots successfully - [ ] System actually boots (surprisingly important)
- [ ] Desktop environments functional - [ ] Desktop environments don't crash immediately
- [ ] Virtualization stack operational - [ ] VMs and containers start up
- [ ] Network services accessible - [ ] Network services respond
- [ ] User environment complete - [ ] Development environment loads
- [ ] Development tools working - [ ] Can actually get work done
## 📈 Monitoring & Maintenance ## 📈 Keeping Things Running
### Health Checks ### Health Checks (The Boring But Important Stuff)
- System generation switching - Generation switching (did the update work?)
- Service status monitoring - Service status monitoring (what's broken now?)
- ZFS pool health - ZFS pool health (happy disks = happy life)
- Network connectivity - Network connectivity (can I reach the internet?)
- Resource utilization - Resource usage (is something eating all my RAM?)
### Backup Strategy ### Backup Strategy (Paranoia Pays Off)
- **ZFS Snapshots**: Automatic filesystem snapshots - **ZFS Snapshots**: Automatic filesystem snapshots - time travel for your data
- **Configuration Backups**: Git repository with full history - **Configuration Backups**: Git repo with full history - every mistake preserved for posterity
- **Data Backups**: Automated backup services on SleeperService - **Data Backups**: Automated services on SleeperService - redundancy is key
- **Recovery Procedures**: Documented rollback processes - **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 ```yaml
# Planned GitHub Actions workflow # What I want GitHub Actions to do
- Syntax Check: nix flake check - Syntax Check: nix flake check # Catch the obvious stuff
- Build Test: nix build .#nixosConfigurations.<machine> - Build Test: nix build .#nixosConfigurations.<machine> # Does it actually build?
- Security Scan: Nix security auditing - Security Scan: Nix security auditing # Keep the bad guys out
- Documentation: Update system documentation - Documentation: Update system docs # Because future me will forget
``` ```
### Deployment Pipeline ### Deployment Pipeline (The Dream)
```yaml ```yaml
# Planned deployment automation # Automated deployment magic
- Staging: Deploy to test environment - Staging: Deploy to test environment # Break things safely
- Integration Tests: Automated system testing - Integration Tests: Automated system testing # Does everything still work?
- Production: Deploy to production machines - Production: Deploy to production machines # The moment of truth
- Rollback: Automatic rollback on failure - Rollback: Automatic rollback on failure # When things go wrong (they will)
``` ```
## 🤝 Contributing ## 🤝 Want to Contribute?
### Development Workflow ### How to Jump In
1. Fork/clone repository 1. Fork or clone the repo
2. Create feature branch 2. Create a feature branch for your idea
3. Make configuration changes 3. Make your changes
4. Test locally with `nixos-rebuild test` 4. Test locally with `nixos-rebuild test` (don't break my machine)
5. Submit pull request 5. Submit a pull request
6. Address review feedback 6. Chat about it in the review
7. Merge after approval 7. Merge when we're both happy
### Module Development Guidelines ### Module Development Tips
- Keep modules focused and single-purpose - Keep modules focused - one job, do it well
- Document module options and usage - Document what your module does and how to use it
- Test modules independently when possible - Test modules independently when you can
- Follow consistent naming conventions - Use consistent naming (future you will thank you)
- Include example configurations - Include example configurations for others
## 📖 Documentation ## 📖 Documentation
- **[Plan](plan.md)**: Detailed migration and development plan - **[Plan](plan.md)**: The grand vision and migration roadmap
- **[Instructions](instruction.md)**: Step-by-step setup instructions - **[Instructions](instruction.md)**: Step-by-step setup and AI agent guidance
- **[Machine Documentation](machines/)**: Per-machine documentation - **[Machine Documentation](machines/)**: Individual machine configs and notes
- **[Module Documentation](modules/)**: Module-specific documentation - **[Module Documentation](modules/)**: How each module works
- **[User Documentation](users/)**: User configuration documentation - **[User Documentation](users/)**: User-specific configuration details
## 🎯 Roadmap ## 🎯 The Journey So Far
### Phase 1: Flakes Migration ✅ ### Phase 1: Flakes Migration ✅
- [x] Convert to flake-based configuration - [x] Converted to flake-based configuration (no more channels!)
- [x] Modularize desktop environments - [x] Modularized desktop environments (sanity preserved)
- [x] Add comprehensive virtualization - [x] Added comprehensive virtualization (all the containers)
- [x] Set up GitOps foundation - [x] Set up GitOps foundation (git-driven everything)
### Phase 2: Configuration Cleanup ### Phase 2: Configuration Cleanup (In Progress)
- [ ] Optimize modular structure - [ ] Optimize modular structure (make it even better)
- [ ] Enhance documentation - [ ] Enhance documentation (explain the magic)
- [ ] Standardize module interfaces - [ ] Standardize module interfaces (consistency is king)
### Phase 3: Multi-Machine Expansion ### Phase 3: Multi-Machine Expansion (Coming Soon)
- [ ] Add SleeperService configuration - [ ] Add SleeperService configuration (wake up the sleeper)
- [ ] Implement service modules - [ ] Implement service modules (automate all the things)
- [ ] Set up network storage - [ ] Set up network storage (centralized data paradise)
### Phase 4: Automation & CI/CD ### Phase 4: Automation & CI/CD (The Dream)
- [ ] Implement automated testing - [ ] Implement automated testing (catch problems early)
- [ ] Set up deployment pipelines - [ ] Set up deployment pipelines (one-click deploys)
- [ ] Add monitoring and alerting - [ ] Add monitoring and alerting (know when things break)
### Phase 5: Advanced Features ### Phase 5: Advanced Features (Future Fun)
- [ ] Secrets management - [ ] Secrets management (proper secret handling)
- [ ] Advanced monitoring - [ ] Advanced monitoring (graphs and dashboards)
- [ ] Backup automation - [ ] Backup automation (paranoia made easy)
## 📄 License ## 📄 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 - **NixOS Community** for excellent docs and endless patience with newbie questions
- **Culture Ship Names** for inspiring machine nomenclature - **Culture Ship Names** for inspiring machine nomenclature (because why not?)
- **Emacs Community** for literate programming inspiration - **Emacs Community** for literate programming inspiration and org-mode magic
- **Home Lab Community** for sharing knowledge and experience - **Home Lab Community** for sharing knowledge, war stories, and "it works on my machine" solutions
--- ---