7a43630bc6
- Update Forgejo service configuration on grey-area - Refine reverse-proxy network configuration - Add README_new.md with enhanced documentation structure - Update instruction.md with latest workflow guidelines - Enhance plan.md with additional deployment considerations - Complete PR template restructuring for professional tone These changes improve service reliability and documentation clarity while maintaining infrastructure consistency across all machines.
215 lines
8.1 KiB
Markdown
215 lines
8.1 KiB
Markdown
# NixOS Home Lab Infrastructure
|
|
|
|
[](https://nixos.org/)
|
|
[](https://nixos.wiki/wiki/Flakes)
|
|
[](LICENSE)
|
|
|
|
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.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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](plan.md)**: Detailed implementation roadmap
|
|
- **[Development Workflow](DEVELOPMENT_WORKFLOW.md)**: Contribution guidelines
|
|
- **[Branching Strategy](BRANCHING_STRATEGY.md)**: Git workflow and conventions
|
|
- **[AI Instructions](instruction.md)**: Agent guidance for system management
|
|
|
|
## Contributing
|
|
|
|
### Getting Started
|
|
1. Fork the repository
|
|
2. Create feature branch
|
|
3. Test changes locally with `nixos-rebuild test`
|
|
4. Submit pull request with detailed description
|
|
5. Respond to review feedback
|
|
6. Deploy after approval
|
|
|
|
### Module Development
|
|
- **Focused Scope**: One responsibility per module
|
|
- **Configuration Options**: Parameterize for flexibility
|
|
- **Documentation**: Explain purpose and usage
|
|
- **Examples**: Provide usage examples
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details.
|
|
|
|
---
|
|
|
|
*Infrastructure designed for reliability, security, and maintainability.*
|