From ef735360a3a618d31ca39ca4adb07b76bbfd8746 Mon Sep 17 00:00:00 2001 From: noisedestroyers Date: Fri, 8 May 2026 11:38:56 -0400 Subject: [PATCH] init --- DocumentationPlan.md | 117 +++++++++++++++++++++++++++ docker-compose.yml | 55 +++++++++++++ generate-mermaid.py | 62 ++++++++++++++ node-template.md | 45 +++++++++++ output.mmd | 19 +++++ sample-nodes-data.json | 161 +++++++++++++++++++++++++++++++++++++ scanopy/README.md | 29 +++++++ scanopy/docker-compose.yml | 42 ++++++++++ setup-dashy.sh | 85 ++++++++++++++++++++ setup-scanopy.sh | 53 ++++++++++++ 10 files changed, 668 insertions(+) create mode 100644 DocumentationPlan.md create mode 100644 docker-compose.yml create mode 100755 generate-mermaid.py create mode 100644 node-template.md create mode 100644 output.mmd create mode 100644 sample-nodes-data.json create mode 100644 scanopy/README.md create mode 100644 scanopy/docker-compose.yml create mode 100755 setup-dashy.sh create mode 100755 setup-scanopy.sh diff --git a/DocumentationPlan.md b/DocumentationPlan.md new file mode 100644 index 0000000..4a428ab --- /dev/null +++ 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
192.168.1.1] + Firewall[Firewall
192.168.1.254] + NAS[NAS
192.168.1.10] + MediaServer[Media Server
192.168.1.20] + HomeHub[Home Automation Hub
192.168.1.30] + + %% Client Devices + Laptop[Laptop
192.168.1.100] + Phone[Phone
192.168.1.101] + Tablet[Tablet
192.168.1.102] + Desktop[Desktop
192.168.1.103] + SmartTV[Smart TV
192.168.1.104] + IoTDevice[IoT Device
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. \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..1878605 --- /dev/null +++ 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 \ No newline at end of file diff --git a/generate-mermaid.py b/generate-mermaid.py new file mode 100755 index 0000000..e5bbe68 --- /dev/null +++ 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}
{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 ") + 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() \ No newline at end of file diff --git a/node-template.md b/node-template.md new file mode 100644 index 0000000..9622d0a --- /dev/null +++ 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 +- \ No newline at end of file diff --git a/output.mmd b/output.mmd new file mode 100644 index 0000000..47c60a8 --- /dev/null +++ b/output.mmd @@ -0,0 +1,19 @@ +graph TD + %% Network Infrastructure + subgraph "Homelab Network" + Router[Router
192.168.1.1
Main Router] + Firewall[Firewall
192.168.1.254
Security Firewall] + NAS[NAS
192.168.1.10
Network Attached Storage] + MediaServer[MediaServer
192.168.1.20
Media Server] + HomeHub[HomeHub
192.168.1.30
Home Automation Hub] + Laptop[Laptop
192.168.1.100
Client Device] + Phone[Phone
192.168.1.101
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 diff --git a/sample-nodes-data.json b/sample-nodes-data.json new file mode 100644 index 0000000..a10ae37 --- /dev/null +++ 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" + } + ] +} \ No newline at end of file diff --git a/scanopy/README.md b/scanopy/README.md new file mode 100644 index 0000000..bd16ed1 --- /dev/null +++ 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://: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 \ No newline at end of file diff --git a/scanopy/docker-compose.yml b/scanopy/docker-compose.yml new file mode 100644 index 0000000..a35d23f --- /dev/null +++ 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 \ No newline at end of file diff --git a/setup-dashy.sh b/setup-dashy.sh new file mode 100755 index 0000000..329612a --- /dev/null +++ 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" \ No newline at end of file diff --git a/setup-scanopy.sh b/setup-scanopy.sh new file mode 100755 index 0000000..7054c20 --- /dev/null +++ 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" \ No newline at end of file