Homelab Dashboard

Ein modernes, responsives Dashboard für die Verwaltung von Homelab-Diensten, gebaut mit Next.js 15, TypeScript, Tailwind CSS und NextAuth.js.

Features

✨ Moderne Benutzeroberfläche

• Elegantes Dark/Light Mode Design
• Responsive Grid-Layout für alle Bildschirmgrößen
• Smooth Animations und Übergänge

🔐 Sichere Admin-Authentifizierung

• Session-basierte Authentifizierung mit NextAuth.js
• Benutzername/Passwort Login
• Sichere Passwort-Hashing mit bcryptjs
• Automatisches Logout bei Inaktivität

🎯 Service-Management

• Service-Karten mit Name, Beschreibung und Status
• Farbcodierter Status-Indikator (Online, Warnung, Offline)
• Direkte Links zu Services
• Pulsierender Status-Punkt für visuelle Rückmeldung

⚙️ Admin-Funktionen

• Globale Konfigurationsoptionen (Polling, Theme, Logging)
• Service-Editor mit Healthcheck-Konfiguration
• Server-seitige Test-Funktion für Dienste
• Automatische und manuelle Backups
• Konfiguration Import/Export
• Dirty-State-Erkennung mit Undo-Funktionalität

📱 Mobile-First Design

• Optimiert für Smartphones, Tablets und Desktop
• Touch-freundliche Buttons
• Flexibles Grid-System

Installation & Setup

Voraussetzungen

• Node.js 18+ installiert
• npm oder yarn

Schritt 1: Abhängigkeiten installieren

npm install

Schritt 1.1: Datenbank wird automatisch erstellt

Es ist keine externe Datenbank und kein Setup-Script nötig. Die App verwendet eine lokale SQLite-Datenbank (better-sqlite3). Die Datenbankdatei wird beim ersten Start automatisch unter dem in .env definierten DATA_DIR angelegt (Standard: ./data/database.db).

Schritt 2: Umgebungsvariablen konfigurieren

Kopiere .env.example zu .env:

cp .env.example .env

Bearbeite .env und setze die erforderlichen Variablen:

PORT=3000
HOSTNAME=0.0.0.0
NEXTAUTH_SECRET=generate-with-openssl-rand-base64-32
DATA_DIR=./data
DATABASE_FILE=database.db

Schritt 3: First-Run-Setup (Admin-Benutzer anlegen)

Beim ersten Start ist /setup verfügbar, solange noch kein Benutzer existiert. Dort kannst du den ersten Admin-Benutzer anlegen. Danach ist /setup gesperrt und du nutzt /login.

Schritt 4: Entwicklungsserver starten

npm run dev

Der Server läuft unter http://localhost:3000

Login & Admin-Zugang

1. Navigiere zu http://localhost:3000/setup, wenn noch kein Benutzer existiert.
2. Lege den ersten Admin-Benutzer an (Benutzername und Passwort werden in der Datenbank gespeichert, Passwort wird mit bcryptjs gehasht).
3. Danach melde dich unter http://localhost:3000/login an.
4. Nach erfolgreichem Login wirst du zu /admin weitergeleitet.

Speicherort der Datenbank

Die SQLite-Datenbankdatei liegt standardmäßig unter ./data/database.db (relativ zum Projektverzeichnis oder /app/data/database.db im Docker-Container). Der Pfad kann über DATA_DIR und DATABASE_FILE in der .env angepasst werden.

Admin-Interface

Im Admin-Bereich kannst du:

• Globale Einstellungen bearbeiten (Polling-Intervall, Theme, Logging-Level)
• Services verwalten (Hinzufügen, Bearbeiten, Löschen)
• Healthchecks konfigurieren (Timeout, akzeptierte Status-Codes)
• Services testen (direkt von der Admin-UI aus)
• Backups erstellen und wiederherstellen
• Konfiguration exportieren und importieren

Projekt-Struktur

homelab-dashboard/
├── app/
│   ├── api/
│   │   ├── auth/[...nextauth]/      # NextAuth API Route
│   │   ├── config/[[...path]]/      # Config Management API
│   │   └── status/                  # Service Status Check API
│   ├── admin/                       # Admin-Interface
│   ├── login/                       # Login-Seite
│   ├── layout.tsx                   # Root Layout
│   └── page.tsx                     # Dashboard
├── auth.ts                          # NextAuth Konfiguration
├── middleware.ts                    # Auth-Middleware
├── src/
│   ├── app/
│   │   ├── api/                     # API-Routen
│   │   └── components/admin/        # Admin-Komponenten
│   ├── lib/
│   │   ├── config/                  # Konfigurationsverwaltung
│   │   ├── monitor/                 # Service-Monitoring
│   │   └── auth/                    # Auth-Hilfsfunktionen
│   └── types/                       # TypeScript Typen
├── scripts/
│   └── generate-password-hash.js   # Passwort-Hash Generator
├── tailwind.config.ts              # Tailwind Konfiguration
├── tsconfig.json                   # TypeScript Konfiguration
└── package.json                    # Abhängigkeiten

Verfügbare Commands

npm run dev       # Entwicklungsserver starten
npm run build     # Produktions-Build erstellen
npm start         # Produktions-Server starten
npm run lint      # ESLint ausführen

Umgebungsvariablen

Variable	Beschreibung	Beispiel
PORT	Port für den Server	3000
HOSTNAME	Server-Hostname	0.0.0.0
NEXTAUTH_SECRET	Secret für JWT-Signing	openssl rand -base64 32

Sicherheit

• ✅ Session-basierte Authentifizierung (nicht Token-basiert)
• ✅ Sichere Passwort-Hashing mit bcryptjs
• ✅ Geschützte API-Routen (nur für authentifizierte Benutzer)
• ✅ CSRF-Schutz durch NextAuth
• ✅ Sichere HTTP-Only Cookies
• ✅ Keine Speicherung sensibler Daten im Frontend

Für Produktionsumgebungen beachte:

1. Starkes Passwort wählen (mindestens 12 Zeichen, Umlaute, Sonderzeichen)
2. NEXTAUTH_SECRET mit openssl rand -base64 32 generieren
3. HTTPS aktivieren in der Produktionsumgebung
4. Admin-Seite mit zusätzlichem Firewall-Schutz (Optional)
5. Regelmäßige Backups durchführen

Konfigurationsdateien

config.json

| Warnung | 🟡 Gelb | Service läuft, aber mit Performance-Problemen | | Offline | 🔴 Rot | Service ist nicht erreichbar |

Docker Deployment

Vorbereitung

1. Umgebungsvariablen setzen:

   cp .env.example .env
   # Bearbeite .env mit deinen Werten
   

2. Datenverzeichnis erstellen (optional, wird automatisch erstellt):

   mkdir -p data
   

Lokaler Docker-Test

# Build und starte mit docker-compose
docker-compose up --build

# Oder manuell:
docker build -t homelab-dashboard .
docker run -p 3000:3000 \
  -e NEXTAUTH_SECRET=your-secret \
  -e DATA_DIR=/app/data \
  -v $(pwd)/data:/app/data \
  homelab-dashboard

Produktions-Deployment

# Build für Produktion
npm run build

# Mit Docker Compose starten
docker-compose up -d

# Container stoppen
docker-compose down

Unraid-Installation

1. Docker-Tab in Unraid öffnen

2. Neuen Container hinzufügen:

   • Name: homelab-dashboard
   • Repository: dein-registry/homelab-dashboard:latest (oder build lokal)
   • Docker Hub Search: Suche nach deinem Image

3. Port-Mapping:

   • Container Port: 3000
   • Host Port: 3000 (oder gewünschter Port)

4. Volume-Mappings (für persistente Daten):

   • Container Path: /app/data
   • Host Path: /mnt/user/appdata/homelab-dashboard/data

5. Environment Variables:

   • NEXTAUTH_SECRET: Dein generierter Secret (openssl rand -base64 32)
   • DATA_DIR: /app/data
   • NODE_ENV: production

6. Container starten

Persistente Daten

Unter /app/data werden gespeichert:

• config.json - App-Konfiguration
• services.json - Service-Konfiguration
• backups/ - Backup-Dateien
• database.db - SQLite-Datenbank für Benutzer

Docker Compose für Unraid-ähnliche Umgebungen

version: '3.8'
services:
  homelab-dashboard:
    image: homelab-dashboard:latest
    container_name: homelab-dashboard
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      - HOSTNAME=0.0.0.0
      - NEXTAUTH_SECRET=your-nextauth-secret
      - DATA_DIR=/app/data
    volumes:
      - /mnt/user/appdata/homelab-dashboard/data:/app/data

Troubleshooting

• Container startet nicht: Logs prüfen mit docker-compose logs
• Daten nicht persistent: Volume-Mapping überprüfen
• Authentifizierung fehlt: NEXTAUTH_SECRET setzen

Konfiguration

Services bearbeiten

Bearbeite src/data/services.json für JSON-basierte Konfiguration oder src/data/services.ts für TypeScript-basierte Konfiguration.

App-Konfiguration

Bearbeite config.json im Projektroot, um Titel, Beschreibung und andere Einstellungen anzupassen:

{
  "title": "Mein Homelab Dashboard",
  "subtitle": "Live-Status aller verwalteten Dienste",
  "description": "Live-Monitoring-Dashboard für mein Homelab",
  "servicesFile": "src/data/services.json",
  "refreshInterval": 30000,
  "categories": [
    "Infrastruktur",
    "Smart Home",
    "Medien",
    "Dokumente"
  ]
}

Environment Variables

Kopiere .env.example zu .env und passe die Werte an:

• PORT: Port für den Server (Standard: 3000)
• HOSTNAME: Hostname binding (Standard: 0.0.0.0)

Ports

• 3000: Haupt-HTTP-Port der Anwendung | Warning | 🟡 Orange | Service hat Probleme, läuft aber | | Offline | 🔴 Rot | Service ist nicht erreichbar |

Styling & Anpassungen

Das Projekt nutzt Tailwind CSS für Styling. Eigene Farben und Konfiguration können in tailwind.config.ts angepasst werden.

Browser-Unterstützung

Das Dashboard funktioniert auf modernen Browsern:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Lizenz

MIT