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 Supabase | All-in-One | |
|---|---|---|
| Datenbank | Ihr bestehendes Supabase-Projekt (Cloud oder self-hosted) | wird als Container mitinstalliert |
| Aufwand | minimal — es läuft nur die App | etwas mehr RAM, dafür kein externes Setup |
| Passt, wenn | Sie schon Supabase nutzen | Sie 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):
# Docker + Compose-Plugincurl -fsSL https://get.docker.com | shsudo usermod -aG docker "$USER" # danach einmal aus-/einloggen
# Node 20 + git + opensslcurl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -sudo apt-get install -y nodejs git openssl
# Kontrolledocker --version && docker compose version && node --versionSchritt 2 — An der Registry anmelden
Mit den Zugangsdaten aus dem Onboarding (Benutzer teamvis-pull, Passwort = Ihr
Pull-Token):
docker login git.zfx.servicesSchritt 3 — Installer-Bundle holen
Das Bundle (Installer, Helfer-Skripte, Datenbank-Schema) ist öffentlich — kein Login nötig:
git clone https://git.zfx.services/zfx-public/teamvis-selfhost.gitcd teamvis-selfhostSchritt 4 — Installer ausführen
bash deploy/selfhost/install.shDer Installer fragt der Reihe nach:
- Kurzname der Instanz (z. B.
kunde) — für Verzeichnis und Compose-Projekt. - Domain der App (
team.ihre-organisation.de). - Admin-E-Mail und Name (der erste Backend-Login).
- Zielverzeichnis der Instanz (Vorgabe passt in der Regel).
- SMTP (optional — leer lassen ist ok; dann landen Login-Mails nur im
Log statt im Postfach; später in der
.envnachtragbar). - Datenbank-Modus →
2für All-in-One (oder1für eigene Supabase). - 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.ymlund 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
https://team.ihre-organisation.de/adminöffnen → mit Admin-E-Mail + Passwort anmelden (beim ersten Login wird ein neues Passwort gesetzt).- Branding (Logo, Farben, Impressum) im Backend hinterlegen.
- Mitarbeiter anlegen (einzeln oder per CSV-Import).
- 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):
cd teamvis-selfhostbash deploy/selfhost/update.shDas Skript arbeitet diese Schritte ab und bricht beim ersten Fehler ab:
- Datenbank-Sicherung (All-in-One): ein Dump als
backup-db-<Zeitstempel>.sqlim Instanz-Verzeichnis. - Bundle aktualisieren (
git pull): neue Datenbank-Migrationen und Skripte. - 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. - App aktualisieren: neues Image ziehen, Container neu starten. Steht in
der
.enveine feste ältere Versionsnummer, hebt das Skript sie auf die Version des Bundles (latestbleibtlatest).
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):
cp deploy/selfhost/backup.sh deploy/selfhost/restore.sh <instanz-verzeichnis>/Tägliche Sicherung per Cron (crontab -e des Benutzers, der Docker bedient):
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:
cd /pfad/zur/instanzbash restore.sh ~/backups/<instanz>/db-<datum>.dump ~/backups/<instanz>/storage-<datum>.tar.gzDas 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 mitTEAMVIS_UPDATE_CHECK=offin 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.