Geir Okkenhaug Jerstad 7a43630bc6 feat: infrastructure updates and documentation improvements

- 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.

2025-06-07 17:45:47 +00:00

8.1 KiB

Raw Blame History

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.

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

Feature Branch: Create branch for configuration changes
Local Testing: Validate changes with nixos-rebuild test
Pull Request: Submit changes for review
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

Contributing

Getting Started

Fork the repository
Create feature branch
Test changes locally with nixos-rebuild test
Submit pull request with detailed description
Respond to review feedback
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 for details.

Infrastructure designed for reliability, security, and maintainability.

8.1 KiB Raw Blame History