Homie

A clean, lightweight Proxmox VE homelab monitoring dashboard.

Features

• Live Node Metrics – Real-time sparkline KPI cards for CPU & I/O wait, load average, network I/O, memory, swap, IO pressure, and root storage.
• Solar-Aware Auto Theme – Automatically transitions between light and dark modes based on astronomical sunrise and sunset calculation (SunCalc), staying in light mode during daytime (after 09:00) and dark mode during evenings and nights.
• Dynamic Timeframe Cycling – Automatically alternates between 1-hour (fine-grained live telemetry) and 24-hour (daily trend overview) Proxmox RRD metrics every 2 minutes, with a 60-second background refetch interval for hands-free monitoring.
• Modern Full-Stack – Built with React 19, TanStack Start, TanStack Router, TanStack Charts, HeroUI, and Tailwind CSS v4.
• Fast Unified Toolchain – Development, linting, testing, and bundling powered by Vite+ (vp).
• Production-Ready – Self-contained standalone Nitro server output with Docker support.

Getting Started

Prerequisites

• pnpm (v12+)
• Vite+ CLI (vp)

Development

1. Install dependencies:

   pnpm install

2. Configure environment variables:

   cp .env.example .env

   Add your Proxmox API token, base URL, and location in .env:

   PROXMOX_BASE_URL="https://example.com/api2/json/nodes/homelab/rrddata"
   PROXMOX_TOKEN="PVEAPIToken=user@pam!tokenid=secret"
   
   # Coordinates & morning hour for auto theme switching
   LATITUDE="53.219"
   LONGITUDE="6.566"
   MORNING_START_HOUR="9"

3. Start the development server:

   vp dev

   Open http://localhost:8080 in your browser.

Docker Deployment

Using Pre-built Image

Pull the image from GitHub Container Registry:

docker pull ghcr.io/stybo/homie:latest

Run directly with Docker:

docker run -d \
  --name homie \
  -p 8080:8080 \
  -e PROXMOX_BASE_URL="https://example.com/api2/json/nodes/homelab/rrddata" \
  -e PROXMOX_TOKEN="PVEAPIToken=user@pam!tokenid=secret" \
  -e LATITUDE="53.219" \
  -e LONGITUDE="6.566" \
  -e MORNING_START_HOUR="9" \
  ghcr.io/stybo/homie:latest

Or using Docker Compose:

docker compose -f compose.prod.yaml up -d

Building Locally

To build and run locally with Docker Compose:

docker compose up -d --build

The app will be available at http://localhost:8080.

Commands

Command	Description
vp dev	Start development server
vp check	Run linter, typecheck, and formatting checks
vp check --fix	Auto-fix formatting and linting errors
vp build	Build standalone production server (.output/)