Zum Inhalt springen

Self-Hosting

TeamVis lässt sich vollständig auf eigener Infrastruktur betreiben — auf einem Server im eigenen Rechenzentrum oder bei einem Hoster Ihrer Wahl. Alle Daten (Mitarbeiter, Fotos, Protokolle) bleiben damit unter Ihrer Kontrolle. Das ist besonders für Kommunen und Versorger relevant, die Datensouveränität und DSGVO-Konformität sicherstellen müssen.

Diese Anleitung führt von einer frischen Linux-VM bis zur laufenden Instanz.

Zwei Betriebsarten

Beim Einrichten wählen Sie, woher die Datenbank kommt:

Eigene SupabaseAll-in-One
DatenbankIhr bestehendes Supabase-Projekt (Cloud oder self-hosted)wird als Container mitinstalliert
Aufwandminimal — es läuft nur die Appetwas mehr RAM, dafür kein externes Setup
Passt, wennSie schon Supabase nutzenSie nur „eine VM” haben und alles auf einmal wollen

Beide laufen aus demselben Container-Image — kein eigener Build pro Kunde, keine Code-Anpassung. Die folgende Anleitung beschreibt die All-in-One-Variante (der Komplettfall); für „eigene Supabase” wählen Sie beim Installer einfach den anderen Modus.

Voraussetzungen

  • Eine Linux-VM (Ubuntu 22.04+/Debian 12+), für All-in-One ca. 2 GB RAM, ~10 GB Disk, root- bzw. sudo-Zugang.
  • Eine Domain (z. B. team.ihre-organisation.de) mit DNS-A-Record auf die öffentliche IP der VM. Das TLS-Zertifikat holt sich der mitgelieferte Webserver (Caddy) automatisch.
  • Eingehende Ports 80 und 443 offen.
  • Docker auf der VM.
  • Zugang vom TeamVis-Team: ein Image-Pull-Token für die Registry. Damit ziehen Sie das Container-Image; das Installer-Bundle ist öffentlich. Den Quellcode benötigen Sie nicht — die App kommt als fertiges Image. Den Token fordern Sie per E-Mail an hello@zfx.services an.

Schritt 1 — Grundpakete installieren

Auf der frischen VM (als root oder mit sudo):

Terminal-Fenster
# Docker + Compose-Plugin
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker "$USER" # danach einmal aus-/einloggen
# Node 20 + git + openssl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs git openssl
# Kontrolle
docker --version && docker compose version && node --version

Schritt 2 — An der Registry anmelden

Mit den Zugangsdaten aus dem Onboarding (Benutzer teamvis-pull, Passwort = Ihr Pull-Token):

Terminal-Fenster
docker login git.zfx.services

Schritt 3 — Installer-Bundle holen

Das Bundle (Installer, Helfer-Skripte, Datenbank-Schema) ist öffentlich — kein Login nötig:

Terminal-Fenster
git clone https://git.zfx.services/zfx-public/teamvis-selfhost.git
cd teamvis-selfhost

Schritt 4 — Installer ausführen

Terminal-Fenster
bash deploy/selfhost/install.sh

Der Installer fragt der Reihe nach:

  1. Kurzname der Instanz (z. B. kunde) — für Verzeichnis und Compose-Projekt.
  2. Domain der App (team.ihre-organisation.de).
  3. Admin-E-Mail und Name (der erste Backend-Login).
  4. Zielverzeichnis der Instanz (Vorgabe passt in der Regel).
  5. SMTP (optional — leer lassen ist ok; dann landen Login-Mails nur im Log statt im Postfach; später in der .env nachtragbar).
  6. Datenbank-Modus → 2 für All-in-One (oder 1 für eigene Supabase).
  7. Zum Schluss das Admin-Passwort.

Das Container-Image wird automatisch in der aktuellen Version (latest) gezogen — eine Versionsnummer müssen Sie nicht kennen.

Danach läuft alles automatisch (siehe nächster Abschnitt). Nach wenigen Minuten ist die Instanz erreichbar.

Was der Installer automatisch erledigt

  • erzeugt alle Schlüssel/Secrets (Datenbank-Passwort, Session-Secret, API-Keys),
  • schreibt .env, docker-compose.yml und die Webserver-Konfiguration,
  • startet (im All-in-One-Modus) Datenbank + Storage + App + Webserver,
  • spielt das vollständige Datenbank-Schema ein,
  • legt den ersten Administrator an.

Schritt 5 — Erster Login & Einrichtung

  1. https://team.ihre-organisation.de/admin öffnen → mit Admin-E-Mail + Passwort anmelden (beim ersten Login wird ein neues Passwort gesetzt).
  2. Branding (Logo, Farben, Impressum) im Backend hinterlegen.
  3. Mitarbeiter anlegen (einzeln oder per CSV-Import).
  4. Funktionen freischalten — eine frische Instanz startet bewusst nur mit den Visitenkarten; weitere Module aktivieren Sie nach Bedarf gestaffelt.

Abnahme-Check

  • Öffentliche Karte …/<name> lädt ohne Login.
  • vCard-Download …/api/vcard/<name> liefert eine .vcf.
  • Foto-Upload im Backend erscheint auf der Karte.
  • (mit SMTP) Self-Service-Portal verschickt einen Login-Code.

Updates

