Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

docs(rack): document the rack canvas for users

Pouzor2af6f728d793
diff --git a/FEATURES.md b/FEATURES.md
index 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 swit
2. [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.md
index 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 Scanner
The 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.md
new file mode 100644
index 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.