homelab/DocumentationPlan.md

Homelab Documentation Plan

Overview

This document outlines the recommended approach for documenting homelab nodes and creating network diagrams for infrastructure management.

Recommended Tools

1. Scanopy

• Purpose: Network documentation that automatically scans and updates infrastructure
• Features:
  • Automatic network discovery without per-device agents
  • Four views: L2 (Physical), L3 (Logical), Workloads, Application dependencies
  • 230+ service definitions
  • Docker & SNMP integration
  • Scheduled rescans
  • Multi-user + RBAC support
  • Export as SVG, Mermaid, or Confluence
  • Self-hosted (AGPL-3.0) or Commercial license available
• URL: https://github.com/scanopy/scanopy

2. Dashy

• Purpose: Personal dashboard for organizing self-hosted services
• Features:
  • Real-time status monitoring for services
  • Multiple pages support
  • Widgets for dynamic content
  • Theming with custom CSS
  • Authentication support
  • Icon packs (Font-Awesome, favicon auto-fetching, emoji, etc.)
  • Search functionality
  • Supports Docker and bare-metal deployment
• URL: https://github.com/Lissy93/dashy

Implementation Scripts

Scanopy Setup Script

• File: setup-scanopy.sh
• Purpose: Automate setting up Scanopy with default configuration for homelab network discovery
• Usage: ./setup-scanopy.sh

Dashy Setup Script

• File: setup-dashy.sh
• Purpose: Automate setting up Dashy dashboard for homelab services
• Usage: ./setup-dashy.sh

Node Documentation Template

• File: node-template.md
• Purpose: Template for documenting individual nodes in the homelab with consistent structure

Mermaid Diagram Generator

• File: generate-mermaid.py
• Purpose: Generate mermaid diagrams from node data
• Usage: python3 generate-mermaid.py nodes-data.json output.mmd

Network Diagram

Sample Homelab Topology

The following diagram shows typical homelab node interactions:

graph TD
    %% Network Infrastructure
    subgraph "Homelab Network"
        Router[Router<br/>192.168.1.1]
        Firewall[Firewall<br/>192.168.1.254]
        NAS[NAS<br/>192.168.1.10]
        MediaServer[Media Server<br/>192.168.1.20]
        HomeHub[Home Automation Hub<br/>192.168.1.30]
        
        %% Client Devices
        Laptop[Laptop<br/>192.168.1.100]
        Phone[Phone<br/>192.168.1.101]
        Tablet[Tablet<br/>192.168.1.102]
        Desktop[Desktop<br/>192.168.1.103]
        SmartTV[Smart TV<br/>192.168.1.104]
        IoTDevice[IoT Device<br/>192.168.1.150]
        
        %% Connections
        Router -->|Internal| Firewall
        Firewall -->|Internal| NAS
        Firewall -->|Internal| MediaServer
        Firewall -->|Internal| HomeHub
        
        Firewall -->|External| Internet[Internet]
        
        NAS -->|Storage| MediaServer
        NAS -->|Storage| HomeHub
        
        MediaServer -->|Streaming| SmartTV
        MediaServer -->|Network| Laptop
        MediaServer -->|Network| Desktop
        
        HomeHub -->|Control| IoTDevice
        HomeHub -->|Control| Laptop
        HomeHub -->|Control| Phone
        HomeHub -->|Control| Tablet
        
        Laptop -->|Network| Firewall
        Phone -->|Network| Firewall
        Tablet -->|Network| Firewall
        Desktop -->|Network| Firewall
        SmartTV -->|Network| Firewall
        IoTDevice -->|Network| Firewall
    end

Implementation Strategy

1. Use Scanopy to automatically document network infrastructure and update it regularly
2. Use Dashy as the main dashboard to organize and access all services
3. Create node summary documents for each component with details including:
   • IP addresses
   • Services running
   • Roles in the network
   • Maintenance requirements

This approach will provide both automated infrastructure documentation and a user-friendly dashboard for accessing your homelab services.