rackpad

Rackpad

MCP inventory proposals are available as an opt-in beta feature. See MCP operator guidance.

Rackpad is a self-hosted infrastructure inventory and operations workspace for homelabs, small racks, network rooms, and lab environments. It brings racks, devices, ports, cables, Networks/IPAM, storage, Wi-Fi, compute, discovery, monitoring, documentation, images, integrations, reports, labs, and administration into one clean app.

This source targets stable release v1.8.7. Use GitHub Releases to confirm published artifacts. See the release and upgrade notes.

Docker is the supported deployment; native Proxmox LXC remains experimental. See the changelog; the latest-tag badge may show a prerelease.

Built with:

• React + Vite frontend
• Fastify API
• SQLite persistence through better-sqlite3
• session-based authentication with admin/editor/viewer roles
• per-device health checks with ICMP, TCP, HTTP/HTTPS, and SNMP (v1/v2c/v3) monitor targets; optional trap receiver and VLAN/subnet sync (see SNMP guide)
• Docker support for a single-container deployment; first-party native Proxmox LXC support is in staged validation

Stacked switches support ordered members, labelled MACs, port assignments and independent member templates.

Highlights

• Visual topology — a movable React Flow network map with cable routes, health overlays, and rack/pyramid layouts
• Racks, devices, ports & cables — dense rack elevations, switch-panel port maps, and full cable patching
• Networks and IPAM — VLANs, subnets, DHCP zones and reservations, gateway/DNS protection, and multi-IP device records
• Storage topology — drive inventory, physical bays and enclosures, cross-device pools, missing members, and reusable templates
• Monitoring — per-device ICMP, TCP, HTTP/HTTPS, and SNMP health checks with email/Discord/Telegram alerting
• Discovery — IPAM-subnet, all-subnet, and manual-CIDR scanning with import reconciliation
• Wi-Fi, compute & docs — controller/SSID/AP/radio/client inventory, virtualization hosts, and markdown docs with images
• Light & dark themes, self-hosted fonts (works offline / air-gapped), and multilingual support across 24 interface languages
• Self-hosted — single Docker container, SQLite persistence, session auth with admin/editor/viewer roles, optional OIDC

See the changelog for what landed in each release.

Quick links

Rackpad’s public website is rackpad.net. The repo also contains the core material you need:

• Installation guide
• Docker bind mounts and custom users
• Proxmox install notes
• Proxmox native LXC operations (pre-release)
• Hyper-V import guide
• Proxmox import guide
• Networks, VLANs, DHCP, and IPAM guide
• Controller integrations guide (Proxmox/UniFi/Omada/OPNsense/Dockhand)
• Discovery guide
• Reports guide
• Storage topology guide
• Visualizer guide
• OIDC login guide
• SNMP monitoring, traps & sync guide
• Discovery deployment (Proxmox/LXC/host networking)
• Documentation and images guide
• Automation roadmap (proposed)
• Proxmox native LXC roadmap (proposed)
• Security policy
• Community Discord
• Changelog
• MIT license
• Support notes

Preview

Rackpad ships light and dark themes. This preview is generated from a safe, opt-in demo database at 1920x1200; the lossless source captures live in docs/screenshots.

Dashboard — inventory, health, and activity

Storage — drives, bays, and pool health

Visualizer — physical and logical topology

Networks — VLANs, subnets, DHCP, and IPAM

Integrations — controllers and UTC schedules

WiFi — controllers, SSIDs, radios, and clients

Inventory and physical infrastructure workspaces

Labs and locations

Racks, rooms, and half-width placement

Device inventory

Compute hosts and workloads

Storage drive inventory in light theme

Aggregate ports and member links

Cable inventory and bulk editing

Operations, review, and administration workspaces

Operations dashboard (light theme)

Discovery inbox and scheduled scans

Review-first Proxmox import

Monitoring targets

Reports and exports

Audit history

Administration

Documentation, customization, and alternate topology workspace views

Diagram visualizer (light theme)

