117 lines
3.9 KiB
Markdown
117 lines
3.9 KiB
Markdown
|
# 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.
|