Skip to content

RackPad ​

RackPad keeps private infrastructure inventory, integration settings, and native database snapshots on the operations VM.

Prepare the guest using the host setup guide. Host-specific AI commands and private recovery details are in RackPad · Internal Operations.

Access and configuration ​

SettingThis homelab
Host address10.120.40.100
Domainrack.home.rwk.me
Normal accesshttps://rack.home.rwk.me
Direct accesshttp://10.120.40.100:8086
Project directory/docker/rackpad

For another homelab, use your own host address, domain, timezone, paths, and network policy. The addresses above describe internal access; the dashboard does not require a public router port forward.

Create the project ​

Run as a deployment account with Docker access on the prepared guest:

sh
sudo install -d -o "$(id -u)" -g "$(id -g)" -m 0750 /docker/rackpad
cd /docker/rackpad

Create compose.yaml with the following configuration. It is a documented example of the repository's pinned deployment, not a second deployment source file:

yaml
name: rackpad

services:
  rackpad:
    image: ghcr.io/kobii-git/rackpad:1.8.6@sha256:b8a6f3b3c90b70ed10893e1c2347c974db2c21d3d73ea80e603d616f0e4fff91
    container_name: rackpad
    init: true
    environment:
      NODE_ENV: production
      HOST: 0.0.0.0
      PORT: "3000"
      DATABASE_PATH: /data/rackpad.db
      APP_URL: https://rack.home.rwk.me
      TRUST_PROXY: 10.120.40.101
      TRUSTED_HOSTS: rack.home.rwk.me
      TRUSTED_ORIGINS: https://rack.home.rwk.me
      RACKPAD_SECRET_KEY: ${RACKPAD_SECRET_KEY}
      RACKPAD_NATIVE_BACKUP_DIR: /backups
      MCP_ENABLED: "0"
      SNMP_TRAP_ENABLED: "0"
      SNMP_INVENTORY_SYNC: "0"
      OIDC_ENABLED: "0"
      TZ: ${TZ}
    ports:
      - "${SERVER_IP}:8086:3000"
    volumes:
      - type: bind
        source: ./data
        target: /data
        bind:
          create_host_path: false
      - type: bind
        source: ./backups
        target: /backups
        bind:
          create_host_path: false
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    mem_limit: 2g
    cpus: 1.0
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    restart: unless-stopped

Create .env alongside it:

dotenv
SERVER_IP=10.120.40.100
TZ=America/Chicago
RACKPAD_SECRET_KEY=

Replace blank secrets and example credentials before starting. SERVER_IP must be an address assigned to the Docker host. Preserve existing keys and data when updating an installation. Protect the file with chmod 600 .env and keep it out of Git.

Configure identity and local storage ​

Generate an independent, persistent RACKPAD_SECRET_KEY for the fresh installation, for example with openssl rand -hex 32 in a private terminal, and store it securely. Restore the original key during recovery; it protects stored integration credentials.

Set APP_URL, TRUSTED_HOSTS, and TRUSTED_ORIGINS to your dashboard URL and hostname. Set TRUST_PROXY to your actual reverse proxy address, not a generic hop count. Keep unused MCP, OIDC, and SNMP features disabled until intentionally configured.

The pinned image runs as UID 10001, GID 999; verify the image identity when changing releases. Create both bind directories before starting:

sh
sudo install -d -o 10001 -g 999 -m 0700 data backups

Compose refuses to create missing bind paths. The root filesystem is read-only and /tmp is temporary; persistent state belongs in the explicit data and backup mounts.

Restrict the backend ​

Before starting, configure the host firewall so only your reverse proxy can reach the published backend. The lab uses an idempotent Docker DOCKER-USER filter matching the original destination 10.120.40.100:8086, permitting source 10.120.40.101 and dropping other forwarded traffic. Host-local administration remains available.

For Docker's iptables backend, create restrict-backend in the project directory:

sh
#!/bin/sh
set -eu

# Match the original published destination before Docker's DNAT.
# Other Docker services and the host's own connections are unaffected.
iptables -w -N DOCKER-USER 2>/dev/null || true
iptables -w -N RACKPAD-BACKEND 2>/dev/null || true
iptables -w -C RACKPAD-BACKEND -s 10.120.40.101/32 -j RETURN 2>/dev/null ||
  iptables -w -A RACKPAD-BACKEND -s 10.120.40.101/32 -j RETURN