Documentation and linked runbooks

Managed custom device types

HTTP/HTTPS checks may target public hosts, RFC1918 LAN addresses, and IPv6 ULA addresses. Rackpad pins each DNS resolution and blocks loopback, link-local, metadata-service, multicast, and reserved destinations, including redirects.

What you can see before install

From the GitHub repo alone, you can already preview the major Rackpad workspaces:

• Dashboard for inventory, health, capacity, and recent activity
• Storage for drives, bays, custom enclosure layouts, cross-device pools, and missing-member review
• Racks for physical placement, mounted gear, and room-tech context
• Devices for searchable inventory and placement-aware records
• Device Types for managed custom types, built-in inheritance, and usage counts
• Ports for switch, host, AP, VM, and patch-panel connectivity
• Compute for hosts, VMs, and virtual switch / bridge membership
• WiFi for controllers, SSIDs, radios, clients, and signal context
• Discovery for staged imports, MAC/vendor hints, and duplicate detection
• Monitoring for multi-target ICMP, TCP, HTTP, and HTTPS checks
• Networks for consolidated VLANs, subnets, DHCP scopes, reservations, IP zones, assignments, and mismatch review
• Documentation for Markdown notes, runbooks, and inline pictures
• Imports for review-first Hyper-V and Proxmox host, VM, and container onboarding
• Integrations for Proxmox, UniFi, Omada, OPNsense, and Dockhand previews plus opt-in UTC schedules
• Reports for printable/PDF, Excel-compatible, and CSV exports
• Audit Log for accountable inventory, storage, integration, and review history
• Administration for users, settings, integrity checks, JSON export, and native SQLite snapshots
• Visualizer for rack, pyramid, diagram, loose-room, port, WiFi, and cable relationship maps

Feature guides

Use these when you want the workflow steps rather than just the overview:

• Hyper-V import: download the collector, collect inventory on a Hyper-V host, map or create the host record, review VMs, and import selected categories.
• Proxmox import: download the collector, collect inventory on a Proxmox node, map or create the node record, review QEMU VMs and LXC containers, and import selected categories.
• Reports: generate a clean inventory report, print/save to PDF, and export CSV or Excel-compatible files.
• Storage topology: document physical drive bays, lab-wide drive inventory, cross-device pools, and missing members.
• Networks/IPAM: create tagged or untagged networks, document DHCP scopes, zones, reservations, and VLAN planning ranges.
• Controller integrations: connect Proxmox VE, UniFi, Omada, OPNsense, and Dockhand APIs, store credentials encrypted, pull live inventory, and apply reviewed VLAN/subnet changes.
• Discovery: run manual or scheduled scans, keep results review-first, and understand Docker/LXC visibility limits.
• Visualizer: inspect rack, loose-room, port, and cable relationships from existing Rackpad data.
• OIDC login: configure Authentik or another IdP, map roles, and debug issuer/discovery URL problems.
• Documentation and images: create Markdown runbooks, insert pictures, attach device reference images, and include them in backups.

Versioning

Rackpad uses semantic versioning and Git tags in the form vX.Y.Z.

• The app version lives in package.json.
• Release notes live in CHANGELOG.md.
• The proposed long-term automation direction lives in docs/AUTOMATION_ROADMAP.md.
• The completed pre-1.0 rollout plan remains in V1_CHECKLIST.md as a historical record.
• Install and deploy examples should pin a version instead of assuming main.

Every shipped change should update the version and add a matching changelog entry describing what changed.

Release channels

Rackpad uses three ordered release branches:

• main: stable release branch intended for production and tagged releases
• beta: pre-release testing branch for changes that should be validated before they land on main
• dev: integration branch for work that is not yet ready for beta testing

Recommended workflow:

• integrate new work into dev
• promote validated development changes from dev to beta
• promote validated beta changes from beta to main
• create version tags like vX.Y.Z from main

The promotion order is dev → beta → main.

