homelab-optimized/README.md

🏠 Vish's Homelab

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

🎯 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 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

# 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 for detailed deployment procedures.

Gaming Server Setup

# 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 - Complete navigation guide
• Infrastructure Overview
• Deployment Documentation
• Development Guide
• Operational Status
• Server Hardening Guide

🌐 Documentation Mirrors

Gitea Wiki (Native Integration)

• Web Interface: 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
• 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
• 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 file for details.

---

_{Built with ❤️ for learning, gaming, and self-hosting}

---

Last Updated: February 24, 2026