Skip to content

About

Visual home-lab rack designer: drag servers, switches and patch panels into a 19" or 10" rack and check power, PoE and cabling. Self-hosted (Docker) or desktop app for Windows and Ubuntu.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

RackPlanner

The RackPlanner editor in dark mode with the "My RackMate T1" design: catalog on the left, an 8U 10-inch DeskPi RackMate T1 with a patch panel, UniFi switch, Raspberry Pi, gateway, power board and NVR in the middle, and power, PoE and warning stats on the right

A self-hosted visual designer for home-lab server racks. Pick a 19″ or 10″ rack (1–32U), drag hardware from a researched catalog of ~340 parts into it, put desktop gear on shelves, and check the totals: power vs UPS capacity, PoE budget, mains outlets, weight and ports. Export the result as PNG, SVG, PDF, CSV or JSON.

Runs as a single Docker container with a SQLite database, or as a desktop app for Windows and Ubuntu (download). No accounts and no cloud; it's built for your LAN.

Features

  • Detailed faceplates, front and rear: every device is drawn as SVG from catalog data: RJ45 jacks with link/activity LEDs and latch notches, metallic SFP/QSFP cages, USB, HDMI, IEC and AU/NZ power, keystones, drive trays, displays, vents, fans and PSUs. Popular gear has a researched, sourced layout; everything else gets a sensible generated one. No logos or product photos.
  • Style presets: UniFi-style silver/white/black, server bezel, NAS grey, PDU, UPS, patch and brush panels and more, all fine in light and dark mode. Lit LEDs, or switch them off for a clean print look.
  • Rack frames: 2-post, 4-post, enclosed cabinet (with glass door) and 10″ mini racks including the DeskPi RackMate T1 / T2, with rails, EIA hole spacing (square cage-nut holes, or round tapped #10-32 holes on the RackMate rails) and free-slot hints.
  • Shelf plans: a top-down view of every shelf showing how devices fit side by side, with overhangs flagged.
  • Placement: drag and drop with U snapping, collision checks, front / rear / full-depth mounting, partial-width gear and desktop gear on shelves. Warns when something is too wide, deep or tall for its shelf.
  • Wall area: an optional wall beside the rack for wall-mounted gear: nbn connection boxes, modems, and data, TV, phone, fibre and power wall plates (AU/NZ single, double and USB power points, UK, EU Schuko and US outlets), cabled to the rack like anything else. The power points count towards the outlets the rack's gear needs.
  • Power sources: USB-C, DC adapters, plug-packs and IEC inlets per device, checked against the outlets your power boards provide.
  • Cables: colour-coded port-to-port patch cables, with tooltips on every port ("Port 17 — 1 GbE (PoE+)").
  • Zoom-aware detail: simplified blocks when zoomed out and full detail up close, so a full 32U rack stays smooth.
  • Catalog: full UniFi lineup plus MikroTik, Synology, QNAP, UGREEN, TP-Link, Netgear, Cisco, Dell, HPE, Supermicro, APC, CyberPower, Eaton, DeskPi, Raspberry Pi and generic passive gear, with search, filters and a custom part builder.
  • Designs, stats and exports: start empty or from a template, autosave, undo / redo, power / heat / UPS / PoE / weight totals with warnings (including mixed airflow), and PNG / SVG / PDF / CSV / JSON exports.
  • Read-only share links: send someone a link to view a design, with no login needed.
  • 3D-printed parts: paste a MakerWorld link to turn a printed mount, shelf or panel into a part, linked to the device it holds, with designer credit, licence and print status.

Gallery

Front view of the My RackMate T1 build: 12-port keystone patch panel, Lite 8 PoE switch and Raspberry Pi 4 on a shelf, Cloud Gateway Ultra, AU power board, vented panel and the NVR Instant in a 3D-printed 2U mount at the bottom Rear view of the same build: punch-down backs of the patch panel, the gateway's network ports and USB-C power, and the NVR's ports
My RackMate T1, front: a 10″ 8U DeskPi RackMate T1 with desktop UniFi gear on shelves. And the rear: each device's rear panel, seen through the open back.
A populated 24U 19-inch cabinet with a UniFi gateway, switches, patch panels, NVR, UNAS, Synology NAS, Dell servers, a PDU and an APC UPS Top-down shelf plans showing the switch and Raspberry Pi side by side, the gateway, and the NVR in its printed mount
A full 24U 19″ cabinet: UniFi, servers, NAS, patch panels, PDU and UPS. Shelf plans: how desktop gear fits on each shelf, with overhangs hatched red.
The editor in light mode showing the 24U homelab rack The same editor view in dark mode
Light mode Dark mode
The catalog sidebar filtered to Ubiquiti PoE switches with a search term The custom part builder dialog with a live faceplate preview
Catalog with search and filters. Custom part builder with a live preview.
Animation: a switch is dragged from the catalog into an empty rack, then moved down to another slot
Drag and drop from the catalog, then rearrange.

Device renders

Front faceplates exported as SVG, straight from the renderer.

Raspberry Pi 4 in the official red and white case: USB 2.0 pair, USB 3.0 pair and Ethernet UniFi Cloud Gateway Ultra front with its small status display
Raspberry Pi 4 (official case) UniFi Cloud Gateway Ultra
UniFi Switch Lite 8 PoE: eight ports, PoE markers on ports 1 to 4 UniFi NVR Instant front with its display
UniFi Switch Lite 8 PoE UniFi NVR Instant
DeskPi 10-inch 1U 12-port keystone patch panel with a label strip UniFi-style silver 24-port PoE switch with SFP+ cages
DeskPi 10″ 12-port keystone panel Preset: UniFi silver
Black server bezel style: 2U server with eight 3.5-inch drive trays Dark grey NAS style: 1U rack NAS with four drive bays
Preset: server bezel Preset: NAS grey
Dark server style with a green accent: 1U server with ports and vents Light metal style with a red accent: router with ports and SFP cages
Preset: dark server Preset: light metal
UniFi-style black device Generic black 10-inch switch
Preset: UniFi black Preset: generic black
24-port keystone patch panel 1U brush panel with its bristle strip
Preset: patch panel Preset: brush panel
1U horizontal PDU with eight C13 outlets and a power switch 2U UPS with a status display, buttons and a status bar
Preset: PDU Preset: UPS
10-inch rack shelf with side lips Generic silver desktop computer
Preset: shelf Preset: generic silver

All images are generated by npm run screenshots (see Development); none are hand-edited, and none are manufacturer photos or logos.

Desktop app (Windows and Ubuntu)

⬇ Download the latest installers (Windows .exe, Ubuntu .deb)

RackPlanner also runs as a normal desktop app, no Docker or server needed. It's the same app: the server runs inside the window, bound to 127.0.0.1 only, and your designs are kept in your user profile:

Installer Designs are stored in
Windows 10/11 (x64) RackPlanner-Setup-<version>.exe %APPDATA%\RackPlanner\data
Ubuntu 22.04+ / Debian (x64) rackplanner_<version>_amd64.deb ~/.config/RackPlanner/data
  • Windows: run the installer. It isn't code-signed, so SmartScreen may say "Windows protected your PC": click More info → Run anyway. It installs for your user only (no admin prompt) and adds Start-menu and desktop shortcuts.
  • Ubuntu: sudo apt install ./rackplanner_<version>_amd64.deb, then open RackPlanner from the app grid or run rackplanner. Remove it with sudo apt remove rackplanner.

File → Open Data Folder shows where your designs live. To move designs between the desktop app and a server install, use Backup on the home page and Import on the other side.

Building the installers

Only Docker is needed:

desktop/build.sh          # both; or: desktop/build.sh linux | win

This builds the web app and server, then packages them with Electron and electron-builder in the electronuserland/builder:wine image (Wine is used to stamp the Windows .exe's icon and version info). The installers land in desktop/dist/. The only native module, better-sqlite3, ships Node-API prebuilds that work in Electron on every platform, so nothing is compiled.

Releases are automated. Pushing a version tag runs .github/workflows/desktop-release.yml: it runs the checks, builds both installers with desktop/build.sh, installs the .deb on the runner to check it starts, and attaches the installers and SHA256SUMS.txt to a GitHub Release for that tag:

git tag -a v0.2.0 -m "RackPlanner 0.2.0" && git push origin v0.2.0

The app version comes from the tag. Running the workflow by hand from the Actions tab builds the installers as a downloadable artifact without publishing anything.

To run the desktop shell from source (needs Node 22+ and a desktop): npm run build, then cd desktop && npm install && npm start.

Install on Ubuntu (server)

  1. Install Docker (skip if you already have it):

    curl -fsSL https://get.docker.com | sudo sh
    sudo usermod -aG docker $USER   # log out and back in afterwards
  2. Get RackPlanner and start it:

    git clone https://github.com/fipity/rackplanner.git
    cd rackplanner
    cp .env.example .env            # optional: port, PUID/PGID, basic auth
    docker compose up -d
  3. Open http://<server-ip>:8085.

The first build takes a few minutes. The container restarts automatically (restart: unless-stopped), and docker compose ps shows its health (GET /api/health).

Configuration (.env)

Variable Default
RACKPLANNER_PORT 8085 Host port. Change it, then run docker compose up -d
PUID / PGID 1000 Owner of ./data on the host (run id to see yours)
BASIC_AUTH_USER / BASIC_AUTH_PASS empty Set both to require a password. /api/health and read-only share links stay open
LOG_LEVEL info debug, warn, error, silent…

Updating

cd rackplanner
git pull && docker compose up -d --build

Designs and custom parts live in ./data and survive rebuilds. Catalog changes are applied on startup, and existing designs keep working: parts removed from the catalog are retired, not deleted.

Backup and restore

Everything (designs, custom parts, catalog state) is in one SQLite database: ./data/rackplanner.db.

  • From the app: use the Backup button on the home screen, or run curl -o rackplanner-backup.db http://<server-ip>:8085/api/backup. This is a consistent snapshot, taken safely while the app runs. Single designs can also be exported as JSON and re-imported.

  • Manually: docker compose stop && tar czf rackplanner-data-$(date +%F).tgz data && docker compose start

  • Restore: stop the container, replace the database, and remove the leftover write-ahead files so SQLite doesn't replay them onto the restored copy:

    docker compose stop
    cp rackplanner-backup.db data/rackplanner.db     # or: tar xzf rackplanner-data-<date>.tgz
    rm -f data/rackplanner.db-wal data/rackplanner.db-shm
    docker compose start

Raspberry Pi / ARM

The image supports amd64 and arm64. On a Pi 4/5 or other arm64 host, docker compose up -d --build builds natively. To build both architectures elsewhere, e.g. for a registry:

docker buildx build --platform linux/amd64,linux/arm64 -t <registry>/rackplanner:latest --push .

Using the editor

Action How
Add a part Drag it from the catalog into the rack, or click it to drop it in the first free slot
Move Drag a placed part (red = blocked, with the reason shown next to the cursor)
Put desktop gear on a shelf Drag it onto a shelf, or just click it in the catalog: it goes onto a shelf with room. It stands on the tray and snaps beside items already there
Lay shelf gear on its side Select it and press R, or choose Orientation: On its side. It takes less height and more shelf width; its faceplate and ports turn with it, and cables stay connected. Gear that doesn't fit standing up is laid on its side for you: when it's too tall for the room above a shelf (like the nbn HFC NTD), when only that fits under the gear above, or near the top of the rack or wall. This applies when you drag, click to add from the catalog, duplicate or move it between the wall and the rack. Gear that only fits upright is stood back up
Put gear on the wall beside the rack Turn on the wall with the wall button in the toolbar, then drag desktop gear or wall plates onto it (left of the rack in the front view, right of it in the rear view). Clicking a wall plate in the catalog turns the wall on and puts it there. For a selected desktop device, Where: In the rack / On the wall moves it without dragging. Turning the wall off asks before removing what's on it
Select a shelf that has gear on it Click its ears or tray, or the shelf name in an item's details
Draw cables Press C (or Cables in the toolbar), click a port or device, then the other end. Esc finishes
Edit / delete a cable Click it to edit type, colour, ports, length, label; Del removes it
Partial-width position Select a 10″ / half-width part (or a shelf item), choose Left / Centre / Right
Move by 1U ↑ / ↓ (shelves take their contents with them)
Delete / duplicate Del / Ctrl+D
Undo / redo Ctrl+Z / Ctrl+Shift+Z
Measured power Select a device and enter watts in Measured power
Export / print Export menu in the header

Changing the rack width, height or depth so that some parts no longer fit asks for confirmation and lists what would be removed. You can undo afterwards.

Moving around: keyboard and mouse shortcuts

The canvas pans and zooms freely, like a map: you can move well past the rack in every direction (up to a full screen of empty space on each side). If the rack ends up off screen, a Back to rack button appears. Each design remembers its zoom and position. Press ? in the editor (or the keyboard button in the canvas corner) for this list.

Pan
Drag empty space Left mouse button (a click without moving still deselects)
Space + drag From anywhere, even over a device (the cursor becomes a hand)
Middle or right mouse button Drag from anywhere
Two-finger trackpad scroll Any direction, diagonally too
Shift + mouse wheel Horizontal
Arrow keys Pan when nothing is selected (Shift for bigger steps). With a device selected, ↑ / ↓ move it 1U as before
Touch One finger on empty space pans; two fingers pinch to zoom and pan together
Zoom
Mouse wheel Zoom towards the cursor (no key needed)
Ctrl / ⌘ + wheel, trackpad pinch Zoom towards the cursor
+ / -, toolbar zoom buttons Zoom around the centre of the view
Zoom % in the toolbar Click it to type a zoom level, 10% to 800% (100% = 1 px per mm)
F or Shift+1 Fit the whole drawing (rack and wall) to the screen
Shift+2 Zoom to the selected device
0 or Ctrl+0 Reset to 100%, centred
Minimap The map button in the canvas corner shows the whole rack with the visible area outlined; click or drag in it to move there. The choice is remembered

Dragging a device near the edge of the canvas scrolls the view so you can drop it further away. The page itself never scrolls or zooms while you're over the canvas; the sidebars scroll as usual. Exports always show the whole rack, whatever the view.

Browsers don't say whether scrolling comes from a mouse wheel or a trackpad, so RackPlanner goes by how it scrolls: a wheel's notches zoom, and small, smooth or sideways movements (two fingers on a trackpad) pan. If it guesses wrong for your mouse, the scroll wheel button in the canvas corner (also in the ? popup) switches between Wheel zooms (automatic), Wheel always zooms (every scroll zooms, trackpads too) and Wheel pans (hold Ctrl to zoom). The choice is remembered.

Cables

Turn on Cables mode (C) and every drawn port becomes clickable. Click one end, then the other, to add a cable. You can connect two ports, or a port to a whole device when the port isn't drawn (e.g. the NIC on a desktop NAS). The cable type is guessed from the ports (copper, DAC, fibre, coax, phone or power) and can be changed. Select a cable to set its colour, change either end's port, add a label, or set a length. Use … m suggests a standard patch-lead length from the distance between the ends, plus slack.

When the rack has cable managers or brush panels, cables are routed the way they'd be dressed: from the port into the nearest manager (within about 2½U), along it, and up or down the side of the rack beside the posts when the two ends use different managers. Cables sharing a manager or a side run are spread a little apart, so they read as a bundle. D-ring and finger-duct managers work on the face they're mounted on; brush panels work from both sides, and a front-to-rear cable is drawn to the brush panel it passes through (marked with a small ring). Without any managers, cables are drawn as a loose curve between the ends, as before. The Use … m suggestion measures along the routed path.

Cables between the front and the rear (or to a device on the other face) are drawn dashed. The eye button hides them all. Deleting a device removes its cables, and undo brings everything back. Warnings flag two cables on one port, ports that don't exist on a device, and cables to deleted devices. The CSV, PDF and printable parts lists include a cable shopping list grouped by type and length.

Designs

The home screen lists your designs with live thumbnails. Create a new one by picking a width, a height preset and an optional depth, or start from a template: a 10″ mini rack, an nbn + UniFi starter in a DeskPi RackMate T1, a 12U 19″ homelab, or a 9U network cabinet. Rename, duplicate or delete designs from each card's menu, and Import a design exported as JSON. JSON exports include any custom parts the design uses, so they move cleanly between RackPlanner installs.

Sharing

Share in the editor creates a read-only link (/s/<token>). Anyone with it sees both views, the stats and the parts list, and can print it or download it as PDF or JSON (to import into their own RackPlanner). They can't change anything. The link always shows the latest saved version. Stop sharing turns it off for good; sharing again makes a new link. Share links work without the basic-auth password: only the share page, its static files and GET /api/shared/<token> are open, so a link only reveals the one design behind it. In the desktop app the server only listens on this computer, so links only work there.

Changes save automatically as you work. If the same design is saved from another tab or device, you're asked whether to keep your version or load the latest one.

Stats & warnings

The Stats tab, next to the device details, updates live:

  • Space: U used and free (a U counts as used if anything occupies it, front or rear), plus device and passive counts.
  • Power: typical and max draw. A device's measured power (e.g. from a smart plug or PDU reading) replaces catalog figures. When a part only publishes one figure, it's used for both. Catalog max power excludes PoE output, so the expected PoE load you enter is added on top before comparing against total UPS capacity.
  • Heat: the rack's heat output in BTU/h (typical to max draw × 3.412). PoE power delivered to cameras and access points is given off where they are, not in the rack.
  • PoE: total PoE budget of the switches and gateways in the rack, compared with your expected PoE load.
  • Weight and port counts by type.
  • Cables: count by type and total length.
  • Warnings: devices deeper than the rack, gear deeper than its shelf, desktop gear not on a shelf, collisions or bad widths (e.g. after an import), parts missing from the catalog, UPS or PoE overload, cable problems, mixed airflow (one device blowing hot air out of the rack face where another draws cool air in), and devices with no power data. Click a warning to select the device.

Airflow

Rack servers and UPSs are assumed to breathe front to back; other gear has no airflow unless its catalog entry sets one (airflow: front-to-back, back-to-front, side-to-side or passive). Set your own in the inspector's Airflow field. Airflow is relative to the device's front panel, so gear mounted on the rear rails blows the other way through the rack.

Exports

Format Contents
PNG / SVG Front, rear, or both side by side, with title. SVG is fully vector
PDF Page 1: front + rear views (landscape for short racks). Page 2: parts list, 3D-printed parts (model URL, designer, licence), summary and warnings
CSV Bill of materials: brand, model, quantity, U, power, weight, labels, spec URL, model URL / designer / licence for 3D-printed parts, plus cables by type and length
JSON Full design plus the custom parts it uses (re-importable), with 3D-printed parts' cached pictures unless you pick JSON without 3D-print thumbnails
Parts to print 3D-printed parts with picture, filament, status, model link, designer and licence. Printable, or CSV / Markdown
Printable view Light layout with both views, stats and the parts list. Print from the browser

Images and PDFs always use full detail, whatever the editor's zoom. Tick Print style (LEDs off) in the Export menu (or use the LED button on the printable view) for a cleaner look without lit status LEDs.

Catalog

~300 parts in versioned JSON files under catalog/:

File Contents
unifi.json Full rack-relevant UniFi lineup: gateways, switches, UNAS/UNVR/ENVR, UPS/PDU/RPS, OCD panels, shelves, rack-mount kits, plus desktop gear for shelves
mikrotik.json CRS/CSS switches, CCR/RB routers, RDS storage
switching.json TP-Link Omada, Netgear, Cisco, legacy Ubiquiti EdgeMax/UISP
storage.json Synology RackStation, QNAP rack NAS
servers.json Dell PowerEdge, HPE ProLiant, Supermicro chassis, generic DIY cases
power.json APC, CyberPower, Eaton UPS units and generic PDUs
patch-panels.json Generic 19" patch panels, blanks, brush panels, cable managers, shelves, drawers
mini-rack.json 10" ecosystem: DeskPi RackMate shelves/panels, Pi and mini-PC mounts, 10" PDUs
desktop.json Mini PCs, Raspberry Pis, UGREEN NASync desktop NAS, modems/ONTs that sit on shelves

What verified means: true means every number in the part comes from the manufacturer's own spec page or datasheet, linked in sourceUrl. false means the figures come from resellers, rack-vendor guides or typical values for generic items. Unknown values are null, never guessed. catalog/UNVERIFIED.md lists every unverified part and every missing value.

On first start the catalog is loaded into the SQLite database in ./data. When a file's contents change, it's re-applied on the next start. Parts removed from a file are retired: hidden from the catalog but kept, so existing designs still render.

Adding or editing catalog parts

  1. Edit or add a JSON file in catalog/. Your editor can autocomplete against catalog/schema.json. Bump the file's version.
  2. Validate it: npm run validate:catalog (or ./dev.sh run validate:catalog). This lists every problem and exits non-zero, and the Docker build runs it too.
  3. Deploy: docker compose up -d --build. To skip rebuilding, uncomment the ./catalog volume in docker-compose.yml, then run curl -X POST http://localhost:8085/api/catalog/reload after editing.

Custom parts

Use the + button in the catalog to build your own device, with a live front and rear faceplate preview. Pick a style preset, then tick Custom layout to place regions yourself (ports, SFP cages, drive bays, display, vents, fans, PSUs, labels…) with % positions, or press Start from generated layout to begin from what the app would draw. The builder warns when the layout's ports don't match the port list or regions overlap. The copy icon on any catalog part (or Customise a copy in the inspector) starts from an existing part. Custom parts are stored in the database, appear under My custom parts, and are never overwritten by catalog updates.

3D-printed parts

The My RackMate T1 example with the 3D-printed NVR mount selected: the UniFi NVR Instant sits inside the 2U mount at the bottom of the rack, and the details panel shows a placeholder model picture, the designer credit, licence, print status, filament colour and a View on MakerWorld button

Click Add 3D-printed part (in the catalog, or at the top of the custom part builder) and paste a MakerWorld model link. Any form works: with or without /en/, the name slug or #profileId-…. RackPlanner keeps a cleaned link and reads the model page once, when you paste it: title, designer, licence, print profile, a short description and the cover picture, from the page's public meta tags and embedded JSON. Print files (STL / 3MF) are never downloaded; the part links to the model page.

MakerWorld often blocks automated requests. When it does, nothing breaks: the name comes from the link (unifi-nvr-instant-10-inch-rackmount → "UniFi NVR Instant 10 Inch Rackmount"), the other fields stay editable, you can paste or upload a picture yourself, and Refresh details tries again later.

Before saving you check and edit what was guessed from the title:

  • Rack width (10″ / 19″) and U height (1U, 2U, 1.5U…). When the title has no height it defaults to 1U, highlighted so you check it.
  • Part type: rackmount (holds a device), shelf, blank, cable management, patch panel / keystone, ear / bracket, other.
  • Device it holds: the title is matched against the catalog ("UniFi NVR Instant" → the UniFi NVR Instant). Confirm it, pick another, add more (e.g. 2 × Raspberry Pi) or remove it.
  • Name, depth, front / rear, filament colour, notes and print status (planned, printing, printed, installed).

The part is saved as a custom catalog part tagged 3d-printed (filter the catalog with 3D printed), reusable in any design. Placing a mount places the devices it holds inside it, showing their real front panels through the cutout; dragging the mount moves them too, and removing it asks whether to keep them (moved to the nearest free shelf) or remove them as well. The stats warn when a device is too wide, tall or deep for its mount or the rack.

Printed parts are drawn in their filament colour, matte, with printed-on rack ears, faint layer lines up close and a small printer badge. Selecting one shows its picture, the designer (linked), the licence (NonCommercial / NoDerivatives are called out), print status and filament per placement, and View on MakerWorld. The stats count printed parts and how many are still to print, and Export → Parts to print lists them with picture, colour, status and link (printable, or CSV / Markdown). The CSV bill of materials, the PDF and the printable view include each printed part's model URL, designer and licence, and JSON exports carry the source details plus the cached pictures (or choose JSON without 3D-print thumbnails).

Pictures are resized to 600 px and kept in ./data/thumbnails, so they show offline. Fetching is locked down: only https://makerworld.com pages (and pictures from MakerWorld's image host, bblmw.com), checked on the parsed hostname for every redirect, never private or local addresses, a 10 s timeout, 2 MB pages and 5 MB images, images checked by decoding them, all fetched text stripped to plain text, and at most 10 fetches a minute. The My RackMate T1 example holds its NVR Instant in a MakerWorld mount. The NVR is 220 mm deep in the T1's 212 mm frame, so that example shows a depth warning. Printables and Thingiverse links aren't supported yet; each site is a small "source adapter" (packages/shared/src/printed/sources.ts).

Regenerating the researched catalog

scripts/research/ has the scripts that built the catalog. They cache spec pages in ~/.cache/rackplanner-research:

python3 scripts/research/fetch_unifi.py      # techspecs.ui.com (UniFi + EdgeMax/UISP)
python3 scripts/research/build_unifi.py      # -> catalog/unifi.json
python3 scripts/research/fetch_mikrotik.py && python3 scripts/research/build_mikrotik.py
python3 scripts/research/build_misc.py       # servers, storage, switching, power, passive, 10", desktop, UGREEN
python3 scripts/research/gen_unverified.py   # -> catalog/UNVERIFIED.md

Faceplate layouts

Each catalog entry can describe its front, rear and top faces declaratively; the renderer places the parts:

"layout": {
  "layoutVerified": false,
  "sources": ["https://techspecs.ui.com/unifi/cloud-gateways/ucg-ultra"],
  "front": { "style": "unifi-white", "regions": [ { "type": "display", "x": 0.41, "w": 0.18 } ] },
  "rear": {
    "regions": [
      { "type": "usb_c", "count": 1, "portType": "none", "role": "Power in", "x": 0.05 },
      { "type": "rj45", "count": 4, "portType": "rj45_1g", "x": 0.25 },
      { "type": "rj45", "count": 1, "portType": "rj45_2_5g", "start": 5, "uplink": true, "role": "WAN", "x": 0.78 }
    ]
  }
}
  • Positions (x, w, y, h) are fractions of the face, so the same layout works on 19″, 10″ and half-width gear. A region without x follows the previous one, and one without w takes its natural size (scaled down to fit, never overlapping the next placed region).
  • Port regions (rj45, sfp_plus, qsfp28, usb_a, usb_c, hdmi, iec_c14, outlet_au, keystone, punchdown, lc…) take count, rows, grouping, poe / poePorts, uplink, colors and numbers. Two-row blocks number switch-style (odd on top, even below); portType ties them to the entry's ports for cables and stats ("none" for pass-through backs).
  • Feature regions: bays, display, vent, leds, ledbar, button, label, psu, fan, pcie, io_shield, ground, label_strip, cable_bar, brush, handle, thumbscrew, switch, breaker, slot, d_ring, panel.
  • style picks a preset: unifi-silver, unifi-white, unifi-black, dell-bezel, hpe, synology, mikrotik, generic-black, generic-silver, patch-panel, brush-panel, shelf, pdu, ups, rpi-case.
  • Entries without a layout get one generated from their ports, bays and category.
  • npm run validate:catalog checks every layout against the schema, that it stays inside its face without overlaps at each rack width, and that it draws each catalog port exactly once. Layouts with layoutVerified: false are listed in catalog/UNVERIFIED.md with what couldn't be confirmed.

powerInput records how a device is powered (usb_c, dc_barrel, iec_c14, poe…, via a plug-pack or brick), which feeds the outlet check in the stats.

API

Method Path
GET /api/health Health check (used by Docker)
GET /api/backup Download a consistent SQLite snapshot
GET /api/catalog All parts, retired ids, catalog files
POST /api/catalog/reload Re-read catalog/*.json
POST / PUT / DELETE /api/parts[/:id] Custom parts (imports keep custom-* ids)
GET / POST /api/designs List / create ({name, rack} or import {design})
GET / PUT / DELETE /api/designs/:id Load / save ({design, revision, force?}, 409 on conflict) / delete
POST /api/designs/:id/duplicate Copy a design
GET / POST / DELETE /api/designs/:id/share Read / create / revoke the design's read-only share link
GET /api/shared/:token A shared design and the parts it uses (open without basic auth)
GET /api/templates Starting-point designs (examples/templates/*.json)
POST /api/printed/resolve {url}: parse a MakerWorld link and read the model page once (cached; fetched: false with a reason when it's blocked)
POST /api/printed/refresh {url}: read the model page again
POST /api/thumbnails {data} (base64 or data: URL, ≤ 5 MB): store a picture, returns its id
GET /api/thumbnails/:id A stored picture (WebP, open without basic auth like share links)

Development

There's no Node on the host? ./dev.sh runs npm inside a node:22 container:

./dev.sh install
./dev.sh test               # vitest: placement, stats, exchange, schema, catalog files, API
./dev.sh run typecheck
./dev.sh run dev            # API on :8085, Vite on :5173 (proxying /api)

Screenshots and README images

Every image in docs/images/ is produced by the app itself:

npx playwright install chromium   # once
npm run screenshots               # builds, starts a scratch server, captures, optimises

3D-printed parts in screenshots always show a generated placeholder picture: model pictures belong to their designers and never go in the repository. It starts the built server on a temporary database (the example designs in examples/ seed themselves), drives Chromium, writes palette-optimised PNGs, the drag-and-drop GIF and the device SVGs, and fails if docs/images/ grows past 15 MB. If the browser runs under a different Node version from the server (for example inside the mcr.microsoft.com/playwright image), start the server yourself on an empty DATA_DIR and pass BASE_URL=http://127.0.0.1:<port>.

npm run examples rebuilds examples/*.json and the templates in examples/templates/ from the catalog, checking every placement and cable.

Visual tests

tests/visual holds Playwright snapshot tests: one reference device per style preset (see /_faceplates), front and rear, in light and dark mode, plus checks for port tooltips and self-contained SVG exports. Snapshots are rendered in the mcr.microsoft.com/playwright:v1.64.0-noble image:

BASE_URL=http://127.0.0.1:8097 npm run test:visual            # against a server on a scratch DATA_DIR
BASE_URL=http://127.0.0.1:8097 npm run test:visual -- --update-snapshots

GitHub social preview

GitHub can't take the social preview image from the repository. Upload docs/images/social-preview.png (1280 × 640) under Settings → General → Social preview → Edit → Upload an image.

Layout:

packages/shared   zod schemas, placement engine, faceplate layout engine, stats, power, import/export + BOM
apps/server       Fastify API (SQLite via better-sqlite3 + Drizzle) + static hosting of the built web app
apps/web          React + Vite + Tailwind editor (SVG rendering, dnd-kit, zustand + zundo, jsPDF)
catalog/          parts catalog JSON seed files (+ UNVERIFIED.md)
examples/         example designs, added to the design list once; templates/ for the New design dialog
scripts/          catalog validator, example builder, screenshot pipeline, research scripts
docs/images/      generated README images

Licence

MIT

About

Visual home-lab rack designer: drag servers, switches and patch panels into a 19" or 10" rack and check power, PoE and cabling. Self-hosted (Docker) or desktop app for Windows and Ubuntu.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages