Rackpad

Important

Help shape Rackpad’s next phase

We have published a proposed automation roadmap covering the public API, optional agents, deeper infrastructure integrations, network and IPAM automation, major provider support, and carefully controlled infrastructure management.

These are proposed directions rather than shipped features or fixed delivery dates. We would like community feedback before implementation begins.

Read the roadmap and share your feedback →

View the detailed engineering roadmap

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.

See the changelog for release history; the badge above tracks the latest tag.

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

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
• Proxmox install notes
• 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)
• 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

What works

• Rack inventory and physical placement
• Add, edit, and delete racks
• Add, edit, and delete devices
• Custom device types for inventory, discovery, icons, filters, and port templates
• MAC address fields, search, sort, import, and display beside IP context
• Device placement modes for rack, room, wireless, and virtual inventory
• Parent-child device relationships for hosted VMs and AP-linked wireless clients
• Host-shared networking for VMs and containers that intentionally reuse a parent host IP
• Multiple IP assignments per device, with device-level and port/interface-level context
• Compute workspace for virtualization hosts and VMs
• Capacity tracking for hosts and VMs with CPU, memory, storage, and specs fields
• Port templates for new devices
• Manual port create, edit, and delete
• WiFi port kind across device types, templates, selectors, labels, visualizer views, and reports
• Create, edit, and delete cables
• VLAN allocation and VLAN deletion
• VLAN range create, edit, and delete
• IPAM subnet, DHCP scope, DHCP reservation, and IP zone CRUD
• Gateway, DNS, reserved, infrastructure, and technical IP protection during allocation, discovery, and reconcile
• Controller-aware WiFi workspace for controllers, SSIDs, AP radios, and wireless clients
• Wireless client telemetry with AP, SSID, band, channel, signal, last-seen, and roam context
• WiFi client grouping by AP/SSID in visualizer views when association or VLAN/IPAM context is available
• Discovery inbox with subnet scan, duplicate awareness, review, and import into inventory
• Discovery enrichment with MAC/vendor capture, technical IP preservation, natural IP sorting, and direct linking to existing inventory
• Management IP synchronization between device records and IPAM
• Next-free IP allocation and IP release
• DHCP reservation allocation from IP zones instead of treating the whole DHCP scope as assignable
• Direct links between devices, ports, IPAM assignments, racks, rooms, dashboard cards, reports, and visualizer inspector entries
• Bulk device status edits and bulk delete with dependency cleanup
• Unmanaged device status across inventory, filters, reports, backups, and monitoring; health checks continue but do not overwrite that manual state
• Atomic bulk cable type, length, and color edits across selected inventory rows
• Audit log writes for the main workflows
• User bootstrap, login, logout, and user management
• Optional OIDC login with PKCE, role mapping, and Authentik-style issuer/debug guidance
• Admin-only portable JSON backup/restore plus optional scheduled native SQLite snapshots and an offline restore CLI
• Backup exports preserve password hashes, documentation pages, device images, MACs, and parent-linked devices for restore, but redact stored alert-delivery secrets before download
• Device health-check configuration, alert destinations, repeat-alert controls, and on-demand monitor runs
• Multiple monitor targets per device so servers, firewalls, and multi-NIC systems can track separate management, service, storage, or VIP endpoints
• Bulk ICMP, TCP, HTTP, and HTTPS monitor creation from selected devices
• Device service inventory for DHCP, DNS, VPN, NTP, SNMP, Syslog, HTTP/S, databases, apps, and custom services
• SMTP/email alert delivery beside Discord and Telegram, plus recent alert activity in the admin area
• Reports workspace with printable/PDF-friendly inventory summaries plus Excel-compatible and CSV exports
• Visualizer workspace for grouped rack layout, pyramid view, and React Flow diagram mapping, with Health mode, Trace mode, multi-select filters, loose-device layout toggles, room-only rack-zone toggles, and saved diagram positions
• Rack shelves with proportional child-device footprints for multi-device and multi-U shelf documentation
• Markdown Documentation workspace for runbooks and notes, including inline image insertion
• Device image attachments with labels and notes on device detail pages
• Hyper-V import wizard for staging hosts, VMs, power state, guest OS, virtual switches, virtual NICs, VLANs, IPs, CPU, memory, and disk data from a local PowerShell export, with editable host mapping before import
• Proxmox import wizard for staging nodes, Linux bridges, QEMU VMs, LXC containers, MACs, VLAN tags/trunks, guest IPs, CPU, RAM, disks, boot flags, and Proxmox metadata from a local node export
• Controller API integrations for Proxmox VE, UniFi Network, TP-Link Omada, OPNsense, and Dockhand with encrypted stored credentials, background connection-status refresh, token-bound manual previews, non-destructive scheduled sync, DHCP range previews, and selectable device/guest imports
• Expanded demo data with multiple labs, MAC addresses, discovery states, custom templates/device types, multi-target monitors, room tech, documentation pages, device image examples, compute, and WiFi examples
• Production build of the frontend and backend
• Docker packaging for the frontend + API together

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.

OIDC uses the authorization-code flow with PKCE. Configure the provider redirect URI as APP_URL/api/auth/oidc/callback, or set OIDC_REDIRECT_URI explicitly when Rackpad is behind a proxy with a non-standard public URL. OIDC_ISSUER_URL must be the provider issuer, not the authorize URL or client settings page. Rackpad fetches OIDC_ISSUER_URL/.well-known/openid-configuration; if login returns a 502 with HTTP 404, test that exact discovery URL in a browser or with curl. For providers with per-application issuers, such as authentik, this usually means using the application/provider issuer path rather than the IdP root domain. Set OIDC_DEBUG=1 temporarily to log the discovery URL, redirect URI, token endpoint status, and JWKS URL used during sign-in.