Aktualisieren Sie in einem Schritt — im Bundle-Verzeichnis (dort, wo Sie git clone ausgeführt haben):

Terminal-Fenster
cd teamvis-selfhost
bash deploy/selfhost/update.sh

Das Skript arbeitet diese Schritte ab und bricht beim ersten Fehler ab:

  1. Datenbank-Sicherung (All-in-One): ein Dump als backup-db-<Zeitstempel>.sql im Instanz-Verzeichnis.
  2. Bundle aktualisieren (git pull): neue Datenbank-Migrationen und Skripte.
  3. Fehlende Migrationen einspielen. Welche Migrationen eine Instanz schon hat, steht in der Datenbank selbst (Tabelle teamvis_schema_migrations). Jede Migration läuft zusammen mit ihrem Eintrag in einer Transaktion — scheitert sie, wird sie vollständig zurückgerollt, die App bleibt auf dem alten Stand, und der nächste Lauf versucht genau diese Migration erneut.
  4. App aktualisieren: neues Image ziehen, Container neu starten. Steht in der .env eine feste ältere Versionsnummer, hebt das Skript sie auf die Version des Bundles (latest bleibt latest).

Nach dem Update prüfen: https://team.ihre-organisation.de/api/health antwortet mit {"ok":true,…}, eine öffentliche Karte lädt, der Admin-Login funktioniert. Bei Problemen hilft das Log der App: docker compose logs -f app im Instanz-Verzeichnis.

Zurück auf die vorige Version: In der .env des Instanz-Verzeichnisses TEAMVIS_VERSION auf die vorige Versionsnummer setzen (statt latest) und docker compose up -d app ausführen. Migrationen sind immer nur ergänzend — die ältere App läuft auch mit dem neueren Schema.

Sicherung und Wiederherstellung

Im All-in-One-Modus liegen Datenbank und Fotos auf Ihrer VM — die Sicherung liegt damit bei Ihnen. Das Bundle bringt zwei Skripte mit; kopieren Sie beide einmalig in das Instanz-Verzeichnis (neben docker-compose.yml):

Terminal-Fenster
cp deploy/selfhost/backup.sh deploy/selfhost/restore.sh <instanz-verzeichnis>/

Tägliche Sicherung per Cron (crontab -e des Benutzers, der Docker bedient):

Terminal-Fenster
15 3 * * * /bin/bash /pfad/zur/instanz/backup.sh >> $HOME/backups/<instanz>/backup.log 2>&1
  • Gesichert werden die Datenbank (TeamVis-Daten und Speicher-Verwaltung) und alle hochgeladenen Dateien (Fotos, Logos) — nach $HOME/backups/<instanz>, nur für Sie lesbar, 30 Tage aufbewahrt.
  • Das Skript prüft jede Sicherung auf Vollständigkeit. Optional meldet es jeden erfolgreichen Lauf an einen Uptime-Monitor (z. B. einen Push-Monitor in Uptime Kuma): Zeile PUSH_URL=… in $HOME/backups/<instanz>/push.env.
  • Nicht gesichert wird die .env — sie enthält alle Schlüssel. Bewahren Sie sie in einem Passwort-Safe auf; ohne sie passt eine Sicherung nicht mehr zur Instanz.
  • Die Sicherungen liegen zunächst auf derselben VM. Kopieren Sie sie regelmäßig an einen zweiten Ort. Ein VM-Snapshot allein ersetzt das nicht: Er erfasst die laufende Datenbank nur im Zustand eines Stromausfalls.

Wiederherstellen — in eine leere Instanz (neue VM oder nach Datenverlust), mit docker-compose.yml und der .env aus dem Passwort-Safe im Instanz-Verzeichnis:

Terminal-Fenster
cd /pfad/zur/instanz
bash restore.sh ~/backups/<instanz>/db-<datum>.dump ~/backups/<instanz>/storage-<datum>.tar.gz

Das Skript startet die Datenbank, stellt Daten und Dateien wieder her und startet alle Dienste. Es bricht ab, wenn die Datenbank schon TeamVis-Daten enthält — es überschreibt also nie versehentlich eine laufende Instanz.

Betrieb

Sonst liegt beim Self-Hosting in Ihrer Hand:

  • Erreichbarkeit von Domain und Server. Für ein Monitoring eignet sich /api/health (antwortet ohne Anmeldung mit {"ok":true,…}).
  • Updates des Betriebssystems und von Docker auf der VM.
  • Update-Hinweis: Ab Version 0.57 zeigt der Admin-Bereich ein Banner, wenn eine neuere Version vorliegt (bei Sicherheits-Releases rot). Eingespielt wird weiterhin mit update.sh — bewusst nicht per Klick in der Web-Oberfläche, denn dafür bräuchte die App Vollzugriff auf Docker und damit auf Ihren Server. Abschalten mit TEAMVIS_UPDATE_CHECK=off in der .env (siehe DSGVO & AVV).

Datenschutz

Self-Hosting heißt: personenbezogene Daten verlassen Ihre Infrastruktur nicht (außer optionalem Mailversand). Welche Daten TeamVis verarbeitet und welche Verträge nötig sind, steht unter DSGVO & AVV.


Self-Hosting gewünscht? Wir stellen Image-Zugang und das Installations-Bundle bereit und begleiten die Erstinstallation. Sprechen Sie uns an.