geir/home-lab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update README to reflect current AI-enhanced infrastructure status

Browse source 
Major updates to accurately represent the project's evolution from basic NixOS
home lab to sophisticated AI-integrated infrastructure:

- Add AI components: Task Master AI, Ollama inference, MCP protocol
- Update architecture to show 4/4 machines fully operational
- Include service stack: Forgejo Git hosting, Jellyfin media, RAG system
- Reflect 31 completed infrastructure automation tasks
- Add local AI processing with complete data privacy
- Update technology stack with Guile Scheme automation tools
- Include external services accessible via git.geokkjer.eu

The README now accurately represents this as an advanced AI-enhanced
home lab with intelligent task management and privacy-focused automation.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Geir Okkenhaug Jerstad 2025-06-27 18:58:11 +02:00
parent 6306a05d64
commit 8db85e0479
1 changed files with 106 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

148
README.md
View file

@ -8,11 +8,11 @@
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
</div>
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.
AI-integrated NixOS home lab infrastructure with Guile Scheme automation tools. Features declarative system configuration, Task Master AI integration, local Ollama processing, and MCP protocol implementation for intelligent infrastructure management across 4 fully operational machines.
# Vibe DevSecOpsing with claude-sonnet 4 and github-copilot
## AI-Enhanced DevSecOps with Local Intelligence
A project about handling pets. If you want to handle sheep, look elsewhere :-)
Advanced home lab featuring AI-powered task management, Guile Scheme automation, and local Ollama inference for complete data privacy and intelligent infrastructure operations.
## Quick Start
@ -33,21 +33,34 @@ sudo nixos-rebuild switch --flake .#<machine-name>
## Architecture Overview
### Machine Types
### AI-Enhanced Infrastructure
- **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
#### Core AI Components
- **Task Master AI** - Intelligent task management with local Ollama inference
- **MCP Protocol Server** - Guile Scheme-based Model Context Protocol implementation
- **Local AI Models** - Qwen3:4b, DeepSeek-R1:1.5b, Gemma3:4b running on grey-area
- **RAG System** - Document retrieval and processing for enhanced AI context
- **VS Code Integration** - AI-powered development environment with GitHub Copilot
### Machine Infrastructure (All Operational)
- **congenital-optimist** - AI-enhanced development workstation with multiple desktop environments
- **sleeper-service** - ZFS file server with 903GB media library and NFS services
- **grey-area** - AI processing hub with Ollama, containerized services, and Forgejo Git hosting
- **reverse-proxy** - External gateway with SSL termination, service routing (git.geokkjer.eu)
### Technology Stack
- **Base OS**: <img src="assets/nixos_logo.svg" alt="NixOS" width="20" height="25" style="vertical-align: middle; margin-right: 5px;">NixOS 25.05 with Nix Flakes
- **Configuration**: Modular, declarative system configuration
- **AI Integration**: Task Master AI with local Ollama inference (Qwen, DeepSeek, Gemma models)
- **Automation**: Guile Scheme-based infrastructure tools with MCP protocol
- **Development**: VS Code extension with GitHub Copilot integration
- **Virtualization**: Incus containers, Libvirt/QEMU VMs, Podman containers
- **Desktop**: GNOME, Cosmic, Sway window managers
- **Storage**: ZFS with snapshots, automated mounting, NFS network storage
- **Storage**: ZFS with snapshots, automated mounting, NFS network storage (903GB media library)
- **Network**: Tailscale mesh VPN with centralized hostname resolution
- **Services**: Forgejo Git hosting, Jellyfin media server, RAG document processing
## Project Structure
@ -57,32 +70,40 @@ Modular configuration organized for scalability and maintainability:
Home-lab/
├── flake.nix # Main flake configuration
├── flake.lock # Dependency lock file
├── .taskmaster/ # Task Master AI configuration and tasks
│ ├── tasks/ # Task database and generated files
│ ├── config.json # AI model configuration
│ └── docs/ # PRD and documentation
├── machines/ # Machine-specific configurations
│ ├── workstation/ # Development machine config
│ ├── file-server/ # NFS storage server
│ ├── app-server/ # Containerized services
│ └── reverse-proxy/ # External gateway
│ ├── congenital-optimist/ # AI-enhanced workstation
│ ├── sleeper-service/ # File server with 903GB media
│ ├── grey-area/ # AI processing and application server
│ └── reverse-proxy/ # External gateway (git.geokkjer.eu)
├── modules/ # Reusable NixOS modules
│ ├── common/ # Base system configuration
│ ├── ai/ # Claude Code and AI tools
│ ├── desktop/ # Desktop environment modules
│ ├── development/ # Development tools
│ ├── services/ # Service configurations
│ ├── services/ # Service configurations (Ollama, RAG, etc.)
│ ├── users/ # User management
│ └── virtualization/ # Container and VM setup
├── packages/ # Custom packages and tools
└── research/ # Documentation and analysis
├── research/ # AI integration research and analysis
├── documentation/ # Comprehensive project documentation
└── scripts/ # Automation and utility scripts
```
## Configuration Philosophy
<img src="assets/nixos_logo.svg" alt="NixOS" width="30" height="37" style="float: left; margin-right: 10px; margin-top: 5px;">
### Modular Design
### AI-Enhanced 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
- **Intelligent Orchestration**: Task Master AI manages complex deployment workflows
- **Local AI Processing**: Complete data privacy with Ollama inference on local hardware
- **Composable Modules**: Mix and match modules per machine requirements with AI assistance
- **Testable Infrastructure**: Individual modules validated independently with automated testing
- **Living Documentation**: AI-generated documentation that evolves with the infrastructure
### User Management Strategy
@ -132,13 +153,21 @@ sudo nixos-rebuild switch --flake .#<machine>
## Service Architecture
### Core Services
### Core Services - Fully Operational Stack
- **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
#### AI & Automation Services
- **Task Master AI**: Intelligent task management with 31 completed infrastructure tasks
- **Ollama AI Processing**: Local inference on grey-area (Qwen3, DeepSeek, Gemma models)
- **MCP Server**: Guile Scheme-based Model Context Protocol implementation
- **RAG System**: Document retrieval and processing for enhanced AI context
#### Infrastructure Services
- **Forgejo Git Hosting**: Self-hosted at git.geokkjer.eu with external SSH access (port 1337)
- **Jellyfin Media Server**: Streaming with transcoding, accessing 903GB library via NFS
- **File Storage**: NFS network storage with ZFS snapshots (sleeper-service)
- **Reverse Proxy**: Nginx with Let's Encrypt SSL and external access
- **Container Platform**: Podman-based services across grey-area
- **Additional Services**: Calibre-web (e-books), audiobook server, web applications
### Service Discovery
@ -195,37 +224,72 @@ sudo nixos-rebuild switch --flake .#<machine>
## Deployment Status
### Infrastructure Maturity
### Infrastructure Maturity - FULLY OPERATIONAL 🚀
- ✅ **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
- ✅ **AI-Integrated Management**: Task Master AI with 31 completed tasks, Guile Scheme MCP server
- ✅ **Multi-machine Configuration**: 4 machines fully deployed and operational
- ✅ **Local AI Processing**: Ollama inference on grey-area with multiple models
- ✅ **Service Integration**: Forgejo Git hosting (git.geokkjer.eu), Jellyfin media server, file storage
- ✅ **Network Mesh**: Secure Tailscale VPN with centralized hostname resolution
- ✅ **External Access**: Public services with SSL termination and SSH forwarding
- ✅ **Development Tools**: VS Code extension with MCP integration for AI-assisted development
- ✅ **Centralized Management**: Single repository with intelligent task orchestration
### 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
- **AI-Powered Development**: Task Master AI with local Ollama inference for intelligent task management
- **Advanced Automation**: Guile Scheme-based tools replacing traditional Bash scripts
- **MCP Integration**: Model Context Protocol server for AI tool communication
- **Development Environment**: Full IDE setup with AI-enhanced workflows and multiple desktop options
- **File Services**: Network storage with 903GB media library (38 movies, 29 TV series, 79 audiobooks)
- **Git Hosting**: Self-hosted Forgejo with external access via git.geokkjer.eu
- **Media Streaming**: Jellyfin with transcoding, Calibre-web, audiobook server
- **Container Platform**: Podman-based containerized services across grey-area
- **RAG System**: Document retrieval and processing for enhanced AI context
## 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
- **[Migration Plan](plan.md)**: Detailed implementation roadmap with current operational status
- **[Task Master Integration](research/claude-task-master-ai-integration-status.md)**: AI-powered task management setup
- **[Ollama Research](research/taskmaster-ai.md)**: Local AI processing with privacy-first approach
- **[Guile Development](research/guile-configuration-strategy.md)**: Scheme-based automation tools
- **[RAG System](research/RAG-MCP-TaskMaster-Domain-Model.md)**: Document processing and retrieval
- **[Development Workflow](documentation/DEVELOPMENT_WORKFLOW.md)**: AI-enhanced contribution guidelines
- **[AI Instructions](instruction.md)**: Agent guidance for intelligent system management
## License
MIT License - see [LICENSE](LICENSE) for details.
## Current Status Summary
### ✅ Fully Operational AI-Enhanced Home Lab (December 2024 - June 2025)
#### Infrastructure Achievement
- **4/4 machines deployed** and fully operational with complete service integration
- **Task Master AI** managing infrastructure with 31 completed automation tasks
- **Local AI processing** with Ollama models providing complete data privacy
- **External services** accessible via git.geokkjer.eu with SSL termination
#### AI Integration Milestones
- **MCP Protocol Server** implemented in Guile Scheme for AI tool communication
- **VS Code Integration** with GitHub Copilot and local AI models
- **RAG System** for intelligent document processing and retrieval
- **Intelligent Task Management** with automated project breakdown and tracking
#### Service Stack Status
- **Git Hosting**: Forgejo operational at git.geokkjer.eu
- **Media Services**: Jellyfin, Calibre-web, audiobook server with 903GB library
- **AI Processing**: Ollama inference with Qwen3, DeepSeek, Gemma models
- **Network Mesh**: Tailscale VPN connecting all infrastructure securely
- **Storage**: ZFS with NFS exports serving content across the network
This represents a **comprehensive evolution** from traditional infrastructure management to **AI-enhanced, privacy-focused automation** while maintaining full control over data and processing.
---
<div align="center">
<img src="assets/nixos_logo.svg" alt="NixOS Logo" width="40" height="50">
<br>
<em>Infrastructure designed for reliability, security, and maintainability.</em>
<em>AI-enhanced infrastructure designed for intelligence, privacy, and continuous evolution.</em>
</div>