Homelab Dashboard

A private dashboard for homelab service links, uptime, infrastructure stats, media libraries, and operational shortcuts.

Development

npm install
npm run dev

The Vite dev server handles the frontend. Production runs through the Node backend so API tokens stay server-side.

Build

npm run build

Production

Example docker-compose.yml:

services:
  homelab-dashboard:
    image: registry.example.com/YOUR-USER/homelab-dashboard:latest
    container_name: homelab-dashboard
    restart: unless-stopped
    environment:
      - DATA_DIR=/data
      - PORT=3000
    ports:
      - "3000:3000"
    volumes:
      - homelab-dashboard-data:/data

volumes:
  homelab-dashboard-data:

Start or update the container:

docker compose pull
docker compose up -d

The container listens on port 3000. On first launch, open http://YOUR-VM-IP:3000/admin to create the initial admin user.

It is ready to run behind an nginx reverse proxy. See docs/nginx-proxy.md. Container publishing notes live in docs/container-registry.md.

To build locally instead of using the Forgejo container registry:

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

Admin Settings

Open /admin after first launch to create the initial admin user. After registration, use the admin dashboard to configure module URLs and tokens.

The admin dashboard stores the admin user, module settings, notification history, and audit history in a SQLite database at /data/dashboard.db. Existing settings.json, notification-history.json, and audit-log.json files are imported into the database automatically on first startup after upgrade. Secret fields are saved server-side and are not returned to the browser after saving.

The dashboard includes local layout profiles, wallboard presets, mobile-friendly card layouts, theme presets, card drill-downs, a SQLite-backed event timeline, server-side Uptime Kuma and diagnostic history samples with retention controls, module-specific diagnostic guidance, running version visibility, redacted settings export, history export/clear controls, and optional webhook alert notifications. Browser-local items such as layout, theme, uptime ticks, and older fallback timeline data can be cleared from the Dashboard Recovery section.

The admin dashboard also includes a White Label section for changing the header title, subtitle, eyebrow text, logo URL, and module documentation link base URL.

See the Forgejo wiki for module-by-module setup notes, including where to find each URL, API key, and token:

https://forgejo.example.com/YOUR-USER/homelab-dashboard/wiki/Module-Setup

Project Shape

• src/App.tsx renders the dashboard shell and service cards.
• src/App.css contains the dashboard styling.
• server/server.js serves the production app, WebSocket updates, and server-side integration endpoints.
• docs/integrations.md tracks integration setup and implementation notes.