# 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:

```mermaid
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.