# 🏠 Vish's Homelab

<div align="center">

[![Infrastructure Status](https://img.shields.io/badge/Infrastructure-Online-green?style=flat-square)](https://git.vish.gg/Vish/homelab)
[![Servers](https://img.shields.io/badge/Servers-5-blue?style=flat-square)](#server-inventory)
[![Services](https://img.shields.io/badge/Services-100+-orange?style=flat-square)](#service-categories)
[![Security](https://img.shields.io/badge/Security-Hardened-red?style=flat-square)](#security)

*A comprehensive self-hosted infrastructure for media, development, gaming, and productivity services*

</div>

## 🎯 Overview

This repository contains the complete infrastructure-as-code setup for my homelab, including:

- **Multi-server Docker orchestration** with Portainer GitOps
- **Gaming servers** (Minecraft, Garry's Mod, PufferPanel)
- **Media management** (Plex, Jellyfin, *arr stack)
- **Development tools** (Gitea, CI/CD, monitoring)
- **Communication platforms** (Stoat chat deployment configs)
- **Security hardening** and monitoring
- **Automated backups** and disaster recovery

## 🖥️ Server Inventory

| Server | Type | Status | CPUs | RAM | Containers | GitOps Stacks | Location |
|--------|------|--------|------|-----|------------|---------------|----------|
| **Atlantis** | Synology DS1823xs+ | 🟢 Online | 8 | 31.3 GB | 50+ | 18 Active | Primary NAS |
| **Concord NUC** | Intel NUC6i3SYB | 🟢 Online | 4 | 15.5 GB | 17 | GitOps Ready | Edge Computing |
| **Calypso** | Synology DS723+ | 🟢 Online | 4 | 31.3 GB | 46 | GitOps Ready | Secondary NAS |
| **Raspberry Pi 5** | ARM64 | 🟢 Online | 4 | 15.8 GB | 4 | GitOps Ready | IoT/Edge |
| **Homelab VM** | Proxmox VM | 🟢 Online | 4 | 28.7 GB | 23 | GitOps Ready | Cloud Services |

### Gaming Server (VPS)
- **Provider**: Contabo VPS
- **Specs**: 8 vCPU, 32GB RAM, 400GB NVMe
- **Services**: Minecraft, Garry's Mod, PufferPanel, Stoat Chat
- **Security**: Hardened with fail2ban, UFW, SSH keys only

## 📊 Monitoring & Observability

The homelab uses a comprehensive monitoring stack with multiple deployment options:

### Production Monitoring (GitOps)
- **Location**: `hosts/vms/homelab-vm/monitoring.yaml`
- **Access**: https://gf.vish.gg (Authentik SSO)
- **Status**: ✅ **ACTIVE** - Primary monitoring stack
- **Features**: Full infrastructure monitoring, SNMP for Synology devices

### Development Stack (Fixed Dashboards)
- **Location**: `docker/monitoring/`
- **Access**: http://localhost:3300 (admin/admin)
- **Status**: 🔧 **DEVELOPMENT** - Testing and dashboard fixes
- **Features**: All datasource UIDs fixed, working template variables

### Key Metrics Monitored
- **System Metrics**: CPU, Memory, Disk, Network across all servers
- **Container Metrics**: Docker container health and resource usage
- **Storage Metrics**: Synology NAS storage, RAID status, disk temperatures
- **Network Metrics**: Tailscale VPN connectivity, bandwidth usage
- **Service Health**: Uptime monitoring for all critical services

📋 **Documentation**: See [MONITORING_ARCHITECTURE.md](docs/infrastructure/MONITORING_ARCHITECTURE.md) for detailed setup information.

## 🎮 Gaming Services

### Active Game Servers
- **Minecraft Server** (Port 25565)
  - Version: Latest
  - Plugins: Custom modpack
  - Management: PufferPanel

- **Garry's Mod Server** (Port 27015)
  - Gamemode: Sandbox/DarkRP
  - Addons: Custom collection
  - Management: PufferPanel

- **PufferPanel** (Port 8080)
  - Web-based game server management
  - Multi-user support
  - Automated backups

### Communication
- **Stoat Chat** (st.vish.gg)
  - Self-hosted Revolt instance
  - Voice/video calling via LiveKit
  - Custom branding and features

## 🛡️ Security

### Server Hardening (Recently Implemented)
- **SSH Security**: Key-based authentication only, backup access on port 2222
- **Firewall Protection**: UFW with rate limiting for SSH/HTTP
- **Intrusion Prevention**: Fail2ban protecting SSH and web services
- **Web Server Security**: Nginx with modern TLS and security headers
- **Automatic Updates**: Security patches auto-installed
- **Emergency Access**: Backup SSH access when Tailscale is down

### Network Security
- **VPN**: Tailscale mesh network for secure access
- **DNS Filtering**: AdGuard Home on multiple nodes
- **SSL/TLS**: Let's Encrypt certificates with auto-renewal
- **Access Control**: Authentik SSO for service authentication

### Monitoring & Alerting
- **Uptime Monitoring**: Custom health checks
- **Log Aggregation**: Centralized logging with alerts
- **Security Monitoring**: Automated threat detection
- **Backup Verification**: Automated backup testing

## 📊 Service Categories

### Media & Entertainment
- **Plex Media Server** - Primary media streaming
- **Jellyfin** - Alternative media server
- **Sonarr/Radarr/Lidarr** - Media acquisition automation
- **Jellyseerr** - Media request management
- **Tautulli** - Plex analytics and monitoring

### Development & DevOps
- **Gitea** - Self-hosted Git repositories
- **Portainer** - Docker container management
- **Grafana** - Metrics visualization
- **Prometheus** - Metrics collection
- **Watchtower** - Automated container updates

### Productivity & Storage
- **Immich** - Photo management and backup
- **PaperlessNGX** - Document management
- **Joplin** - Note-taking and synchronization
- **Syncthing** - File synchronization
- **Nextcloud** - Cloud storage and collaboration

### Network & Infrastructure
- **AdGuard Home** - DNS filtering and ad blocking
- **Nginx Proxy Manager** - Reverse proxy management
- **Authentik** - Single sign-on (SSO) provider
- **Tailscale** - Mesh VPN networking

## 🚀 GitOps Deployment

This homelab uses **GitOps methodology** with **Portainer Enterprise Edition** for automated deployment and management.

### Current GitOps Status
- **Management Platform**: Portainer EE v2.33.7 (https://192.168.0.200:9443)
- **Active Deployments**: 18 compose stacks on Atlantis
- **Total Containers**: 50+ containers across infrastructure
- **Deployment Method**: Automatic sync from Git repository

### Key GitOps Features
- **Declarative Configuration**: All services defined in Git
- **Automatic Deployment**: Changes trigger immediate updates
- **Multi-Host Orchestration**: Services distributed across infrastructure
- **Version Control**: Full deployment history and rollback capability

### Quick Deployment Guide
```bash
# Clone the repository
git clone https://git.vish.gg/Vish/homelab.git
cd homelab

# Add new service configuration
cat > Atlantis/new-service.yaml << 'EOF'
version: '3.8'
services:
  new-service:
    image: example/service:latest
    container_name: new-service
    ports:
      - "8080:8080"
    restart: unless-stopped
EOF

# Commit and deploy via GitOps
git add Atlantis/new-service.yaml
git commit -m "Add new service deployment"
git push origin main
# Service automatically deploys via Portainer GitOps
```

📋 **Comprehensive Guide**: See [GitOps Comprehensive Guide](docs/admin/GITOPS_COMPREHENSIVE_GUIDE.md) for detailed deployment procedures.

### Gaming Server Setup
```bash
# Access the gaming server
ssh -p 22 root@YOUR_SERVER_IP  # Primary access
ssh -p 2222 root@YOUR_SERVER_IP  # Backup access

# Check server status
/root/scripts/security-check.sh
/root/scripts/backup-access-manager.sh status
```

## 📁 Repository Structure

```
homelab/
├── hosts/                    # Host-specific configurations (canonical)
│   ├── physical/            # Physical servers (NUC, etc.)
│   ├── synology/            # Synology NAS (atlantis, calypso, setillo)
│   ├── vms/                 # Virtual machines (homelab-vm, seattle, etc.)
│   ├── truenas/             # TrueNAS configurations
│   └── edge/                # Edge devices (Raspberry Pi, MSI laptop)
├── Atlantis/                 # GitOps: Portainer stacks for Atlantis NAS
├── Calypso/                  # GitOps: Portainer stacks for Calypso NAS
├── concord_nuc/              # GitOps: Portainer stacks for Concord NUC
├── homelab_vm/               # GitOps: Portainer stacks for Homelab VM
├── raspberry-pi-5-vish/      # GitOps: Portainer stacks for RPi5
├── deployments/              # Standalone service deployment configs
│   ├── mastodon/            # Mastodon social instance
│   ├── matrix/              # Matrix homeserver
│   ├── mattermost/          # Mattermost chat
│   └── fluxer-seattle/      # Fluxer deployment
├── ansible/                  # Automation playbooks
│   └── homelab/             # Primary Ansible configuration
├── docs/                     # Documentation
│   ├── getting-started/     # Beginner guides
│   ├── infrastructure/      # Network, storage, hosts
│   ├── services/            # Per-service documentation
│   ├── admin/               # GitOps, deployment, monitoring guides
│   ├── runbooks/            # Operational runbooks
│   ├── troubleshooting/     # Incident guides & recovery
│   ├── security/            # Hardening documentation
│   ├── hardware/            # Hardware inventory & specs
│   └── diagrams/            # Architecture diagrams
├── scripts/                  # Management & utility scripts
├── alerting/                 # Alertmanager & notification bridges
├── grafana/                  # Grafana dashboard JSON exports
├── prometheus/               # Prometheus config & alert rules
├── common/                   # Shared container configurations
├── archive/                  # Deprecated configs & old docs
├── backup.sh                 # Stoatchat backup script
└── restore.sh                # Stoatchat restore script
```

## 🔧 Management Tools

### Server Hardening Tools
- **Security Monitor**: `/root/scripts/security-check.sh`
- **Backup Access Manager**: `/root/scripts/backup-access-manager.sh`
- **Firewall Management**: UFW with custom rules

### Infrastructure Management
- **GitOps Deployment**: Portainer with Git repository sync
- **Backup Scripts**: `./backup.sh` and `./restore.sh`
- **Health Monitoring**: Automated status checks

## 📚 Documentation

### 📖 Repository Documentation
- [**Master Documentation Index**](docs/INDEX.md) - Complete navigation guide
- [Infrastructure Overview](docs/infrastructure/INFRASTRUCTURE_OVERVIEW.md)
- [Deployment Documentation](docs/admin/DEPLOYMENT_DOCUMENTATION.md)
- [Development Guide](docs/admin/DEVELOPMENT.md)
- [Operational Status](docs/admin/OPERATIONAL_STATUS.md)
- [Server Hardening Guide](docs/security/SERVER_HARDENING.md)

### 🌐 Documentation Mirrors

#### Gitea Wiki (Native Integration)
- **Web Interface**: [https://git.vish.gg/Vish/homelab/wiki](https://git.vish.gg/Vish/homelab/wiki)
- **Features**: Native Git integration, version control, unified authentication
- **Sync**: Automated mirroring via API
- **Access**: Same authentication as repository

#### DokuWiki Mirror (External) ✅ **OPERATIONAL**
- **Web Interface**: [http://atlantis.vish.local:8399](http://atlantis.vish.local:8399/doku.php?id=homelab:start)
- **Features**: Advanced wiki features, collaborative editing, search
- **Status**: 160 pages synchronized (Feb 14, 2026)
- **Sync**: Manual sync via `scripts/sync-dokuwiki-simple.sh`
- **Access**: Available on LAN and Tailscale network

## 🔄 Backup & Disaster Recovery

### Automated Backups
- **Schedule**: Daily incremental, weekly full
- **Storage**: Multiple locations (local + cloud)
- **Verification**: Automated backup testing
- **Retention**: 30 days incremental, 12 months full

### Disaster Recovery
- **RTO**: < 4 hours for critical services
- **RPO**: < 24 hours data loss maximum
- **Procedures**: Documented recovery playbooks
- **Testing**: Monthly DR drills

## 🤝 Contributing

This is a personal homelab setup, but feel free to:
- Use configurations as reference
- Submit issues for bugs or improvements
- Suggest optimizations or security enhancements

## 📞 Support & Contact

- **Repository**: [git.vish.gg/Vish/homelab](https://git.vish.gg/Vish/homelab)
- **Issues**: Use the repository issue tracker
- **Chat**: Available on Stoat chat (st.vish.gg)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

<div align="center">
<sub>Built with ❤️ for learning, gaming, and self-hosting</sub>
</div>

---
**Last Updated**: February 24, 2026