Updated README
Some checks are pending
🏠 Home Lab CI/CD Pipeline / 🔍 Validate Configuration (push) Waiting to run
🏠 Home Lab CI/CD Pipeline / 🔨 Build Configurations (push) Blocked by required conditions
🏠 Home Lab CI/CD Pipeline / 🔒 Security Audit (push) Blocked by required conditions
🏠 Home Lab CI/CD Pipeline / 📚 Documentation & Modules (push) Blocked by required conditions
🏠 Home Lab CI/CD Pipeline / 🔄 Update Dependencies (push) Waiting to run
🏠 Home Lab CI/CD Pipeline / 🚀 Deploy Configuration (push) Blocked by required conditions
🏠 Home Lab CI/CD Pipeline / 📢 Notify Results (push) Blocked by required conditions
Some checks are pending
🏠 Home Lab CI/CD Pipeline / 🔍 Validate Configuration (push) Waiting to run
🏠 Home Lab CI/CD Pipeline / 🔨 Build Configurations (push) Blocked by required conditions
🏠 Home Lab CI/CD Pipeline / 🔒 Security Audit (push) Blocked by required conditions
🏠 Home Lab CI/CD Pipeline / 📚 Documentation & Modules (push) Blocked by required conditions
🏠 Home Lab CI/CD Pipeline / 🔄 Update Dependencies (push) Waiting to run
🏠 Home Lab CI/CD Pipeline / 🚀 Deploy Configuration (push) Blocked by required conditions
🏠 Home Lab CI/CD Pipeline / 📢 Notify Results (push) Blocked by required conditions
This commit is contained in:
Geir Okkenhaug Jerstad
parent
5b3a058e7e
commit
61a50dad27
1 changed files with 154 additions and 151 deletions
305
README.md
305
README.md
|
|
@ -1,43 +1,47 @@
|
|||
# 🏠 NixOS Home Lab Infrastructure
|
||||
# 🏠 NixOS Home Lab Adventures
|
||||
|
||||
[](https://nixos.org/)
|
||||
[](https://nixos.wiki/wiki/Flakes)
|
||||
[](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 <repository-url> 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 .#<machine-name>
|
||||
|
||||
# Build configuration
|
||||
# Build and see what happens
|
||||
sudo nixos-rebuild build --flake .#<machine-name>
|
||||
|
||||
# Apply configuration
|
||||
# Ship it!
|
||||
sudo nixos-rebuild switch --flake .#<machine-name>
|
||||
```
|
||||
|
||||
### 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.<machine>
|
||||
- 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.<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
|
||||
### 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
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue