# 🏠 Vish's Homelab Documentation

Welcome to the comprehensive documentation for Vish's homelab infrastructure! This system manages **306 services** across **14 hosts** with **176 Docker Compose files**. Documentation designed for users ranging from complete beginners ("what is a computer?") to experienced HPC engineers.

> **🌐 External Access Available**  
> Many services are accessible externally via **vish.gg** and **thevish.io** domains with automatic DDNS updates every 5 minutes.

## 🚀 Quick Navigation

### 📖 Getting Started
- **🚀 Quick Start Guide** - Get up and running fast
- **🏗️ Infrastructure Overview** - System architecture and hosts
- **🌐 Network Configuration** - Tailscale, 10GbE, and connectivity
- **💻 Hardware Specifications** - Complete device inventory

### 🔧 Services Documentation
- **⭐ Popular Services** - Most commonly used services
- **📋 Complete Service Index** - All 159 individual services
- **📂 Services by Category** - Organized by function
- **🌐 External Access Services** - Publicly available services

### 🛠️ Infrastructure & Networking
- **🔌 Port Forwarding** - External access configuration
- **🔗 Tailscale Setup** - Mesh VPN with split-brain DNS
- **✈️ Travel Connectivity** - Mobile and laptop setup
- **👨‍👩‍👧‍👦 Family Network** - Separate network bridge

### 🚨 Emergency & Recovery
- **🚨 Disaster Recovery** - Router failure and network issues
- **🔐 Offline Password Access** - When Vaultwarden is down
- **🔧 Common Issues** - Frequent problems and solutions

## 🖥️ System Overview

### 🏠 Primary Infrastructure
| Host | IP Address | Services | Primary Function | External Access |
|------|------------|----------|------------------|-----------------|
| **Atlantis** | 192.168.0.200 | 45 services | Primary NAS, Jitsi Meet | Portainer, Jitsi |
| **Calypso** | 192.168.0.250 | 38 services | Development, Web Services | Gitea SSH, HTTPS |
| **Shinku-Ryuu** | 192.168.0.201 | 32 services | Gaming, Entertainment | - |
| **Guava** | 192.168.0.202 | 28 services | Monitoring, Utilities | - |
| **Concord-NUC** | 192.168.0.203 | 12 services | Family Network Bridge | - |

### 📱 Mobile & Travel Infrastructure
| Device | Type | Purpose | Tailscale IP |
|--------|------|---------|--------------|
| **MSI Prestige 13 AI Plus** | Travel Laptop | Business Travel | 100.x.x.x |
| **GL.iNet Comet GL-RM1** | KVM Router | Remote Server Access | 100.x.x.x |
| **GL.iNet Slate 7 GL-BE3600** | WiFi 7 Router | High-Speed Travel | 100.x.x.x |
| **GL.iNet Beryl AX GL-MT3000** | Compact Router | Extended Travel | 100.x.x.x |
| **GL.iNet Mango GL-MT300N-V2** | Mini Router | Emergency Backup | 100.x.x.x |
| **GL.iNet GL-S200** | IoT Gateway | Device Management | 100.x.x.x |

## 🌐 External Access Domains

### 🔌 Port Forwarded Services
| Service | Domain | Port | Purpose |
|---------|--------|------|---------|
| **🎥 Jitsi Meet** | `meet.thevish.io` | 4443 | Video conferencing |
| **📝 Gitea SSH** | `git.vish.gg` | 2222 | Git repository access |
| **🐳 Portainer** | `pw.vish.gg` | 9443 | Container management |
| **🌍 Web Services** | `vish.gg` | 443/80 | Main website |

### 🌐 Cloudflare Proxied Services
- **📅 Calendar**: `https://cal.vish.gg`
- **💬 Matrix Chat**: `https://matrix.thevish.io`
- **📓 Joplin Notes**: `https://joplin.thevish.io`
- **🔗 Reddit Alt**: `https://reddit.vish.gg`
- **🌍 Main Sites**: `https://www.vish.gg`, `https://www.thevish.io`

### 🔄 DDNS Configuration
- **Update Frequency**: Every 5 minutes
- **Domains**: vish.gg and thevish.io
- **Services**: 4 DDNS updaters (proxied/unproxied for each domain)
- **Records**: IPv4 (A) and IPv6 (AAAA) automatic updates

## 📊 Service Categories & Counts

### 🎬 Media & Entertainment (45 services)
- **Streaming Servers**: Plex, Jellyfin, Navidrome, Immich
- **Download Management**: Sonarr, Radarr, Lidarr, Readarr, Whisparr, Bazarr
- **Media Tools**: Tautulli, MeTube, Podgrab, Calibre-Web
- **Gaming**: Satisfactory Server, LinuxGSM servers

### 🔧 Development & DevOps (38 services)
- **Version Control**: Gitea (external SSH), Git repositories
- **Container Management**: Portainer (external access), Docker registries
- **CI/CD**: Automated builds, deployment pipelines
- **Development Tools**: Code servers, API endpoints

