Skip to content

niklask52t/hivehome

BranchesTags

Repository files navigation

HiveHome

Das ultimative WG-Management Tool mit WhatsApp-Integration (WAHA).

Full-Stack Web-App mit Dashboard, Finanzen, Putzplan, Einkaufsliste, Kochen, Kalender, Wartungs-Tickets, Gamification und einem WhatsApp-Bot der alles zusammenhält.

Features

  • Dashboard — Übersicht über Schulden, Putzplan, Einkaufsliste, anstehende Events, Punkte
  • Finanzen — Ausgaben erfassen, automatischer Split, Schulden-Optimierung, Monats-Charts
  • Putzplan — Automatische Wochen-Rotation, Erledigt/Bestätigen-System, Tauschbörse, Punkte
  • Einkaufsliste — Quick-Add, Kategorien, Inventar-Verwaltung mit MHD-Warnungen
  • Kochen — Wochenplan, Rezept-Datenbank, Koch-Freiwillige, Opt-Out
  • Kalender — Events (Party, Filmabend, Meeting, Geburtstag), Anwesenheits-Tracker
  • Wartung — Ticket-System mit Prioritäten, Paket-Tracking
  • Stats & Gamification — Leaderboard, Achievements/Badges, WG-Statistiken
  • Wiki — WG-internes Wissenssystem, Markdown-ähnlich, frei editierbar
  • Changelog — Versionshistorie direkt in der App
  • Settings — Bewohner-Verwaltung, WG-Regeln, Putzaufgaben-Config, WiFi-Infos
  • WhatsApp Bot — 15+ Befehle (!ausgabe, !schulden, !liste, !putzplan, !hilfe, ...)
  • Automatische Cron-Jobs — Putzplan-Generierung, Erinnerungen, Wochen-Recap, Monatsabrechnung
  • Kalender-Abo — iCal-Feed zum Einbinden in Google/Apple/Outlook Calendar
  • PWA — Installierbar als App auf dem Handy

Tech Stack

Komponente Technologie
Frontend Next.js 15, React 19, TypeScript
Styling Tailwind CSS, shadcn/ui, Lucide Icons
Backend Next.js API Routes, Server Actions
Datenbank PostgreSQL 16
ORM Prisma
WhatsApp WAHA (WhatsApp HTTP API)
Charts Recharts
Deployment Docker, Docker Compose

Schnellstart (Entwicklung)

Windows

git clone git@github.com:niklask52t/hivehome.git
cd hivehome
cp .env.example .env
dev.bat

Die dev.bat startet automatisch PostgreSQL (Docker), installiert Dependencies, richtet die Datenbank ein und startet den Dev-Server.

Linux / macOS

git clone git@github.com:niklask52t/hivehome.git
cd hivehome
cp .env.example .env

# PostgreSQL starten (z.B. via Docker)
docker run -d --name hivehome-dev-db -e POSTGRES_USER=hivehome -e POSTGRES_PASSWORD=hivehome -e POSTGRES_DB=hivehome -p 5432:5432 postgres:16-alpine

npm install
npx prisma db push
npx tsx prisma/seed.ts
npm run dev

Erreichbar unter http://localhost:3000 — Default PIN: 1234

Production Installation (Debian 13)

Voraussetzungen

  • Debian 13 (Trixie) Server (LXC, VM, oder Bare Metal)
  • Root/sudo Zugang
  • Mindestens 1 GB RAM, 5 GB Disk
  • Internetzugang
  • Reverse Proxy (Nginx/Caddy/Traefik) für SSL — wird hier nicht behandelt

1. Docker installieren

# System updaten
sudo apt update && sudo apt upgrade -y

# Docker installieren
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian trixie stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Docker ohne sudo nutzen
sudo usermod -aG docker $USER
newgrp docker

2. Projekt einrichten

cd /opt
sudo git clone git@github.com:niklask52t/hivehome.git
sudo chown -R $USER:$USER /opt/hivehome
cd /opt/hivehome

cp .env.example .env
nano .env

3. Environment konfigurieren

Bearbeite /opt/hivehome/.env:

# Datenbank (innerhalb Docker-Netzwerk)
DATABASE_URL="postgresql://hivehome:sicheres-passwort@db:5432/hivehome"

# WAHA
WAHA_API_URL="http://waha:3000"   # Wenn WAHA im gleichen Docker-Netzwerk
WAHA_API_KEY=""                     # Falls WAHA API Key gesetzt
WAHA_SESSION="default"

# WhatsApp Gruppe (Gruppen-ID von WAHA holen)
WG_GROUP="120363XXXXXXXXX@g.us"
WG_GROUP_BOT=""                     # Optional: separate Bot-Gruppe

# Secrets — UNBEDINGT ÄNDERN!
CRON_SECRET="$(openssl rand -hex 16)"
CALENDAR_TOKEN="$(openssl rand -hex 16)"
APP_URL="https://hivehome.deine-domain.de"

4. WAHA einrichten

Falls WAHA noch nicht läuft, die WAHA-Sektion in docker-compose.yml auskommentieren:

# In docker-compose.yml die waha: Sektion entkommentieren

Oder falls WAHA bereits separat läuft, den Webhook konfigurieren:

  • WAHA Dashboard öffnen
  • Webhook URL setzen: http://hivehome:3000/api/waha/webhook (im gleichen Docker-Netzwerk) oder http://SERVER-IP:3000/api/waha/webhook
  • Events: message

5. Starten

cd /opt/hivehome

# Bauen und starten
docker compose up -d --build

# Datenbank initialisieren (nur beim ersten Mal)
docker compose exec app npx prisma db push
docker compose exec app npx tsx prisma/seed.ts

# Logs prüfen
docker compose logs -f app

6. WhatsApp-Gruppe einrichten

  1. WhatsApp-Gruppe erstellen (z.B. "WG")
  2. WAHA Dashboard öffnen und QR-Code scannen
  3. Gruppen-ID herausfinden: 
    # Über WAHA API
curl http://localhost:3001/api/default/chats | jq '.[] | select(.isGroup) | {id, name}'
  4. Gruppen-ID in .env als WG_GROUP eintragen
  5. Container neustarten: docker compose restart app

7. Cron-Jobs

Die Cron-Jobs laufen automatisch via den cron-Container in docker-compose:

Job Zeitplan Beschreibung
weekly-cleaning Mo 9:00 Neuer Putzplan
cleaning-reminder Do 18:00 + Sa 12:00 Putz-Erinnerung
weekly-recap So 20:00 Wochen-Zusammenfassung
shopping-reminder Mi 17:00 + Sa 10:00 Einkaufs-Reminder
monthly-report 1. des Monats Monatsabrechnung

8. Kalender-Abo einrichten

HiveHome bietet einen iCal-Feed mit allen Events, Putzplänen und Essensplänen.

URL: https://hivehome.deine-domain.de/api/calendar/ical?token=DEIN_CALENDAR_TOKEN

  • Google Calendar: Einstellungen → Weitere Kalender → Per URL → URL einfügen
  • Apple Calendar: Ablage → Neues Kalenderabonnement → URL einfügen
  • Outlook: Kalender → Kalender hinzufügen → Aus dem Internet → URL einfügen

Der Kalender enthält:

  • Alle WG-Events (Partys, Filmabende, Meetings, Geburtstage)
  • Putzplan-Deadlines (Sonntag der jeweiligen Woche)
  • Essenspläne (wer kocht wann)

Management (update.sh)

HiveHome kommt mit einem interaktiven Management-Tool. Starte es einfach:

cd /opt/hivehome
./update.sh

Es öffnet sich ein Menü mit folgenden Optionen:

Option Beschreibung
1) Update Git pull, Container neu bauen, DB-Migration ausführen
2) Status Zeigt den Status aller Docker-Container
3) Neustart Startet alle Container neu
4) Logs Zeigt Live-Logs (Ctrl+C zum Beenden)
5) Backup Erstellt ein PostgreSQL-Dump in backups/
6) Reset Löscht ALLE Daten und setzt alles zurück (doppelte Bestätigung)
0) Beenden Beendet das Menü

Update durchführen

  1. ./update.sh starten
  2. Option 1 wählen
  3. Das Script macht automatisch:
    • Git Stash falls lokale Änderungen
    • git pull origin main
    • Stash wiederherstellen
    • docker compose build --no-cache app
    • docker compose up -d
    • npx prisma db push (Schema-Migration)

Backup erstellen

Backups werden als SQL-Dump in backups/ gespeichert:

backups/hivehome_20260319_143022.sql

Kompletter Reset

Option 6 löscht unwiderruflich alle Daten (Ausgaben, Schulden, Putzpläne, Benutzer, etc.). Erfordert zwei Bestätigungen: Erst RESET tippen, dann JA LÖSCHEN.

Konfiguration (.env)

Nach dem Klonen muss die .env-Datei konfiguriert werden. Alle Einstellungen:

Variable Pflicht Beschreibung Beispiel
DATABASE_URL Nein* PostgreSQL Connection String postgresql://hivehome:hivehome@db:5432/hivehome
WAHA_API_URL Nein URL der WAHA-Instanz http://waha:3000
WAHA_API_KEY Nein API-Key falls WAHA geschützt (leer lassen wenn kein Key)
WAHA_SESSION Nein WAHA Session Name default
WG_GROUP Ja** WhatsApp Gruppen-ID 120363XXXXXXXXX@g.us
WG_GROUP_BOT Nein Separate Bot-Gruppe (optional) (leer = nutzt WG_GROUP)
CRON_SECRET Ja Secret für Cron-Job-Endpunkte openssl rand -hex 16
CALENDAR_TOKEN Nein Token für iCal-Feed openssl rand -hex 16
APP_URL Nein Öffentliche URL der App https://hivehome.example.de

* Hat einen Default im docker-compose.yml ** Nur nötig wenn WhatsApp-Bot genutzt werden soll

Secrets generieren

# CRON_SECRET generieren
openssl rand -hex 16

# CALENDAR_TOKEN generieren
openssl rand -hex 16

Trage die generierten Werte in .env ein und starte den Container neu: docker compose restart app

WhatsApp Bot-Befehle

Befehl Beschreibung
!ausgabe 15€ Klopapier Ausgabe erfassen + Split
!schulden Offene Schulden anzeigen
!liste Einkaufsliste anzeigen
!brauche Milch, Brot, Eier Artikel zur Liste hinzufügen
!ich geh Rewe Einkaufen gehen (Liste bekommen)
!putzplan Putzplan der Woche
!erledigt Bad Putzaufgabe als erledigt markieren
!essensplan Essensplan der Woche
!esse nicht mit Heute nicht mitessen
!stats Leaderboard anzeigen
!achievements Eigene Achievements
!umfrage 'Frage?' Ja Nein Umfrage erstellen
!anonym Text Anonyme Nachricht posten
!regeln WG-Regeln anzeigen
!wifi WLAN-Infos
!wer ist da Anwesenheit
!problem Text Wartungs-Ticket erstellen
!paket Name Info Paket ankündigen
!hilfe Alle Befehle

Projektstruktur

hivehome/
├── prisma/
│   ├── schema.prisma       # 24 Datenbank-Modelle
│   └── seed.ts              # Seed-Daten
├── src/
│   ├── app/
│   │   ├── (dashboard)/     # Alle Feature-Seiten
│   │   ├── api/             # Auth, WAHA Webhook, Cron, iCal
│   │   └── login/           # PIN-Login
│   ├── components/ui/       # shadcn/ui Komponenten
│   └── lib/
│       ├── db.ts            # Prisma Client
│       ├── utils.ts         # Utility-Funktionen
│       └── waha/            # WAHA Client + Bot-Commands
├── docker-compose.yml
├── Dockerfile
├── update.sh
├── dev.bat                   # Windows Dev-Setup
└── .env

Lizenz

Private Nutzung.

Last reviewed: 2026-04-11

About

HiveHome — Das ultimative WG-Management Tool mit WhatsApp-Bot, Finanzen, Putzplan, Gamification & mehr

Topics

docker typescript pwa nextjs postgresql whatsapp prisma tailwindcss hivehome

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages