homelab-dashboard/README.md

# 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

```bash
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`:

```bash
cp .env.example .env
```

Bearbeite `.env` und setze die erforderlichen Variablen:

```env
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

```bash
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

```bash
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**:
   ```bash
   cp .env.example .env
   # Bearbeite .env mit deinen Werten
   ```

2. **Datenverzeichnis erstellen** (optional, wird automatisch erstellt):
   ```bash
   mkdir -p data
   ```

### Lokaler Docker-Test

```bash
# 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

```bash
# 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

```yaml
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:

```json
{
  "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](tailwind.config.ts) angepasst werden.

## Browser-Unterstützung

Das Dashboard funktioniert auf modernen Browsern:
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+

## Lizenz

MIT