TeamPulse

WhatsApp-basiertes Anwesenheits-Management für Teams. Erstelle Trainings, Turniere und andere Events, versende automatisch Umfragen per WhatsApp (via WAHA) und sammle die Antworten übersichtlich im Dashboard.

Features

• Login-System: Geschütztes Dashboard mit Passwort-Pflichtänderung beim ersten Login
• Dashboard: Startseite mit Quick-Stats, nächstes Event mit Live-Countdown, aktive Umfragen mit Fortschrittsbalken, Antwort-Trend
• Event-Management: Wiederkehrende Trainings und einmalige Events (Turniere, Sondertermine) erstellen und verwalten
• Event-Beschreibung: Optionales Freitextfeld pro Event — wird überall angezeigt (Umfrage, Erinnerungen, Ergebnisse, Gruppenbeschreibung, Dashboard)
• Keine manuelle Kontaktverwaltung: Teilnehmer werden automatisch aus der WhatsApp-Gruppe synchronisiert
• Gruppen-Umfrage: Umfrage wird als native WhatsApp-Poll in die Gruppe geschickt (Tap-to-Vote)
• Antwort-Sammlung: Übersichtliche Darstellung aller Zu-/Absagen, gruppiert nach Status — inkl. Kommentare/Begründungen für alle Stimmen
• Kommentare: Nach jeder Abstimmung (Ja/Nein/Vielleicht) wird eine Follow-up-PN gesendet mit optionaler Kommentar-Möglichkeit (5-Min-Fenster)
• Stimmänderung: Bei Ummeldung wird der alte Kommentar in der PN angezeigt — bleibt erhalten wenn kein neuer geschrieben wird
• Treffenszeit & Ende: Optionale Treffenszeit (muss vor Event liegen) und Endzeit (muss nach Event liegen) — in allen Nachrichten angezeigt
• Umfrage-Versand: "Stunden vor Event" oder festes Datum (Standard: 24h vor Event)
• Abstimmungsfrist: "Stunden vor Event" oder festes Datum — Umfrage schließt und Ergebnis wird sofort gepostet (Standard: 1h vor Event)
• Automatische Absage: Optional pro Event — bei zu wenigen Zusagen wird automatisch eine Absage in die Gruppe gesendet
• Wiederkehrende Ausnahmen: Einzelne Termine bei wiederkehrenden Events aussetzen (z.B. Feiertage)
• Gruppen-Posting: Ergebnis-Text + Chart in die Gruppe — auch manuell mehrfach möglich
• Auto-Pin: Aktive Umfragen werden in der Gruppe angepinnt (entpinnt beim Schließen), Ergebnis-Posts werden angepinnt (entpinnt nach Event-Ende)
• Bot-Hinweis: Alle automatischen Nachrichten sind mit "🤖 Automatisch generierte Nachricht von TeamPulse" gekennzeichnet
• Frist verlängern: Abstimmungsdeadline direkt im Dashboard verschieben
• Automatische Gruppenbeschreibung: WhatsApp-Gruppenbeschreibung wird bei jeder Änderung automatisch aktualisiert — zeigt nächstes Event, Status aller Mitglieder (Zusagen, Absagen mit Grund, Vielleicht, Ausstehend) + statische Textblöcke. Wechselt automatisch zum nächsten Event sobald das aktuelle endet (end_time) bzw. beginnt (event_time)
• Beschreibungs-Tab: Statische Textblöcke erstellen (oberhalb/unterhalb), Vorschau, manuelles Aktualisieren
• Statistiken-Tab: Antwortquote & Ja/Nein/Vielleicht/Offen pro Mitglied — nur abgeschlossene Umfragen
• Gruppen-Übersicht (DEV_MODE): Footer-Tab zeigt alle WhatsApp-Gruppen mit ID und Kopieren-Button — zum einfachen Nachschlagen der GROUP_CHAT_ID
• Erinnerungen (konfigurierbar pro Event):
  • 2x Abstimmungs-Erinnerung: Standard 120 Min + 15 Min vor Fristablauf an alle Nicht-Voter (privat)
  • Start-Erinnerung: Standard 60 Min vor Event an alle Zusager (privat, mit Event-Name + dynamischer Zeitangabe)
• Zu-spät-Benachrichtigung: Wer nach Fristablauf abstimmt, wird per PN informiert dass die Abstimmung beendet ist
• Manuelle Stimmkorrektur: Admin kann Stimmen im Dashboard ändern (auch bei archivierten Umfragen) — Mitglied wird per PN benachrichtigt, Statistiken werden aktualisiert
• Neu senden (Reset): Aktive Umfragen können komplett zurückgesetzt und als neue WhatsApp-Umfrage neu gesendet werden — alle bisherigen Stimmen werden gelöscht
• Kompakte Umfrage-Übersicht: In der Gruppenbeschreibung wird das nächste Event voll detailliert angezeigt, weitere aktive Umfragen als kompakter Einzeiler mit Emoji-Counts (✅X ❌X 🤷X)

Tech Stack

• Backend: Node.js + Express
• Frontend: Vanilla HTML/CSS/JS (leichtgewichtig, kein Build-Step)
• Datenbank: SQLite (via libsql)
• WhatsApp: WAHA (WhatsApp HTTP API)
• Scheduler: node-cron für zeitgesteuerte Nachrichten
• Auth: bcrypt + express-session

Standard-Login

Benutzer	Passwort
admin	admin

Beim ersten Login muss das Passwort geändert werden. Der Benutzername kann optional angepasst werden.

Umgebungsvariablen

Variable	Beschreibung	Beispiel
PORT	Server-Port	3000
SESSION_SECRET	Session-Verschlüsselung (zufälliger String)	a1b2c3d4e5...
WAHA_API_URL	URL der WAHA-Instanz	http://localhost:3000
WAHA_API_KEY	API-Key für WAHA	your-api-key
WAHA_SESSION	WAHA Session-Name	default
GROUP_CHAT_ID	WhatsApp Gruppen-ID für Ergebnis-Posts	120363xxx@g.us
DEV_MODE	Zeigt Gruppen-Tab im Footer (zum ID-Nachschlagen)	false

---

Produktiv-Installation auf Debian 13 (Trixie)

Komplette Schritt-für-Schritt-Anleitung für eine produktive Installation mit Autostart.

1. System vorbereiten

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential python3

2. Node.js 24 LTS installieren

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node -v  # sollte v24.x zeigen

3. Systembenutzer anlegen

sudo useradd -r -m -s /bin/bash teampulse

4. Git-Credentials speichern

Damit beim git pull nicht jedes Mal Benutzername und Passwort (bzw. Token) abgefragt werden:

# Credentials dauerhaft auf dem Server speichern
sudo -u teampulse git config --global credential.helper store

Beim ersten git clone oder git pull werden die Zugangsdaten abgefragt und danach in ~/.git-credentials gespeichert. Für private Repos einen Personal Access Token (PAT) statt Passwort verwenden:

GitHub -> Settings -> Developer settings -> Personal access tokens -> Tokens (classic) -> Generate new token (Scope: repo)

Beim Login dann den Token als Passwort eingeben.

5. TeamPulse klonen und installieren

sudo -u teampulse bash -c '
  cd /home/teampulse
  git clone https://github.com/niklask52t/TeamPulse.git app
  cd app
  npm install --omit=dev
  cp .env.example .env
'

6. Konfiguration anpassen

sudo -u teampulse nano /home/teampulse/app/.env

Inhalt:

PORT=3000
SESSION_SECRET=HIER_EINEN_LANGEN_ZUFAELLIGEN_STRING_EINSETZEN
WAHA_API_URL=http://localhost:3000
WAHA_API_KEY=dein-waha-api-key
WAHA_SESSION=default
GROUP_CHAT_ID=120363xxx@g.us

Tipp: WAHA_API_URL ist die URL der laufenden WAHA-Instanz. Wenn WAHA auf dem gleichen Server läuft, trägst du dort deren IP/Port ein (z.B. http://localhost:3000).

GROUP_CHAT_ID herausfinden

Am einfachsten: Im TeamPulse-Dashboard auf den Gruppen-Tab im Footer klicken — dort werden alle WhatsApp-Gruppen mit Name und ID angezeigt. Die gewünschte ID kopieren und in die .env eintragen.

Alternativ per CLI:

curl http://<WAHA-IP>:3000/api/default/groups

Die gesuchte ID hat immer das Format 120363xxxxxxxxx@g.us.

SESSION_SECRET generieren

Einfach einen der folgenden Befehle ausführen und den Output in die .env kopieren:

# Option 1 – openssl (empfohlen)
openssl rand -hex 32

# Option 2 – Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Direkt in die .env schreiben (ersetzt den Platzhalter):
sed -i "s/HIER_EINEN_LANGEN_ZUFAELLIGEN_STRING_EINSETZEN/$(openssl rand -hex 32)/" /home/teampulse/app/.env

7. Kurzer Test

sudo -u teampulse bash -c 'cd /home/teampulse/app && node server.js'
# Sollte "TeamPulse running on http://0.0.0.0:3000" ausgeben
# Mit Ctrl+C beenden

8. Systemd-Service erstellen

sudo tee /etc/systemd/system/teampulse.service > /dev/null << 'EOF'
[Unit]
Description=TeamPulse - WhatsApp Attendance Manager
After=network.target

[Service]
Type=simple
User=teampulse
Group=teampulse
WorkingDirectory=/home/teampulse/app
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

9. Service aktivieren und starten

sudo systemctl daemon-reload
sudo systemctl enable teampulse
sudo systemctl start teampulse

10. Status prüfen

sudo systemctl status teampulse
# Logs anschauen:
sudo journalctl -u teampulse -f

11. Firewall (optional)

sudo apt install -y ufw
sudo ufw allow ssh
sudo ufw allow 3000/tcp   # TeamPulse
sudo ufw allow 3000/tcp   # TeamPulse (anpassen falls anderer Port)
sudo ufw enable

12. WAHA Webhook konfigurieren

Damit Abstimmungen in TeamPulse ankommen, muss WAHA Webhooks an TeamPulse senden. Im WAHA-Dashboard unter Sessions → deine Session → Webhooks:

Feld	Wert
URL	http://<TeamPulse-IP>:3000/api/webhooks/waha
Events	message, poll.vote
Attempts	3
Delay seconds	2
Retry policy	constant
HMAC Key	(leer lassen)
Custom Headers	(leer lassen)

<TeamPulse-IP> durch die IP-Adresse des TeamPulse-Servers ersetzen. Wenn WAHA auf derselben Maschine läuft, localhost verwenden. Der Server hört auf 0.0.0.0, ist also von allen Interfaces erreichbar.

14. Update-Skript installieren

sudo cp /home/teampulse/app/update.sh /usr/local/bin/teampulse-update
sudo chmod +x /usr/local/bin/teampulse-update

Updates einspielen

# Normales Update (Code + Dependencies)
sudo teampulse-update

# Komplett-Reset (löscht DB + alle Daten, mit doppelter Bestätigung)
sudo teampulse-update --reset

Logs & Troubleshooting

# Live-Logs
sudo journalctl -u teampulse -f

# Service neustarten
sudo systemctl restart teampulse

# DB-Backup
sudo cp /home/teampulse/app/teampulse.db /home/teampulse/backup_$(date +%Y%m%d).db

# Passwort zurücksetzen (Notfall)
sudo -u teampulse bash -c '
  cd /home/teampulse/app
  node -e "
    const db = require(\"./db/database\");
    const bcrypt = require(\"bcrypt\");
    const hash = bcrypt.hashSync(\"admin\", 10);
    db.prepare(\"UPDATE users SET password_hash = ?, must_change_password = 1 WHERE username = ?\").run(hash, \"admin\");
    console.log(\"Passwort zurückgesetzt auf admin/admin\");
  "
'

---

Lokale Entwicklung

git clone https://github.com/niklask52t/TeamPulse.git
cd TeamPulse
npm install
cp .env.example .env
npm run dev

Lizenz

MIT

---

Last reviewed: 2026-04-11