### 📊 Monitoring & Analytics (28 services)
- **Metrics Collection**: Grafana, Prometheus, Node Exporter
- **Uptime Monitoring**: Uptime Kuma, health checks
- **Network Monitoring**: SNMP Exporter, Speedtest Exporter
- **System Monitoring**: cAdvisor, Blackbox Exporter

### 🌐 Web Services & Proxies (32 services)
- **Reverse Proxies**: Nginx, Nginx Proxy Manager
- **Web Applications**: Various hosted web services
- **APIs & Backends**: Service APIs, database frontends
- **Static Sites**: Documentation, personal websites

### 💬 Communication & Collaboration (18 services)
- **Video Conferencing**: Jitsi Meet (external access via meet.thevish.io)
- **Chat Platforms**: Matrix Synapse, Element Web, Mastodon
- **Email Services**: Roundcube, ProtonMail Bridge
- **Team Collaboration**: Mattermost, communication tools

### 🏠 Home Automation & IoT (15 services)
- **Smart Home Control**: Home Assistant, Matter Server
- **IoT Device Management**: Device monitoring and control
- **Automation Scripts**: Workflows and triggers
- **Sensor Data**: Collection and processing

### 🔒 Security & Authentication (12 services)
- **Password Management**: Vaultwarden (with offline backup)
- **VPN Services**: WireGuard Easy, Tailscale mesh
- **Network Security**: Pi-hole, AdGuard Home
- **Authentication**: SSO services, security tools

### 🤖 AI & Machine Learning (8 services)
- **Language Models**: Ollama, OpenWebUI
- **AI Tools**: Various AI-powered applications
- **Machine Learning**: Model serving and inference
- **Data Processing**: AI-enhanced workflows

## 🌍 Network Architecture

### 🔗 Tailscale Mesh VPN
- **Network Name**: `tail.vish.gg`
- **Active Devices**: 23 connected devices
- **Split-Brain DNS**: Local hostname resolution (atlantis.tail.vish.gg)
- **Exit Nodes**: Available for secure internet routing
- **Magic DNS**: Automatic device discovery and naming

### 🚀 10 Gigabit Ethernet Infrastructure
- **Switch**: TP-Link TL-SX1008 (8-port 10GbE unmanaged)
- **Connected Hosts**: Atlantis, Calypso, Shinku-Ryuu, Guava
- **Bandwidth**: Full 10Gbps between connected systems
- **Use Cases**: Large file transfers, media streaming, backups

### 🌐 External Connectivity
- **Router**: TP-Link Archer BE800 v1.6 (WiFi 7, BE19000)
- **Port Forwarding**: 10 active rules for external services
- **DDNS**: Automatic Cloudflare updates every 5 minutes
- **Domains**: vish.gg and thevish.io with Cloudflare proxy protection
- **IPv6**: Full dual-stack support with AAAA records

## 📱 Mobile & Travel Infrastructure

### ✈️ Travel Connectivity Suite
- **Primary Laptop**: MSI Prestige 13 AI Plus (Intel Core Ultra 7 258V)
- **KVM Access**: GL.iNet Comet GL-RM1 for remote server management
- **WiFi 7 Router**: GL.iNet Slate 7 GL-BE3600 for high-speed connectivity
- **Compact Router**: GL.iNet Beryl AX GL-MT3000 for extended travel
- **Emergency Backup**: GL.iNet Mango GL-MT300N-V2 mini router
- **IoT Gateway**: GL.iNet GL-S200 for device management

### 🔒 Travel Security Features
- **VPN Tunneling**: All traffic routed through Atlantis exit node
- **Remote Mounting**: Secure file access via SSHFS
- **Disposable Data**: Minimal local storage, cloud-first approach
- **Encrypted Communications**: All connections via Tailscale mesh

### 📱 Mobile Device Support
- **Platforms**: iOS, Android, macOS, Linux, iPadOS, Debian, Rocky Linux
- **Tailscale Integration**: All devices connected to mesh network
- **Family Devices**: Separate network integration via Concord-NUC
- **Guest Access**: Isolated network access for visitors

## 👨‍👩‍👧‍👦 Family Network Integration

### 🌉 Network Bridge Setup
- **Bridge Device**: Concord-NUC (Intel NUC13ANHi7)
- **Family Network**: 2 Gbps down / 400 Mbps up
- **Homelab Network**: 20 Gbps up/down fiber
- **Services**: Plex streaming, Immich photo sync, Synology file sharing

### 🎬 Shared Services
- **Media Streaming**: Plex server accessible from family network
- **Photo Management**: Immich for family photo backup and sharing
- **File Sharing**: Synology NAS accessible for document sharing
- **Bandwidth Optimization**: QoS and traffic shaping

## 🚨 Disaster Recovery & Emergency Procedures

### 🔧 Router Failure Recovery
- **Backup Configuration**: TP-Link settings exported monthly
- **Manual Reconfiguration**: Step-by-step port forwarding restoration
- **Network Isolation**: Tailscale mesh continues independent operation
- **Service Priority**: Critical services restoration order documented

### 🔐 Offline Password Access
- **Vaultwarden Backup**: Local database exports and encrypted storage
- **Emergency Access**: Offline password retrieval procedures
- **Mobile Backup**: Cached credentials on mobile devices
- **Recovery Methods**: Multiple access paths documented

### 📱 Travel Emergency Procedures
- **Connectivity Loss**: Multiple router fallback options
- **Device Failure**: Remote server access via KVM
- **Data Recovery**: Cloud backup and sync procedures
- **Communication**: Alternative contact methods

## 🛠️ Getting Started by Experience Level

### For Complete Beginners 🟢
- **Start Here**: Quick Start Guide
- **Learn Basics**: What is Docker, containers, networking
- **First Services**: Set up Plex or Jellyfin for media streaming
- **Remote Access**: Configure Tailscale for secure connections
- **Popular Apps**: Explore Popular Services

### For Intermediate Users 🟡
- **Service Exploration**: Browse Complete Service Index
- **External Access**: Set up Port Forwarding
- **Travel Setup**: Configure Mobile Connectivity
- **Monitoring**: Implement Grafana and Prometheus dashboards
- **Automation**: Basic Docker Compose customizations

### For Advanced Users 🔴
- **Architecture Review**: Study Hardware Architecture
- **Disaster Recovery**: Implement Emergency Procedures
- **Network Engineering**: Advanced VLANs, routing, and security
- **Automation**: Infrastructure as Code with Ansible
- **Scaling**: Multi-host deployments and load balancing

### For HPC Engineers 🔴
- **Performance Optimization**: 10GbE network utilization
- **Container Orchestration**: Kubernetes cluster deployment
- **Monitoring Stack**: Advanced metrics and alerting
- **Security Hardening**: Enterprise-grade security implementations
- **Integration Patterns**: Complex service interdependencies

## 📚 Documentation Organization

### 📖 Documentation Types
- **🟢 Beginner Guides** - Step-by-step with explanations
- **🟡 Configuration Guides** - Setup and customization details
- **🔴 Advanced Topics** - Complex deployments and troubleshooting
- **🔧 Reference Docs** - Technical specifications and APIs
- **🚨 Emergency Guides** - Crisis management and recovery

### 🔍 How to Find Information
- **By Service**: Use Service Index for specific applications
- **By Category**: Browse Service Categories for related services
- **By Function**: Check Popular Services for common use cases
- **By Problem**: Search Common Issues for solutions
- **By Access Method**: Review External Access for remote services

## 🔄 Recent Major Updates

### November 2025 Updates
- **✅ Port Forwarding Documentation** - Complete external access configuration
- **✅ Domain Integration** - All vish.gg and thevish.io domains documented
- **✅ Travel Infrastructure** - GL.iNet router suite and MSI laptop setup
- **✅ Family Network Integration** - Concord-NUC bridge configuration
- **✅ Disaster Recovery** - Router failure and offline access procedures
- **✅ Individual Service Docs** - All 159 services fully documented
- **✅ DDNS Configuration** - Automatic Cloudflare updates every 5 minutes

### Infrastructure Milestones
- **306 Total Services** across 14 hosts
- **159 Individual Service Guides** with full documentation
- **23 Tailscale Devices** in active mesh network
- **10 External Port Forwards** for public service access
- **12 Domain Names** with automatic DDNS updates
- **6 Travel Routers** for complete mobile connectivity

## 🤝 Contributing & Feedback

### 📝 Documentation Improvements
- Found an error? Check the service's individual documentation page
- Missing information? Review the troubleshooting sections
- Want to add content? Follow the established documentation patterns
- Need help? Check the emergency procedures and common issues

### 🔄 Keeping Documentation Current
- Service configurations are auto-generated from Docker Compose files
- Infrastructure changes are documented within 24 hours
- External access information is verified monthly
- Hardware specifications are updated with each change

## 📊 Quick Statistics

> **📈 Homelab Statistics**
> - **Total Services**: 306 across all hosts
> - **Documented Services**: 159 individual guides
> - **External Domains**: 12 with automatic DDNS
> - **Network Devices**: 23 in Tailscale mesh
> - **Port Forwards**: 10 active external access rules
> - **Travel Routers**: 6 GL.iNet devices for mobility
> - **Documentation Pages**: 200+ comprehensive guides
> - **Last Updated**: 2025-11-17

## 🔗 External Links & Resources

- **Git Repository**: `https://git.vish.gg/Vish/homelab`
- **Jitsi Meet**: `https://meet.thevish.io`
- **Portainer**: `https://pw.vish.gg:9443`
- **Main Website**: `https://vish.gg`
- **Tailscale Network**: `tail.vish.gg`

---

*Last Updated: 2025-11-17*  
*Infrastructure: 306 services, 159 documented, 14 hosts, 23 Tailscale devices*  
*External Access: 12 domains, 10 port forwards, 5-minute DDNS updates*  
*Documentation Status: Complete with comprehensive guides for all experience levels*