Branch image tags such as dev, beta, and latest move as their branches are published. Immutable semantic-version image tags such as 1.8.0 are created only from an explicitly approved Git release tag.

If you want the newest testing build instead of the latest stable tag:

git checkout beta
git pull origin beta

Legal and support files

The repository now also includes:

• the project LICENSE
• copyright and project notices in NOTICE.md
• a basic disclosure policy in SECURITY.md
• maintainer/support expectations in SUPPORT.md

Requirements

• Docker Engine with the Compose plugin for normal installs
• Node 22 LTS and npm for development or native installs

The repo includes .nvmrc, so if you use nvm:

nvm use

Development

Install dependencies:

npm install

Run the full dev stack:

npm run dev:all

This starts:

• frontend on http://localhost:5173
• API on http://localhost:3000

The Vite dev server proxies /api to the Fastify backend.

Production build

Build both the frontend and backend:

npm run build

Start the compiled app:

npm start

The authoritative environment-variable contract and defaults are documented in .env.example. CI checks that every supported runtime variable is represented there and passed through all intended Compose manifests. See INSTALL.md for deployment, secret, OIDC, discovery, and reverse-proxy configuration.

For provider setup, use the OIDC guide. For layer-2 visibility, permissions, and optional host discovery, use the discovery deployment guide.

First run

On the first boot there are no users yet.

1. Open Rackpad in the browser.
2. Create the initial admin account.
3. Sign in.
4. Choose whether to start empty or preload the expanded demo environment.
5. Start documenting racks, devices, VLANs, and IPAM.

If a local admin password is lost in a Docker install, use the container CLI recovery command documented in INSTALL.md. OIDC users must reset passwords in the identity provider.

Install With Docker

Use the installation guide for the canonical Linux, Windows, Proxmox, source-build, backup, update, and recovery procedures. Stable installations can pin RACKPAD_TAG=1.8.7; latest follows stable and beta follows testing. The normal deployment uses one hardened container and a persistent SQLite volume.

Linux test deploy

See native Node deployment for source-build requirements and the generic service example. Docker remains the recommended path.

Reverse proxy / TLS

Follow the version-specific proxy instructions. Older 1.8.0 uses controlled hop counts; stable 1.8.3 and 1.8.2 beta.4 onward require explicit proxy IPs/CIDRs. Terminate TLS at the proxy and restrict direct application access. Before upgrading, read the 1.8.6 upgrade precautions for encryption-key retention, OIDC re-login, trap opt-in, and paired rollback.

Native development note

Native development on Windows, Linux, and macOS requires Node 22. Docker remains the recommended deployment method.

Quality checks

Run the standard non-browser completion gate:

npm run check

npm run check:full adds Playwright browser and accessibility tests and is the full CI/release application gate. The canonical validation ladder is in .ai/COMMANDS.md; package.json owns the command bodies.

Server tests require Node 22 on a platform where better-sqlite3 can load.

Project layout

rackpad/
|- docs/screenshots/       GitHub-friendly app screenshots
|- server/                 Fastify API, SQLite schema, seed data, routes, tests
|- src/
|  |- components/          UI and feature components
|  |- lib/                 typed API client, store, types, helpers
|  |- pages/               route-level screens
|- dist/                   built frontend
|- dist-server/            built backend
|- Dockerfile              production container build
|- docker-compose.yml      local container orchestration

Full step-by-step setup instructions are in INSTALL.md. Version-by-version release notes are in CHANGELOG.md.

Special thanks

A special thank you to @M4v3r1cK87 and @dhop90.

Rackpad has benefited hugely from their time, testing, feedback, screenshots, bug reports, and ideas. Their involvement has helped shape the project in a very real way, and I am genuinely grateful for the care they have put into helping improve it.

Thank you both for being such an important part of Rackpad’s journey.

Support the project

Rackpad is free to use. If it helps you and you want to support the work, there is an optional Ko-fi link here on GitHub: ko-fi.com/k0bii. PayPal.me is also available here: paypal.me/St3wi.