init

2026-05-08 11:38:56 -04:00
commit ef735360a3
10 changed files with 668 additions and 0 deletions
--- a/DocumentationPlan.md
+++ b/DocumentationPlan.md
@@ -0,0 +1,117 @@
+# 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.
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -0,0 +1,55 @@
+version: '3.8'
+
+services:
+  dashy:
+    image: lissy93/dashy:latest
+    container_name: dashy
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./dashy/config:/app/config
+      - ./dashy/public:/app/public
+      - ./dashy/data:/app/data
+    environment:
+      - NODE_ENV=production
+    restart: unless-stopped
+    networks:
+      - scanopy-network
+    depends_on:
+      - scanopy-server
+
+  scanopy-server:
+    image: scanopy/server:latest
+    container_name: scanopy-server
+    ports:
+      - "60072:60072"
+    volumes:
+      - ./scanopy/data:/app/data
+      - ./scanopy/config:/app/config
+    environment:
+      - SCANOPY_SERVER_PORT=60072
+      - SCANOPY_SERVER_HOST=0.0.0.0
+    restart: unless-stopped
+    networks:
+      - scanopy-network
+
+  scanopy-daemon:
+    image: scanopy/daemon:latest
+    container_name: scanopy-daemon
+    privileged: true
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./scanopy/daemon-data:/app/data
+      - ./scanopy/config:/app/config
+    environment:
+      - SCANOPY_DAEMON_SERVER_HOST=scanopy-server
+      - SCANOPY_DAEMON_SERVER_PORT=60072
+      - SCANOPY_DAEMON_SCAN_INTERVAL=3600
+      - SCANOPY_DAEMON_TARGETS=192.168.1.0/24
+    restart: unless-stopped
+    networks:
+      - scanopy-network
+
+networks:
+  scanopy-network:
+    driver: bridge
--- a/generate-mermaid.py
+++ b/generate-mermaid.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+
+"""
+Mermaid Diagram Generator for Homelab Nodes
+This script generates mermaid.js diagrams from node data
+"""
+
+import json
+import sys
+from pathlib import Path
+
+def generate_mermaid_diagram(nodes_data, output_file):
+    """Generate a mermaid diagram from node data"""
+    
+    # Start the mermaid diagram
+    mermaid_content = "graph TD\n"
+    mermaid_content += "    %% Network Infrastructure\n"
+    mermaid_content += "    subgraph \"Homelab Network\"\n"
+    
+    # Add nodes
+    for node in nodes_data.get('nodes', []):
+        node_name = node.get('name', 'Unknown')
+        ip = node.get('ip', 'Unknown')
+        node_type = node.get('type', 'Generic')
+        node_id = node_name.replace(' ', '').replace('.', '')
+        
+        mermaid_content += f"        {node_id}[{node_name}<br/>{ip}]\n"
+    
+    # Add connections
+    for connection in nodes_data.get('connections', []):
+        source = connection.get('source', '').replace(' ', '').replace('.', '')
+        target = connection.get('target', '').replace(' ', '').replace('.', '')
+        description = connection.get('description', 'Connection')
+        
+        mermaid_content += f"        {source} -->|{description}| {target}\n"
+    
+    # End the diagram
+    mermaid_content += "    end\n"
+    
+    # Write to file
+    with open(output_file, 'w') as f:
+        f.write(mermaid_content)
+    
+    print(f"Mermaid diagram generated: {output_file}")
+
+def main():
+    if len(sys.argv) != 3:
+        print("Usage: python3 generate-mermaid.py <input.json> <output.mmd>")
+        return
+    
+    input_file = sys.argv[1]
+    output_file = sys.argv[2]
+    
+    # Read input data
+    with open(input_file, 'r') as f:
+        nodes_data = json.load(f)
+    
+    # Generate diagram
+    generate_mermaid_diagram(nodes_data, output_file)
+
+if __name__ == "__main__":
+    main()
--- a/node-template.md
+++ b/node-template.md
@@ -0,0 +1,45 @@
+# Homelab Node Documentation Template
+
+## Node Information
+
+### Basic Details
+- **Node Name**: 
+- **Node Type**: 
+- **IP Address**: 
+- **Hostname**: 
+- **Location**: 
+
+### Hardware Specifications
+- **CPU**: 
+- **Memory**: 
+- **Storage**: 
+- **Network**: 
+
+### Services Running
+- **Primary Services**:
+  * 
+- **Secondary Services**:
+  * 
+
+### Network Configuration
+- **Subnet**: 
+- **Gateway**: 
+- **DNS**: 
+- **Firewall Rules**: 
+
+### Security
+- **Authentication Method**: 
+- **Encryption**: 
+- **Access Control**: 
+
+### Maintenance
+- **Last Update**: 
+- **Next Maintenance**: 
+- **Backup Schedule**: 
+
+### Dependencies
+- **Required By**: 
+- **Provides**: 
+
+### Notes
+- 
--- a/output.mmd
+++ b/output.mmd
@@ -0,0 +1,19 @@
+graph TD
+    %% Network Infrastructure
+    subgraph "Homelab Network"
+        Router[Router<br/>192.168.1.1<br/>Main Router]
+        Firewall[Firewall<br/>192.168.1.254<br/>Security Firewall]
+        NAS[NAS<br/>192.168.1.10<br/>Network Attached Storage]
+        MediaServer[MediaServer<br/>192.168.1.20<br/>Media Server]
+        HomeHub[HomeHub<br/>192.168.1.30<br/>Home Automation Hub]
+        Laptop[Laptop<br/>192.168.1.100<br/>Client Device]
+        Phone[Phone<br/>192.168.1.101<br/>Client Device]
+        Router -->|Internal| Firewall
+        Firewall -->|Internal| NAS
+        Firewall -->|Internal| MediaServer
+        Firewall -->|Internal| HomeHub
+        Firewall -->|External| Internet
+        NAS -->|Storage| MediaServer
+        MediaServer -->|Network| Laptop
+        HomeHub -->|Control| Phone
+    end
--- a/sample-nodes-data.json
+++ b/sample-nodes-data.json
@@ -0,0 +1,161 @@
+{
+  "nodes": [
+    {
+      "name": "Router",
+      "ip": "192.168.1.1",
+      "type": "Network"
+    },
+    {
+      "name": "Firewall",
+      "ip": "192.168.1.254",
+      "type": "Network"
+    },
+    {
+      "name": "NAS",
+      "ip": "192.168.1.10",
+      "type": "Storage"
+    },
+    {
+      "name": "Media Server",
+      "ip": "192.168.1.20",
+      "type": "Media"
+    },
+    {
+      "name": "Home Automation Hub",
+      "ip": "192.168.1.30",
+      "type": "Automation"
+    },
+    {
+      "name": "Laptop",
+      "ip": "192.168.1.100",
+      "type": "Client"
+    },
+    {
+      "name": "Phone",
+      "ip": "192.168.1.101",
+      "type": "Client"
+    },
+    {
+      "name": "Tablet",
+      "ip": "192.168.1.102",
+      "type": "Client"
+    },
+    {
+      "name": "Desktop",
+      "ip": "192.168.1.103",
+      "type": "Client"
+    },
+    {
+      "name": "Smart TV",
+      "ip": "192.168.1.104",
+      "type": "Media"
+    },
+    {
+      "name": "IoT Device",
+      "ip": "192.168.1.150",
+      "type": "IoT"
+    }
+  ],
+  "connections": [
+    {
+      "source": "Router",
+      "target": "Firewall",
+      "description": "Internal"
+    },
+    {
+      "source": "Firewall",
+      "target": "NAS",
+      "description": "Internal"
+    },
+    {
+      "source": "Firewall",
+      "target": "Media Server",
+      "description": "Internal"
+    },
+    {
+      "source": "Firewall",
+      "target": "Home Automation Hub",
+      "description": "Internal"
+    },
+    {
+      "source": "Firewall",
+      "target": "Internet",
+      "description": "External"
+    },
+    {
+      "source": "NAS",
+      "target": "Media Server",
+      "description": "Storage"
+    },
+    {
+      "source": "NAS",
+      "target": "Home Automation Hub",
+      "description": "Storage"
+    },
+    {
+      "source": "Media Server",
+      "target": "Smart TV",
+      "description": "Streaming"
+    },
+    {
+      "source": "Media Server",
+      "target": "Laptop",
+      "description": "Network"
+    },
+    {
+      "source": "Media Server",
+      "target": "Desktop",
+      "description": "Network"
+    },
+    {
+      "source": "Home Automation Hub",
+      "target": "IoT Device",
+      "description": "Control"
+    },
+    {
+      "source": "Home Automation Hub",
+      "target": "Laptop",
+      "description": "Control"
+    },
+    {
+      "source": "Home Automation Hub",
+      "target": "Phone",
+      "description": "Control"
+    },
+    {
+      "source": "Home Automation Hub",
+      "target": "Tablet",
+      "description": "Control"
+    },
+    {
+      "source": "Laptop",
+      "target": "Firewall",
+      "description": "Network"
+    },
+    {
+      "source": "Phone",
+      "target": "Firewall",
+      "description": "Network"
+    },
+    {
+      "source": "Tablet",
+      "target": "Firewall",
+      "description": "Network"
+    },
+    {
+      "source": "Desktop",
+      "target": "Firewall",
+      "description": "Network"
+    },
+    {
+      "source": "Smart TV",
+      "target": "Firewall",
+      "description": "Network"
+    },
+    {
+      "source": "IoT Device",
+      "target": "Firewall",
+      "description": "Network"
+    }
+  ]
+}
--- a/scanopy/README.md
+++ b/scanopy/README.md
@@ -0,0 +1,29 @@
+# Scanopy Configuration
+
+This directory contains the Docker Compose configuration for setting up Scanopy in your homelab environment.
+
+## Files
+
+- `docker-compose.yml` - Main Docker Compose configuration
+- `README.md` - This file
+
+## Setup Instructions
+
+1. Ensure Docker and Docker Compose are installed on your system
+2. Navigate to this directory: `cd /Users/noise/Documents/obsidian/homelab/scanopy`
+3. Start the services: `docker compose up -d`
+4. Access the UI at: http://<your-server-ip>:60072
+
+## Configuration
+
+The configuration includes:
+- Scanopy Server (port 60072)
+- Scanopy Daemon for network scanning
+- Bridge network for communication between services
+- Persistent data volumes
+
+## Customization
+
+To customize the scan targets, modify the `SCANOPY_DAEMON_TARGETS` environment variable in the docker-compose.yml file. By default, it scans the 192.168.1.0/24 subnet.
+
+For more advanced configuration, see the Scanopy documentation at https://scanopy.net/docs
--- a/scanopy/docker-compose.yml
+++ b/scanopy/docker-compose.yml
@@ -0,0 +1,42 @@
+version: '3.8'
+
+services:
+  scanopy-server:
+    image: scanopy/server:latest
+    container_name: scanopy-server
+    ports:
+      - "60072:60072"
+    volumes:
+      - ./data:/app/data
+      - ./config:/app/config
+    environment:
+      - SCANOPY_SERVER_PORT=60072
+      - SCANOPY_SERVER_HOST=0.0.0.0
+    restart: unless-stopped
+    networks:
+      - scanopy-network
+
+  scanopy-daemon:
+    image: scanopy/daemon:latest
+    container_name: scanopy-daemon
+    privileged: true
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./daemon-data:/app/data
+      - ./config:/app/config
+    environment:
+      - SCANOPY_DAEMON_SERVER_HOST=scanopy-server
+      - SCANOPY_DAEMON_SERVER_PORT=60072
+      - SCANOPY_DAEMON_SCAN_INTERVAL=3600
+      - SCANOPY_DAEMON_TARGETS=192.168.1.0/24
+    restart: unless-stopped
+    networks:
+      - scanopy-network
+
+volumes:
+  scanopy-data:
+  scanopy-config:
+
+networks:
+  scanopy-network:
+    driver: bridge
--- a/setup-dashy.sh
+++ b/setup-dashy.sh
@@ -0,0 +1,85 @@
+#!/bin/bash
+
+# Dashy Setup Script
+# This script automates the setup of Dashy for homelab dashboard
+
+echo "Setting up Dashy dashboard for homelab services..."
+
+# Create Dashy directory structure
+mkdir -p /opt/dashy/config
+mkdir -p /opt/dashy/public
+
+# Create sample Dashy configuration
+cat > /opt/dashy/config/config.yml << 'EOF'
+# Dashy Configuration
+title: "My Homelab Dashboard"
+subtitle: "Home Network Services"
+theme: "default"
+favicon: "/public/favicon.ico"
+backgroundImage: "/public/background.jpg"
+showStats: true
+showSearch: true
+sections:
+  - name: "Network Infrastructure"
+    items:
+      - title: "Router"
+        description: "Main network router"
+        url: "http://192.168.1.1"
+        icon: "router"
+        category: "network"
+      - title: "Firewall"
+        description: "Network security"
+        url: "http://192.168.1.254"
+        icon: "shield"
+        category: "network"
+      - title: "NAS"
+        description: "Network attached storage"
+        url: "http://192.168.1.10"
+        icon: "server"
+        category: "storage"
+  - name: "Media Services"
+    items:
+      - title: "Media Server"
+        description: "Home media streaming"
+        url: "http://192.168.1.20"
+        icon: "tv"
+        category: "media"
+      - title: "Smart TV"
+        description: "4K streaming device"
+        url: "http://192.168.1.104"
+        icon: "smart-tv"
+        category: "media"
+  - name: "Home Automation"
+    items:
+      - title: "Home Hub"
+        description: "Home automation control"
+        url: "http://192.168.1.30"
+        icon: "home"
+        category: "automation"
+      - title: "IoT Devices"
+        description: "Internet of Things"
+        url: "http://192.168.1.150"
+        icon: "devices"
+        category: "automation"
+EOF
+
+# Create systemd service file for Dashy
+cat > /etc/systemd/system/dashy.service << 'EOF'
+[Unit]
+Description=Dashy Homelab Dashboard
+After=network.target
+
+[Service]
+Type=simple
+User=dashy
+Group=dashy
+WorkingDirectory=/opt/dashy
+ExecStart=/usr/local/bin/dashy --config /opt/dashy/config/config.yml
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+echo "Dashy setup complete. You can now run: sudo systemctl start dashy"
--- a/setup-scanopy.sh
+++ b/setup-scanopy.sh
@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# Scanopy Setup Script
+# This script automates the setup of Scanopy for homelab network documentation
+
+echo "Setting up Scanopy for homelab network documentation..."
+
+# Create required directories
+mkdir -p /opt/scanopy/config
+mkdir -p /opt/scanopy/data
+
+# Create basic Scanopy configuration
+cat > /opt/scanopy/config/scanopy.yml << 'EOF'
+# Scanopy Configuration
+name: "MyHomelab"
+description: "Homelab network documentation"
+scan:
+  interval: 3600
+  targets:
+    - 192.168.1.0/24
+  protocols:
+    - snmp
+    - ssh
+    - http
+    - https
+  # Add additional configuration as needed
+export:
+  formats:
+    - mermaid
+    - svg
+    - confluence
+  output_dir: /opt/scanopy/data
+EOF
+
+# Create systemd service file for Scanopy
+cat > /etc/systemd/system/scanopy.service << 'EOF'
+[Unit]
+Description=Scanopy Network Documentation
+After=network.target
+
+[Service]
+Type=simple
+User=scanopy
+Group=scanopy
+ExecStart=/usr/local/bin/scanopy --config /opt/scanopy/config/scanopy.yml
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+echo "Scanopy setup complete. You can now run: sudo systemctl start scanopy"