Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
docs(rack): document the rack canvas for users
Pouzor2af6f728d793
diff --git a/FEATURES.md b/FEATURES.mdindex 96d90dd..8a92aaf 100644--- a/FEATURES.md+++ b/FEATURES.md@@ -16,20 +16,21 @@ Here's what Homelable can do. One line on what each feature is, then how to swit2. [Groups & Nesting](#2-groups--nesting)3. [Text Annotations](#3-text-annotations)4. [Multiple Canvases](#4-multiple-canvases)-5. [Customize Style](#5-customize-style)-6. [Floor Plan](#6-floor-plan-)-7. [Network Scanner (IP import)](#7-network-scanner-ip-import-)-8. [Zigbee Import](#8-zigbee-import-)-9. [Z-Wave Import](#9-z-wave-import-)-10. [Proxmox VE Import](#10-proxmox-ve-import-)-11. [Device Inventory](#11-device-inventory-)-12. [Live Status Monitoring](#12-live-status-monitoring-)-13. [Export (PNG / SVG / YAML / Markdown)](#13-export)-14. [Live View (read-only public canvas)](#14-live-view-)-15. [Gethomepage Widget](#15-gethomepage-widget-)-16. [MCP Server (AI integration)](#16-mcp-server-)-17. [Settings & Shortcuts](#17-settings--shortcuts)-18. [Authentication (Local / OpenID Connect)](#18-authentication-local--openid-connect-)+5. [Rack Canvas](#5-rack-canvas)+6. [Customize Style](#6-customize-style)+7. [Floor Plan](#7-floor-plan-)+8. [Network Scanner (IP import)](#8-network-scanner-ip-import-)+9. [Zigbee Import](#9-zigbee-import-)+10. [Z-Wave Import](#10-z-wave-import-)+11. [Proxmox VE Import](#11-proxmox-ve-import-)+12. [Device Inventory](#12-device-inventory-)+13. [Live Status Monitoring](#13-live-status-monitoring-)+14. [Export (PNG / SVG / YAML / Markdown)](#14-export)+15. [Live View (read-only public canvas)](#15-live-view-)+16. [Gethomepage Widget](#16-gethomepage-widget-)+17. [MCP Server (AI integration)](#17-mcp-server-)+18. [Settings & Shortcuts](#18-settings--shortcuts)+19. [Authentication (Local / OpenID Connect)](#19-authentication-local--openid-connect-)---@@ -74,7 +75,26 @@ Here's what Homelable can do. One line on what each feature is, then how to swit----## 5. Customize Style+## 5. Rack Canvas++**What:** The physical side of the lab, as its own kind of canvas: racks, the gear mounted in them, and the patch cables between their ports. Where a diagram says what talks to what, a rack says what sits in which U, and which switch port the uplink lands on.++**Use:**+- **Canvas switcher** → **New Canvas** → Kind **Rack**. A canvas cannot change kind afterwards.+- **Add Rack** in the header drops a rack; double-click its frame for U height, 19"/10" width, numbering direction, colours and the enclosed/open look.+- **+ Device** in the sidebar mounts something: an entry from your **Device Inventory** 🔒, a **new device** (which joins the inventory tagged *Rack devices*), or a rack-only **accessory** (blank, shelf, cable manager). Double-click a plate to edit it, and **Unmount** to take it out — the device itself stays in the inventory.+- Gear occupies a U range and part of a 12-column width grid, so half- and third-width machines share a U. A drop snaps to the nearest free slot, an impossible one previews red, and growing a device relocates it to the nearest slot that fits.+- The **Faceplate** field opens a visual catalog — servers, switches, routers, patch panels, UPS and PDUs, desktop NAS towers, shelves and blanks — drawn as vector artwork that scales with the rack and follows your theme.+- **Patch**: drag from one port to another (or click both in turn) to cable them, across racks if you need to. Click a cable to select it, then **Delete** or **Unplug**. A header select controls whether cables show on hover, always, or not at all.+- **Status**: pin a mount's colour, or set **Check device** 🔒 so it follows the status check already configured on the matching diagram node.+- **Import links** 🔒 derives patches, once per canvas, from the physical links already drawn on your diagrams.+- Saving is explicit — **Save Rack** — like any other canvas.++> **Full documentation:** [docs/rack-canvas.md](./docs/rack-canvas.md)++---++## 6. Customize Style**What:** Repaint the whole thing with a preset theme, or roll your own node and edge colors.@@ -85,7 +105,7 @@ Here's what Homelable can do. One line on what each feature is, then how to swit----## 6. Floor Plan 🔒+## 7. Floor Plan 🔒**What:** Put a background image (a house plan, an office layout, a rack diagram) behind a canvas and lay your devices out on top of it.@@ -96,7 +116,7 @@ Here's what Homelable can do. One line on what each feature is, then how to swit----## 7. Network Scanner (IP import) 🔒+## 8. Network Scanner (IP import) 🔒**What:** Point `nmap` at your network, fingerprint the services it finds, and turn hosts into nodes.@@ -116,7 +136,7 @@ SCANNER_HTTP_VERIFY_TLS=false----## 8. Zigbee Import 🔒+## 9. Zigbee Import 🔒**What:** Pull your **Zigbee2MQTT** topology in over MQTT and drop every device on the canvas as a typed node.@@ -129,7 +149,7 @@ Nodes come in as `zigbee_coordinator` / `zigbee_router` / `zigbee_enddevice`. Th----## 9. Z-Wave Import 🔒+## 10. Z-Wave Import 🔒**What:** Same idea for **Z-Wave JS UI**, over the same MQTT broker.@@ -142,7 +162,7 @@ Nodes: `zwave_coordinator` / `zwave_router` / `zwave_enddevice`. The hierarchy c----## 10. Proxmox VE Import 🔒+## 11. Proxmox VE Import 🔒**What:** Pull your **Proxmox VE** inventory (hosts, VMs, LXC) in over the Proxmox REST API — typed, named nodes with run state and hardware specs. Optional scheduled **auto-sync**; guest IPs already found by a scan are merged, not duplicated.@@ -156,7 +176,7 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.----## 11. Device Inventory 🔒+## 12. Device Inventory 🔒**What:** The holding pen for everything found by a scan or import that isn't on the canvas yet, plus a separate **Hidden Devices** list.@@ -167,7 +187,7 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.----## 12. Live Status Monitoring 🔒+## 13. Live Status Monitoring 🔒**What:** Keeps checking each node and shows its status (🟢 online / 🔴 offline / ⚫ unknown) right on the canvas.@@ -188,7 +208,7 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.----## 13. Export+## 14. Export**What:** Get your canvas out as a picture or as structured data.@@ -200,7 +220,7 @@ Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge.----## 14. Live View 🔒+## 15. Live View 🔒**What:** A read-only, no-login snapshot of a canvas you can share on your LAN. Off by default.@@ -212,7 +232,7 @@ Pan and zoom only, no editing. Click a node with an IP and it opens in a new tab----## 15. Gethomepage Widget 🔒+## 16. Gethomepage Widget 🔒**What:** A tiny JSON stats endpoint for [gethomepage](https://gethomepage.dev)'s `customapi` widget. Off by default.@@ -224,7 +244,7 @@ Widget snippet lives in the [README](./README.md#gethomepage-widget-read-only-st----## 16. MCP Server 🔒+## 17. MCP Server 🔒**What:** A [Model Context Protocol](https://modelcontextprotocol.io) server so an MCP client (Claude Code, Claude Desktop, Open WebUI…) can read and change your topology. Optional, runs as its own service.@@ -242,7 +262,7 @@ The AI can list nodes/edges/canvas/pending/scans, add/update/delete nodes and ed----## 17. Settings & Shortcuts+## 18. Settings & Shortcuts**What:** App config and keyboard shortcuts.@@ -253,7 +273,7 @@ The AI can list nodes/edges/canvas/pending/scans, add/update/delete nodes and ed----## 18. Authentication (Local / OpenID Connect) 🔒+## 19. Authentication (Local / OpenID Connect) 🔒**What:** Homelable protects the app behind a login. Two exclusive modes, set once in `.env` with `AUTH_MODE`:- **`local`** (default) — a single username + bcrypt-hashed password. Nothing changes for existing installs.diff --git a/README.md b/README.mdindex 2c41740..752f363 100644--- a/README.md+++ b/README.md@@ -21,6 +21,7 @@<a href="#screenshots">Screenshots</a> ·<a href="#features">Features</a> ·<a href="#installation">Installation</a> ·+ <a href="#rack-canvas">Rack Canvas</a> ·<a href="#network-scanner">Network Scanner</a> ·<a href="#zigbee2mqtt-import">Zigbee / Z-Wave</a> ·<a href="#proxmox-ve-import">Proxmox</a> ·@@ -56,7 +57,7 @@ If you are running <img width="22" height="22" align="top" alt="New_Home_Assist## Features-From one-click **network scans** and **Proxmox / Zigbee / Z-Wave** imports to **live status monitoring**, floor plans, multi-canvas layouts and an **MCP server** for AI assistants — Homelable maps and watches your whole homelab.+From one-click **network scans** and **Proxmox / Zigbee / Z-Wave** imports to **live status monitoring**, floor plans, **rack canvases** with port-to-port patching, multi-canvas layouts and an **MCP server** for AI assistants — Homelable maps and watches your whole homelab.Every feature, with how to turn it on and use it, is described in **[FEATURES.md](./FEATURES.md)**.@@ -68,6 +69,24 @@ Docker, Proxmox LXC, build from source, configuration, and development setup are---+## Rack Canvas++Next to the network diagram, Homelable draws the **physical** side of your lab: racks, the gear mounted in them, and the patch cables between their ports. It is a canvas kind of its own — create it from the canvas switcher, **New Canvas → Kind → Rack**.++### Usage++1. **Add Rack** in the header drops a rack; double-click its frame to set U height, 19"/10" width, numbering direction and colours+2. **+ Device** in the sidebar mounts something — an entry from your Device Inventory, a new device (which joins the inventory), or an accessory (blank, shelf, cable manager)+3. Pick a **faceplate** from the visual catalog: servers, switches, routers, patch panels, UPS and PDUs, desktop NAS towers, shelves and blanks+4. Click **Patch**, then drag from one port to another to cable them — across racks if you need to. Click a cable and press Delete to unplug it+5. **Save Rack** when you're happy; nothing is written behind your back++Gear sits in a U range and part of a 12-column width grid, so half- and third-width machines share a U; a drop snaps to the nearest free slot. A mount can follow the status check of its matching diagram node, and **Import links** derives patches from the links already drawn on your diagrams.++> **Full documentation:** [docs/rack-canvas.md](./docs/rack-canvas.md)++---+## Network ScannerThe scanner runs `nmap -sV --open` on your configured CIDR ranges and populates a **Pending Devices** queue. From the sidebar you can then approve (adds a node to the canvas), hide, or ignore each discovered device.diff --git a/docs/rack-canvas.md b/docs/rack-canvas.mdnew file mode 100644index 0000000..4df92e6--- /dev/null+++ b/docs/rack-canvas.md@@ -0,0 +1,205 @@+# Rack Canvas++A rack canvas is the **physical** counterpart to the network diagram: real racks,+the gear mounted in them, and the patch cables between their ports. It is a+canvas kind of its own — you create it like any other canvas, and Homelable swaps+the renderer when you switch to it.++Where the diagram answers *what talks to what*, the rack answers *what is where*:+which U a machine sits in, what plate it wears, which switch port its uplink+lands on.++> Works with **and** without the backend. In the no-backend standalone/demo build+> a rack canvas persists to your browser's local storage; the Device Inventory+> picker and the live status check are backend-only (marked 🔒 below).++---++## Feature Overview++- **Racks** — any U height, 19" or 10" wide, bottom-up or top-down numbering, per-rack frame / rail / interior colours, open or enclosed.+- **Mounted gear** — a device occupies a U range and part of a 12-column width grid, so half- and third-width machines share a U.+- **Faceplates** — a visual catalog of plates (servers, switches, routers, patch panels, UPS, PDUs, desktop NAS towers, shelves, blanks, cable managers) drawn as vector artwork that scales with the rack.+- **Ports & patching** — RJ45 and SFP ports per device, cabled port-to-port by dragging from one to the other, across racks if needed.+- **Device Inventory** 🔒 — a mount points at a real inventory entry, so a rack shows the same devices your scans found, and gear you rack by hand joins that inventory.+- **Live status** 🔒 — a mount can follow the status check already configured on the matching diagram node, and light its plate LED accordingly.+- **Import links** 🔒 — derive patches in one shot from the physical links already drawn on your diagrams.++---++## Create a rack canvas++1. Open the **canvas switcher** at the top of the left sidebar.+2. Click **New Canvas**.+3. Under **Kind**, pick **Rack** (the other kind, *Diagram*, is the usual node/link canvas).+4. Name it, pick an icon, and create.++A canvas cannot change kind afterwards — a diagram and a rack store different+things. Deleting a rack canvas deletes its racks, mounts and cables with it;+duplicating a canvas duplicates them too.++---++## Add a rack++**Add Rack** in the header drops a new rack on the canvas. Drag it anywhere; a+canvas can hold as many as you like, and cables can run between them.++**Double-click the rack chrome** (the frame, not a device) to open its settings:++| Setting | What it does |+|---|---|+| Name / Location | Free text — "Baie salon", "Garage", … |+| U height | How many mountable U the rack has (42 by default). |+| Width | 19" or 10" — drives the drawn inner width. |+| Numbering | `bottom-up` or `top-down`. **Labels only** — gear never moves. |+| Show U numbers | Print the U scale on the rails. |+| Enclosed | Draw side panels / a closed chassis. |+| Colours | Frame, rails and interior. Defaults come from your app theme. |+| Delete | Removes the rack and everything mounted in it. |++---++## Mount a device++Click **+ Device** in the left sidebar, or drag an accessory from the sidebar+tray straight onto a rack. The device modal offers three sources:++- **Device Inventory entry** 🔒 — pick something already discovered. The field+ opens the real Device Inventory, with its search, source and type filters, and+ it opens pre-filtered to **rackable** hardware (no light bulbs, no sockets).+ A device already mounted on this canvas is refused.+- **New device** — for hardware no scan can find (a patch panel, a PDU, an+ unmanaged switch). It is created as a normal Device Inventory entry tagged+ **Rack devices**, so you can search, filter, hide and delete it like any other.+- **Accessory** — rack-only furniture: blanking plate, shelf, cable manager.+ These are not devices and never appear in the inventory.++Then set:++| Field | Notes |+|---|---|+| Label | Shown on the plate. |+| Faceplate | Opens the visual catalog — see below. |+| U position / height | `U` is counted **from the bottom rail**, whatever the numbering setting prints. |+| Column / width | Full, half, third, sixth or quarter of the rack width. |+| Status | A fixed colour, or **Check device** 🔒 — see below. |+| Colour | Overrides the plate's default tint. |+| Ports | The list of RJ45 / SFP ports, seeded by the faceplate and editable afterwards. |++**Double-click a plate** to reopen this modal on an existing mount; a single+click only selects it. **Unmount** takes the device out of the rack — it stays in+the Device Inventory.++### Placement rules++- A drop **snaps to the nearest free slot**; a placement that cannot work+ previews in red.+- Drag a mounted device inside its rack to move it — same snapping.+- **Growing** a device, by hand or by picking a taller plate, relocates it to the+ nearest slot that takes the new size. Only a rack with no such slot refuses the+ edit, and it tells you so.++---++## Faceplates++The **Faceplate** field opens a catalog, not a dropdown of names: every plate is+drawn with the real renderer, at its real relative width and U height, grouped by+family and searchable.++| Family | Examples |+|---|---|+| Servers | 1U, 1U with drive bays, 2U with bays, 4U storage, half-width SFF, third-width mini PC |+| Network | 8 / 24 / 48-port switches, 1U router |+| Patch | 24-port copper panel, 12-port fibre panel |+| Storage | 2U NAS, desktop NAS towers in 2, 4 and 5 bays |+| Power | 2U UPS, 1U PDU |+| Accessories | Blanking plate, shelf, cable manager |++Picking a plate **reseeds the ports** it comes with; your own port edits are kept+until you change plate again. Plates are drawn as vector artwork in relative+coordinates, so they stay correct at any rack width and U height, and their+colours follow the active app theme.++---++## Ports and patching++Ports are **RJ45** or **SFP/SFP+**, drawn as real jack artwork at a fixed size so+plates of different heights line up. Power outlets are artwork only — they are+never a cable endpoint.++Patch-facing gear (switches, patch panels) shows its ports permanently;+everything else reveals them on hover, on selection, or when cables are shown.++To cable:++1. Click **Patch** in the header.+2. **Drag from one port to another** — a dashed rubber band follows the pointer.+ Clicking the two ports in turn works just as well. **Escape** drops a+ half-drawn patch.+3. Repeat. One cable per port; copper or fibre follows the port you start from.+4. Click **Exit patching** when done — the canvas returns to the cable visibility+ it had before.++To unplug: **click the cable** (it gets an accent halo), then press+**Delete/Backspace** or click **Unplug** in the header. A stray click never+destroys a patch.++A header select controls what you see: cables **on hover**, **always**, or+**hidden**. With cables shown, plates fade so the patching reads clearly. Cables+pan and zoom with the canvas and may run from one rack to another.++### Import links 🔒++**Import links** derives patches from the physical links (ethernet, fibre, vlan,+cluster) already drawn on your diagrams, matching both ends to mounts that point+at those nodes. It runs **once per canvas** — afterwards, patch by hand.++---++## Status 🔒++A mount's **Status** is either pinned by hand (online / offline / unknown) or set+to **Check device**: the plate then follows the status check already configured+on the matching diagram node (ping, HTTP, SSH, …) and its LED lights accordingly.++The rack runs no checker of its own — it reads the result of the one your diagram+already performs. So:++- **Check device** is only offered when the mount resolves to a diagram node.+- Losing that link drops the mount back to `unknown`, rather than leaving it on a+ status nothing answers for.+- The refresh polls every 60 s, and only while at least one mount is on+ **Check device**.++---++## Saving++Like the diagram canvas, a rack canvas is **saved explicitly** — **Save Rack** in+the left sidebar, or the header's save button. Nothing is written behind your+back unless you turn on **Autosave** in Settings.++The sidebar footer counts racks, mounts, cables and free U instead of the+diagram's online/offline tally. **PNG export** works here too.++---++## Known limits++- **Front view only** — no rear view, no half-depth pairing.+- No 0U side-mounted PDU.+- No power draw or outlet budgeting.+- No undo/redo on a rack canvas (the diagram canvas keeps its own).+- Rack canvases are not shown by the read-only [Live View](../README.md#live-view-read-only-public-canvas).+- The MCP server exposes diagram nodes and links only, not racks.++---++## See also++- [FEATURES.md](../FEATURES.md) — every feature, one page.+- [Device Inventory](../FEATURES.md#12-device-inventory-) — where racked devices live.+- `frontend/src/rack/README.md` — the developer reference for this canvas.