309 lines
14 KiB
Markdown
309 lines
14 KiB
Markdown
# 🏠 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* |