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.

Vibe DevSecOpsing with claude-sonnet 4 and github-copilot

A project about handling pets. If you want to handle sheep, look elsewhere :-)

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 development environment with desktop environments
• File Server - ZFS storage with NFS services and media management
• Application Server - Containerized services (Git hosting, media server, web applications)
• 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

Project Structure

Modular configuration organized for scalability and maintainability:

Home-lab/
├── flake.nix              # Main flake configuration
├── flake.lock             # Dependency lock file
├── machines/              # Machine-specific configurations
│   ├── workstation/       # Development machine config
│   ├── file-server/       # NFS storage server
│   ├── app-server/        # Containerized services
│   └── reverse-proxy/     # External gateway
├── modules/               # Reusable NixOS modules
│   ├── common/           # Base system configuration
│   ├── desktop/          # Desktop environment modules
│   ├── development/      # Development tools
│   ├── services/         # Service configurations
│   ├── users/            # User management
│   └── virtualization/   # Container and VM setup
├── packages/             # Custom packages and tools
└── research/             # Documentation and analysis

Configuration Philosophy

Modular Design

• Single Responsibility: Each module handles one aspect of system configuration
• Composable: Modules can be mixed and matched per machine requirements
• Testable: Individual modules can be validated independently
• Documented: Clear documentation for module purpose and configuration

User Management Strategy

• Role-based Users: Separate users for desktop vs server administration
• Centralized Configuration: Consistent user setup across all machines
• Security Focus: SSH key management and privilege separation
• Literate Dotfiles: Org-mode documentation for complex configurations

Network Architecture

• Mesh VPN: Tailscale for secure inter-machine communication
• Service Discovery: Centralized hostname resolution
• Firewall Management: Service-specific port configuration
• External Access: Reverse proxy with SSL termination

Development Workflow

Local Testing

# Validate configuration syntax
nix flake check

# Build without applying changes
nix build .#nixosConfigurations.<machine>.config.system.build.toplevel

# Test configuration (temporary)
sudo nixos-rebuild test --flake .#<machine>

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

Git Workflow

1. Feature Branch: Create branch for configuration changes
2. Local Testing: Validate changes with nixos-rebuild test
3. Pull Request: Submit changes for review
4. Deploy: Apply configuration to target machines

Remote Deployment

• SSH-based: Remote deployment via secure shell
• Atomic Updates: Complete success or automatic rollback
• Health Checks: Service validation after deployment
• Centralized Management: Single repository for all infrastructure

Service Architecture

Core Services

• Git Hosting: Self-hosted Git with CI/CD capabilities
• Media Server: Streaming with transcoding support
• File Storage: NFS network storage with ZFS snapshots
• Web Gateway: Reverse proxy with SSL and external access
• Container Platform: Podman for containerized applications

Service Discovery

• Internal DNS: Tailscale for mesh network resolution
• External DNS: Public domain with SSL certificates
• Service Mesh: Inter-service communication via secure network
• Load Balancing: Traffic distribution and failover

Data Management

• ZFS Storage: Copy-on-write filesystem with snapshots
• Network Shares: NFS for cross-machine file access
• Backup Strategy: Automated snapshots and external backup
• Data Integrity: Checksums and redundancy

Security Model

Network Security

• VPN Mesh: All inter-machine traffic via Tailscale
• Firewall Rules: Service-specific port restrictions
• SSH Hardening: Key-based authentication only
• Fail2ban: Automated intrusion prevention

User Security

• Role Separation: Administrative vs daily-use accounts
• Key Management: Centralized SSH key distribution
• Privilege Escalation: Sudo access only where needed
• Service Accounts: Dedicated accounts for automated services

Infrastructure Security

• Configuration as Code: All changes tracked in version control
• Atomic Deployments: Rollback capability for failed changes
• Secret Management: Encrypted secrets with controlled access
• Security Updates: Regular dependency updates

Testing Strategy

Automated Testing

• Syntax Validation: Nix flake syntax checking
• Build Testing: Configuration build verification
• Module Testing: Individual component validation
• Integration Testing: Full system deployment tests

Manual Testing

• Boot Validation: System startup verification
• Service Health: Application functionality checks
• Network Connectivity: Inter-service communication tests
• User Environment: Desktop and development tool validation

Deployment Status

Infrastructure Maturity

• ✅ Multi-machine Configuration: 4 machines deployed
• ✅ Service Integration: Git hosting, media server, file storage
• ✅ Network Mesh: Secure VPN with service discovery
• ✅ External Access: Public services with SSL termination
• ✅ Centralized Management: Single repository for all infrastructure

Current Capabilities

• Development Environment: Full IDE setup with multiple desktop options
• File Services: Network storage with 900GB+ media library
• Git Hosting: Self-hosted with external access
• Media Streaming: Movie and TV series streaming with transcoding
• Container Platform: Podman-based containerized services

Documentation

• Migration Plan: Detailed implementation roadmap
• Development Workflow: Contribution guidelines
• Branching Strategy: Git workflow and conventions
• AI Instructions: Agent guidance for system management

License

MIT License - see LICENSE for details.

---

Infrastructure designed for reliability, security, and maintainability.