spillebulle/homelab-manger repository overview

One page for the whole rack: switches, servers, BMCs and UPSes, each read over the protocol it already speaks.

SNMP · SSH · Redfish · CIMC XMLAPI · IPMI · USB HID · SQLite · one container, amd64 and arm64

⁠Install

# compose.yaml
services:
  homelab-manger:
    image: spillebulle/homelab-manger:0.8.0
    ports:
      - "8080:8080"
    environment:
      ADMIN_PASSWORD: pick-something
    volumes:
      - homelab-data:/data
    restart: unless-stopped

volumes:
  homelab-data:

docker compose up -d, then open http://localhost:8080⁠ and sign in as admin with the password you set. 0.8.0 is the current release; :latest also exists and moves with every release, so pin a version if you would rather choose when to upgrade.

Without compose:

docker run -d --name homelab-manger \
  -p 8080:8080 -e ADMIN_PASSWORD=pick-something \
  -v homelab-data:/data \
  spillebulle/homelab-manger:0.8.0

The same image is published to GitHub Container Registry as ghcr.io/spillebulle/homelab-manger.

Monitoring a USB-connected UPS needs two extra flags, --privileged and -v /dev:/dev:ro, because the adapter reads the UPS through a /dev/hidrawN node that changes when the UPS re-enumerates. Network-only installations do not need either.

The /data volume holds the database, the session secret and the credential-encryption key. Keep it across restarts, or sign-ins and stored device credentials are lost.

⁠Switches

D-Link DGS-3120, HPE OfficeConnect 1820 and anything generic enough to answer IF-MIB. Port status, PoE state and per-port power, VLAN membership, and a Connected tab listing every learned MAC with its port and its vendor from the IEEE registry.

Writes go over whichever surface the firmware actually supports, which is not always SNMP: PoE and VLANs on the DGS-3120 are driven over SSH, and the 1820 is driven through its web interface, because neither exposes them any other way.

⁠Servers and BMCs

HP iLO, Dell iDRAC, Huawei iBMC and Cisco UCS C-series. Inventory down to the DIMM, live sensors and per-PSU wattage, power actions, and a KVM launch that downloads the console file the firmware itself generates.

Cisco needs the right adapter for its firmware: cimc for anything before 3.0, cimc_redfish for 3.0 and later, which reads sensors far faster and adds BIOS and BMC detail the older interface never exposed.

⁠UPS and outage orchestration

A USB-connected UPS is read directly over the standard HID power device class, so most units work without NUT or any per-model configuration. Charge, runtime, load, watts and input voltage are stored as history and graphed over ranges from one hour to a custom window.

The Shutdown tab turns that into a plan: pick which machines to bring down, in what order, at what charge or runtime threshold, and how long to wait between each. Test plan walks the whole thing and sends the notifications without powering anything off.

⁠Publishing services

One form publishes an internal app at https://name.your-domain: the DNS record in Namecheap, the proxy host in Nginx Proxy Manager and the Let's Encrypt certificate are provisioned in order, with per-step status and a retry that picks up where it stopped.

Existing proxy hosts can be imported rather than recreated, renaming a service re-provisions its record and certificate, and a read-only Portainer connection fills in forward targets and shows each service's container state.

⁠Monitoring, events and notifications

Devices and published services can be registered as monitors in an external uptime monitor, with their notification channels and status-page membership managed from the same page. Kuvasz is the implemented provider. Every part of it reverses: pause a monitor, clear its channels, take it off a page, or delete it while leaving the remote monitor alone.

Every device also keeps a log of what happened to it: went offline, came back, went on battery, was shut down by the outage plan. Each device can post those to a Discord webhook, with separate switches for offline, UPS state and shutdown actions.

⁠Interface

Dense and quiet: 12 px type, hairline rules, one accent that only ever means selected, in hand or primary, and semantic colour reserved for state. Numbers are monospaced so a column lines up and a reading does not jitter as it changes. A chart draws a real gap where polling stopped rather than interpolating across it.

Dark, light, or follow the system. A theme is a file: import one, edit the colours, export it, and hand it to somebody else. The typeface and the icon set are bundled rather than fetched; Tailwind, Alpine and Chart.js still come from a CDN, so a machine with no route out gets an unstyled page.

⁠What is not there yet

⁠Configuration

These are the ones worth setting on the first run.

Every variable, and what is set in the interface rather than the environment, is in docs/configuration.md⁠.

• The HTTP API, its authentication and every endpoint: docs/api.md⁠.
• Setting up Nginx Proxy Manager, Namecheap, Portainer and Kuvasz: docs/integrations/⁠.
• Symptoms, causes and fixes, including the per-vendor ones: docs/troubleshooting.md⁠.

⁠Source and licence

Source, issues and releases: https://github.com/Spillebulle/HomeLab-Manger⁠

GNU General Public License v3.0, in LICENSE⁠. Archivo is bundled under the SIL Open Font Licence. Icons are Lucide, under the ISC licence.