Example Authentik configuration:

OIDC_ENABLED=1
OIDC_ISSUER_URL=https://authentik.example.com/application/o/rackpad
OIDC_CLIENT_ID=<client-id>
OIDC_CLIENT_SECRET=<client-secret>
OIDC_REDIRECT_URI=https://rackpad.example.com/api/auth/oidc/callback
OIDC_LABEL=Authentik
OIDC_DEFAULT_ROLE=viewer
OIDC_ADMIN_GROUPS=admin

In Authentik, set the redirect URI to https://rackpad.example.com/api/auth/oidc/callback and assign a signing key to the provider/application. For a single-admin private deployment you can set OIDC_DEFAULT_ROLE=admin; for shared installs, keep the default role at viewer and map admin/editor groups explicitly.

Discovery MAC/vendor enrichment needs layer-2 visibility from the Rackpad runtime. DISCOVERY_MAC_SCAN_MODE=auto tries arp-scan and nmap when the runtime can use them, then falls back to the OS neighbor/ARP cache. In Docker, MACs may remain unavailable on bridge networking, Docker Desktop, routed VLANs, VPNs, or containers without raw-socket capability; Rackpad will show scan diagnostics when that happens.

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

Recommended no-clone install from the published GHCR image:

sudo apt-get update
sudo apt-get install -y curl ca-certificates
curl -fsSL https://raw.githubusercontent.com/Kobii-git/Rackpad/main/scripts/install-docker.sh | bash

Use RACKPAD_TAG=latest if you want the newest stable GHCR image, RACKPAD_TAG=1.7.3 if you want a specific release, or RACKPAD_TAG=beta if you want the newest testing image:

curl -fsSL https://raw.githubusercontent.com/Kobii-git/Rackpad/main/scripts/install-docker.sh -o /tmp/install-rackpad.sh
RACKPAD_TAG=1.7.3 bash /tmp/install-rackpad.sh

Open:

http://SERVER_IP:3000

Manual no-clone compose install:

sudo mkdir -p /opt/rackpad
cd /opt/rackpad
sudo curl -fsSLo compose.yml https://raw.githubusercontent.com/Kobii-git/Rackpad/main/docker-compose.release.yml
sudo tee .env >/dev/null <<'EOF'
RACKPAD_IMAGE=ghcr.io/kobii-git/rackpad
RACKPAD_TAG=latest
RACKPAD_PORT=3000
MONITOR_INTERVAL_MS=300000
TRUST_PROXY=0
TRUSTED_HOSTS=
TRUSTED_ORIGINS=
EOF
sudo docker compose pull
sudo docker compose up -d

If Rackpad runs in Docker on Linux or inside a Proxmox LXC and Discovery cannot see the local subnet, use the host-network discovery compose variant:

sudo curl -fsSLo compose.host-discovery.yml https://raw.githubusercontent.com/Kobii-git/Rackpad/main/docker-compose.host-discovery.yml
sudo docker compose -f compose.host-discovery.yml pull
sudo docker compose -f compose.host-discovery.yml up -d

That variant runs with host networking plus the raw-network capabilities needed by ICMP/ARP-style scans. See Docker network discovery for the security trade-offs and manual compose snippet.

Build locally from a cloned repo only if you want to build from source:

docker compose up --build -d

The compose stack:

• exposes Rackpad on ${RACKPAD_PORT:-3000}
• stores SQLite data in the named volume rackpad_data
• serves the compiled frontend and API from the same container
• runs with a read-only root filesystem except for /data and /tmp
• uses /api/health for the container health check

To stop it:

docker compose down

Caution

docker compose down -v permanently removes the rackpad_data volume and its Rackpad database. Export a backup first and use this only when you intend to delete the installation's stored data.

To stop it and permanently remove the database volume:

docker compose down -v

Full Linux, Proxmox, and Windows install details, plus update steps, backups, git-clone/source-build options, and reverse-proxy settings live in INSTALL.md.

Linux test deploy

For a simple non-Docker Linux test deploy:

npm install
npm run build
PORT=3000 HOST=0.0.0.0 DATABASE_PATH=./rackpad.db npm start

If better-sqlite3 needs to compile during npm install, install build tools first:

sudo apt-get update
sudo apt-get install -y python3 make g++

Reverse proxy / TLS

For any public-facing or VPN-exposed deployment, put Rackpad behind a TLS reverse proxy and set the trusted proxy/origin environment values. TRUST_PROXY is the exact number of controlled proxy hops between the client and Rackpad: use 1 for the included single-proxy examples, or 2 through 10 for a controlled multi-proxy chain.

Recommended environment shape:

TRUST_PROXY=1
TRUSTED_HOSTS=rackpad.example.com
TRUSTED_ORIGINS=https://rackpad.example.com

Example proxy files are included in:

• deploy/Caddyfile.example
• deploy/nginx-rackpad.conf

The app already sets:

• Content-Security-Policy
• Strict-Transport-Security when the request arrives over HTTPS
• X-Frame-Options
• X-Content-Type-Options
• Referrer-Policy

So the main deployment job is to terminate TLS, overwrite the client-facing X-Forwarded-* headers, and keep the Rackpad application port reachable only through exactly the configured proxy chain. Do not enable TRUST_PROXY while clients can also connect directly to Rackpad; otherwise forwarded client identity and rate-limit buckets are not trustworthy. Invalid values fail closed to 0 (disabled), while true, yes, and on remain aliases for one hop.

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.