iptables -w -C RACKPAD-BACKEND -j DROP 2>/dev/null ||
  iptables -w -A RACKPAD-BACKEND -j DROP
iptables -w -C DOCKER-USER -p tcp -m conntrack --ctorigdst 10.120.40.100 --ctorigdstport 8086 --ctdir ORIGINAL -j RACKPAD-BACKEND 2>/dev/null ||
  iptables -w -I DOCKER-USER 1 -p tcp -m conntrack --ctorigdst 10.120.40.100 --ctorigdstport 8086 --ctdir ORIGINAL -j RACKPAD-BACKEND

Change the proxy source, original host destination, and port for another installation. Create rackpad-backend-firewall.service alongside it:

ini
[Unit]
Description=Restrict RackPad Docker backend to Nginx Proxy Manager
Before=docker.service
PartOf=docker.service

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/rackpad-restrict-backend
RemainAfterExit=yes

[Install]
WantedBy=docker.service

Install and enable the persistent filter before starting the application:

sh
sudo install -m 0755 restrict-backend /usr/local/sbin/rackpad-restrict-backend
sudo install -m 0644 rackpad-backend-firewall.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now rackpad-backend-firewall.service

The script is idempotent and leaves unrelated chains intact. The unit runs before Docker and follows its restarts. Inspect existing rules first, and adapt the approach if Docker uses a different firewall backend. Never flush shared Docker chains. A router rule alone cannot protect backend traffic between peers on the same VLAN.

Start and verify ​

Run only this Compose project:

sh
cd /docker/rackpad
docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 180
docker compose ps
docker compose logs --tail=100 rackpad

Keep logs private. Do not rerun the base guest provisioner to install or update one service; it upgrades the host and restarts Docker.

Configure DNS and HTTPS ​

Make rack.home.rwk.me resolve to Nginx Proxy Manager (10.120.40.101 in this lab). Add a proxy host:

SettingValue
Domainrack.home.rwk.me
Schemehttp
Backend10.120.40.100
Port8086
WebSocketsEnabled
CertificateA certificate covering rack.home.rwk.me
Force SSL / HTTP/2Enabled

Use your own domain and certificate on another homelab. Apply a LAN/VPN access list appropriate to your users. A proxy access list does not restrict clients connecting directly to a backend port; use network filtering when the backend must be proxy-only.

Use a custom / location that overwrites X-Forwarded-Host with $host, X-Forwarded-For with $remote_addr, and X-Forwarded-Proto with $scheme. Trust only the actual proxy and intended hostname/origin; do not accept arbitrary client-supplied forwarding headers.

Check both paths:

sh
curl --fail --silent --show-error --output /dev/null http://10.120.40.100:8086/api/health
curl --fail --silent --show-error --output /dev/null https://rack.home.rwk.me/api/health

Add the HTTPS health endpoint to Uptime Kuma, using TLS validation and a suitable check interval. Monitoring on the same VM cannot independently report that VM's outage.

Initialize inventory and backups ​

Open the HTTPS dashboard and complete initial administrator setup. Add sites, racks, and inventory deliberately; a fresh deployment has no controller integration configured. Use dedicated integration credentials and test the intended connection before enabling discovery or synchronization.

In Users → Backup and release state, configure native snapshots every 24 hours and retain seven files, or choose your own retention. Snapshots use SQLite's backup mechanism; copying the live database file is unsafe. These snapshots are local until copied off-host.

Check login/logout, saved inventory after restart, and rejection of unauthenticated inventory requests. From another LAN device, direct backend access must fail while allowed HTTPS access works. Test excluded networks too.

Maintenance and recovery ​

Updates are manual in this lab; RackPad is not part of the operations auto-deployment runner. Before updating, retain a native snapshot, matching configuration, encryption key, and exact image. Migrations are forward-only: rollback requires the previous image and its paired database. Restore into an empty data directory with correct ownership, without stale WAL/SHM files. Keep protected off-host VM backups; local snapshots alone do not cover VM loss.

The deployed files remain in the private homelab source directory. Keep these instructions aligned with source changes. Review release notes and preserve a recovery point before updating pinned images. After maintenance, repeat the checks and verify the main application function.