# 🏠 Vish's Homelab Documentation

Welcome to the comprehensive documentation for Vish's homelab infrastructure! This documentation is designed to serve users ranging from complete beginners ("what is a computer?") to experienced HPC engineers.

## 📚 Documentation Structure

### 🚀 Getting Started
- **[01-What-is-a-Homelab](01-What-is-a-Homelab.md)** - Complete beginner's introduction
- **[02-Quick-Start-Guide](02-Quick-Start-Guide.md)** - Get up and running fast
- **[03-Architecture-Overview](03-Architecture-Overview.md)** - Understanding the infrastructure
- **[04-Prerequisites](04-Prerequisites.md)** - What you need to know/have

### 🏗️ Infrastructure
- **[10-Host-Overview](10-Host-Overview.md)** - All physical and virtual machines
- **[11-Network-Architecture](11-Network-Architecture.md)** - How everything connects
- **[12-Storage-Systems](12-Storage-Systems.md)** - Data storage and management
- **[13-Security-Model](13-Security-Model.md)** - How the lab is secured

### 🐳 Services
- **[19-Individual-Service-Docs](19-Individual-Service-Docs.md)** - **NEW!** Detailed guides for all 159 services
- **[20-Service-Categories](20-Service-Categories.md)** - Services organized by function
- **[21-Service-Index](21-Service-Index.md)** - Complete alphabetical list
- **[22-Popular-Services](22-Popular-Services.md)** - Most commonly used services
- **[23-Service-Dependencies](23-Service-Dependencies.md)** - How services interact

### 🔧 Administration
- **[30-Deployment-Guide](30-Deployment-Guide.md)** - How to deploy new services
- **[31-Monitoring-Alerting](31-Monitoring-Alerting.md)** - Keeping track of everything
- **[32-Backup-Recovery](32-Backup-Recovery.md)** - Protecting your data
- **[33-Maintenance-Tasks](33-Maintenance-Tasks.md)** - Regular upkeep

### 🚨 Troubleshooting
- **[40-Common-Issues](40-Common-Issues.md)** - Frequent problems and solutions
- **[41-Diagnostic-Tools](41-Diagnostic-Tools.md)** - How to investigate problems
- **[42-Emergency-Procedures](42-Emergency-Procedures.md)** - When things go very wrong
- **[43-Performance-Tuning](43-Performance-Tuning.md)** - Optimizing your setup

### 🎓 Advanced Topics
- **[50-Ansible-Automation](50-Ansible-Automation.md)** - Infrastructure as Code
- **[51-Custom-Configurations](51-Custom-Configurations.md)** - Tailoring to your needs
- **[52-Integration-Patterns](52-Integration-Patterns.md)** - Connecting services together
- **[53-Scaling-Strategies](53-Scaling-Strategies.md)** - Growing your homelab

## 🏠 Infrastructure Overview

This homelab consists of **159 fully documented services** running across **13 different hosts**:

### 📊 Host Summary
| Host Type | Count | Primary Purpose |
|-----------|-------|-----------------|
| **Synology NAS** | 3 | Storage, Media, Core Services |
| **Intel NUC** | 1 | Edge Computing, IoT Hub |
| **Proxmox VMs** | 3 | Isolated Workloads, Testing |
| **Raspberry Pi** | 2 | Lightweight Services, Sensors |
| **Remote VMs** | 2 | External Services, Backup |
| **Physical Hosts** | 2 | High-Performance Computing |

### 🎯 Service Categories
| Category | Services | Examples |
|----------|----------|----------|
| **Media & Entertainment** | 25+ | Plex, Jellyfin, Immich, Arr Suite |
| **Development & DevOps** | 20+ | GitLab, Gitea, Portainer, Dozzle |
| **Productivity** | 15+ | Paperless-NGX, Firefly III, Calibre |
| **Communication** | 10+ | Matrix, Mastodon, Jitsi, Mattermost |
| **Monitoring** | 15+ | Grafana, Prometheus, Uptime Kuma |
| **Security & Privacy** | 10+ | Vaultwarden, Wireguard, Pi-hole |
| **AI & Machine Learning** | 5+ | Ollama, LlamaGPT, Whisper |
| **Gaming** | 8+ | Minecraft, Factorio, Satisfactory |

## 🎯 Quick Navigation

### For Beginners
1. Start with [01-What-is-a-Homelab](01-What-is-a-Homelab.md)
2. Review [04-Prerequisites](04-Prerequisites.md)
3. Follow the [02-Quick-Start-Guide](02-Quick-Start-Guide.md)
4. Explore [22-Popular-Services](22-Popular-Services.md)

### For Intermediate Users
1. Review [03-Architecture-Overview](03-Architecture-Overview.md)
2. Check [20-Service-Categories](20-Service-Categories.md)
3. Learn about [30-Deployment-Guide](30-Deployment-Guide.md)
4. Set up [31-Monitoring-Alerting](31-Monitoring-Alerting.md)

### For Advanced Users
1. Dive into [50-Ansible-Automation](50-Ansible-Automation.md)
2. Explore [51-Custom-Configurations](51-Custom-Configurations.md)
3. Review [52-Integration-Patterns](52-Integration-Patterns.md)
4. Consider [53-Scaling-Strategies](53-Scaling-Strategies.md)

## 🆘 Need Help?

- **Common Issues**: Check [40-Common-Issues](40-Common-Issues.md)
- **Service Not Working**: See [41-Diagnostic-Tools](41-Diagnostic-Tools.md)
- **Performance Problems**: Review [43-Performance-Tuning](43-Performance-Tuning.md)
- **Emergency**: Follow [42-Emergency-Procedures](42-Emergency-Procedures.md)

## 📝 Contributing

This documentation is a living document. If you find errors, have suggestions, or want to add content:

1. Check the [21-Service-Index](21-Service-Index.md) for existing documentation
2. Review [30-Deployment-Guide](30-Deployment-Guide.md) for deployment patterns
3. Follow the documentation style guide in each section

## 🏷️ Conventions Used

- **🟢 Beginner-Friendly**: Suitable for newcomers
- **🟡 Intermediate**: Requires basic Docker/Linux knowledge  
- **🔴 Advanced**: Requires significant technical expertise
- **⚠️ Caution**: Potentially destructive operations
- **💡 Tip**: Helpful hints and best practices
- **🔧 Technical**: Deep technical details

---

*Last Updated: November 2024*  
*Infrastructure: 159 fully documented services across 13 hosts*  
*Documentation Status: Complete with individual service guides*

## 📋 Document Organization for Joplin

This documentation is organized with numbered prefixes for easy sorting in Joplin:

- **00-09**: Index and overview documents
- **10-19**: Infrastructure and architecture
- **20-29**: Services and applications
- **30-39**: Administration and deployment
- **40-49**: Troubleshooting and maintenance
- **50-59**: Advanced topics and automation

Each document is self-contained but cross-references related topics for easy navigation.