feat: initial NixOS home lab infrastructure setup
- Add modular flake-based NixOS configuration - Implement GitOps foundation with CI/CD pipeline - Create comprehensive documentation and branching strategy - Add modular desktop environments (GNOME, Cosmic, Sway) - Configure virtualization stack (Incus, Libvirt, Podman) - Set up development tools and hardware-specific modules - Establish user configuration with literate programming support This commit represents the completion of Phase 1: Flakes Migration with modular configuration, virtualization, and GitOps foundation.
This commit is contained in:
Geir Okkenhaug Jerstad
commit
f30013723e
43 changed files with 4220 additions and 0 deletions
254
README.md
Normal file
254
README.md
Normal file
|
|
@ -0,0 +1,254 @@
|
|||
# 🏠 NixOS Home Lab Infrastructure
|
||||
|
||||
[](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.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url> Home-lab
|
||||
cd Home-lab
|
||||
|
||||
# Check flake configuration
|
||||
nix flake check
|
||||
|
||||
# Build configuration (test)
|
||||
sudo nixos-rebuild test --flake .#congenital-optimist
|
||||
|
||||
# Apply configuration (permanent)
|
||||
sudo nixos-rebuild switch --flake .#congenital-optimist
|
||||
```
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
### Machines
|
||||
- **`congenital-optimist`** - AMD Threadripper workstation (primary development)
|
||||
- **`sleeper-service`** - Intel Xeon E3-1230 V2 file server (network storage)
|
||||
|
||||
### 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
|
||||
|
||||
## 📁 Repository Structure
|
||||
|
||||
```
|
||||
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)
|
||||
```
|
||||
|
||||
## 🔧 Configuration Management
|
||||
|
||||
### Modular Design
|
||||
Each aspect of the system is organized into focused modules:
|
||||
|
||||
- **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
|
||||
|
||||
### 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
|
||||
|
||||
## 🚀 Deployment Workflow
|
||||
|
||||
### Local Development
|
||||
```bash
|
||||
# Check configuration syntax
|
||||
nix flake check
|
||||
|
||||
# Test configuration without switching
|
||||
sudo nixos-rebuild test --flake .#<machine-name>
|
||||
|
||||
# Build configuration
|
||||
sudo nixos-rebuild build --flake .#<machine-name>
|
||||
|
||||
# Apply configuration
|
||||
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
|
||||
|
||||
## 🔐 Security & Secrets
|
||||
|
||||
### Current Approach
|
||||
- No secrets in git repository
|
||||
- Manual secret management during initial setup
|
||||
- ZFS encryption for sensitive data
|
||||
|
||||
### Planned Improvements
|
||||
- **agenix** or **sops-nix** for encrypted secrets in git
|
||||
- **age** keys for secret encryption/decryption
|
||||
- **CI/CD** integration with secret management
|
||||
|
||||
## 🎯 Machine Specifications
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
## 🧪 Testing Strategy
|
||||
|
||||
### 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
|
||||
|
||||
### Manual Testing Checklist
|
||||
- [ ] System boots successfully
|
||||
- [ ] Desktop environments functional
|
||||
- [ ] Virtualization stack operational
|
||||
- [ ] Network services accessible
|
||||
- [ ] User environment complete
|
||||
- [ ] Development tools working
|
||||
|
||||
## 📈 Monitoring & Maintenance
|
||||
|
||||
### Health Checks
|
||||
- System generation switching
|
||||
- Service status monitoring
|
||||
- ZFS pool health
|
||||
- Network connectivity
|
||||
- Resource utilization
|
||||
|
||||
### 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
|
||||
|
||||
## 🔄 CI/CD Pipeline (Planned)
|
||||
|
||||
### Validation Pipeline
|
||||
```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
|
||||
```
|
||||
|
||||
### Deployment Pipeline
|
||||
```yaml
|
||||
# Planned deployment automation
|
||||
- Staging: Deploy to test environment
|
||||
- Integration Tests: Automated system testing
|
||||
- Production: Deploy to production machines
|
||||
- Rollback: Automatic rollback on failure
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
## 📖 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
|
||||
|
||||
## 🎯 Roadmap
|
||||
|
||||
### Phase 1: Flakes Migration ✅
|
||||
- [x] Convert to flake-based configuration
|
||||
- [x] Modularize desktop environments
|
||||
- [x] Add comprehensive virtualization
|
||||
- [x] Set up GitOps foundation
|
||||
|
||||
### Phase 2: Configuration Cleanup
|
||||
- [ ] Optimize modular structure
|
||||
- [ ] Enhance documentation
|
||||
- [ ] Standardize module interfaces
|
||||
|
||||
### Phase 3: Multi-Machine Expansion
|
||||
- [ ] Add SleeperService configuration
|
||||
- [ ] Implement service modules
|
||||
- [ ] Set up network storage
|
||||
|
||||
### Phase 4: Automation & CI/CD
|
||||
- [ ] Implement automated testing
|
||||
- [ ] Set up deployment pipelines
|
||||
- [ ] Add monitoring and alerting
|
||||
|
||||
### Phase 5: Advanced Features
|
||||
- [ ] Secrets management
|
||||
- [ ] Advanced monitoring
|
||||
- [ ] Backup automation
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- **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
|
||||
|
||||
---
|
||||
|
||||
*"The ship had decided to call itself the Arbitrary, presumably for much the same reason."*
|
||||
Loading…
Add table
Add a link
Reference in a new issue