TeamVis Self-Hosting — Quickstart (von der nackten VM bis live)

Diese Anleitung führt von einer komplett frischen Linux-VM bis zur laufenden TeamVis-Instanz. Sie nutzt den Ein-Schritt-Installer deploy/selfhost/install.sh (Hintergrund & manuelle Varianten: deploy/selfhost/README.md, externe Supabase: docs/NEUKUNDE.md).

Zwei Betriebsarten zur Auswahl (fragt der Installer ab):

Modus 2 — alles mitinstallieren (empfohlen für „nur eine VM"): TeamVis und eine schlanke Supabase laufen als Container auf derselben VM, unter einer Domain. Kein externes Supabase nötig.
Modus 1 — eigene/bestehende Supabase: du hast schon ein Supabase-Projekt (Cloud oder self-hosted); es läuft nur die App.

Diese Anleitung beschreibt Modus 2 (der Komplettfall).

0. Voraussetzungen

Du brauchst vorab:

Was	Details
VM	Ubuntu 22.04+/Debian 12+, 2 GB RAM+ (Modus 2 ≈ 1–1,5 GB), ~10 GB Disk. Root- bzw. sudo-Zugang.
Domain	z. B. `team.kunde.de`, mit DNS-A-Record auf die öffentliche IP der VM. Caddy holt das TLS-Zertifikat dann automatisch.
Offene Ports	eingehend 80 und 443 (Let's Encrypt + Web).
Image-Pull-Token	ein Token für die Registry `git.zfx.services` — vom TeamVis-Anbieter. Nur fürs Container-Image. Das Installer-Bundle ist öffentlich (kein Token).

So ist die Auslieferung getrennt: Das Bundle (Installer + Migrationen, kein Quellcode) liegt in einem öffentlichen Repo und ist ohne Login klonbar. Nur das private Container-Image braucht den Pull-Token. Der App-Quellcode bleibt in jedem Fall unzugänglich. (Anbieter-Details: docs/DISTRIBUTION.md.)

1. Grundpakete installieren

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

# Docker + Compose-Plugin
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker "$USER"     # danach einmal aus-/einloggen (oder: newgrp docker)

# 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

2. An der Registry anmelden (Token)

Benutzer ist teamvis-pull, Passwort der Token vom Anbieter:

docker login git.zfx.services
# Benutzer: teamvis-pull   ·   Passwort: <Token>

3. Installer-Bundle holen

Das Bundle ist öffentlich — kein Login nötig:

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

(Enthält Installer, Helfer-Skripte und Migrationen — keinen App-Quellcode. Die App selbst kommt als fertiges Image aus der Registry, wird also nicht gebaut. Kein git? Stattdessen das Release-Tarball des Anbieters entpacken.)

4. Installer ausführen

bash deploy/selfhost/install.sh

Der Installer fragt der Reihe nach:

Kurzname der Instanz (z. B. kunde) — nur für Verzeichnis/Compose-Name.
Domain der App (team.kunde.de).
Image-Version (Default = aktuelle Version, einfach Enter).
Admin-E-Mail + Name (der erste Backend-Login).
Zielverzeichnis (Default: ./kunde).
SMTP (optional — leer lassen ist ok; dann landen Login-/Magic-Links nur im Container-Log statt im Postfach. Lässt sich später in der .env nachtragen).
Datenbank-Modus → hier 2 wählen.
Am Ende: Admin-Passwort (mind. 10 Zeichen, verdeckt).

Danach erledigt das Skript automatisch: Schlüssel/Secrets erzeugen, .env + docker-compose.yml + Caddyfile schreiben, Datenbank starten, Rollen-Bootstrap + Rechte, Schema einspielen, App + Caddy starten, ersten Admin anlegen. Dauer: wenige Minuten (Image-Download).

https://team.kunde.de/admin/login öffnen → mit Admin-E-Mail + Passwort anmelden (beim ersten Login wird ein neues Passwort gesetzt).
Admin → Branding: Firmenname, Logo, Farben, Impressum.
Admin → Mitarbeiter: erste Karte anlegen (oder CSV-Import).
Admin → Funktionen: weitere Module gestaffelt freischalten — eine frische Instanz startet bewusst nur mit den Visitenkarten.

Smoke-Test:

https://team.kunde.de/<slug> zeigt eine Karte (ohne Login)
vCard-Download …/api/vcard/<slug> liefert .vcf
Foto-Upload im Backend erscheint auf der Karte
(mit SMTP) Self-Service-Portal verschickt einen Login-Code

6. Betrieb

Updates: Image-Tag in kunde/docker-compose.yml bumpen, bei Minor-Sprüngen vorher die neue(n) Migration(en) einspielen → docker compose pull && up -d. Details: docs/NEUKUNDE.md §7.
Backup (wichtig, jetzt liegt die DB bei dir): das Postgres-Volume (db-data) und kunde/volumes/storage sichern. Die .env gehört in einen Passwort-Safe (enthält alle Secrets), nicht ins Backup-Repo.

Wenn etwas klemmt

docker compose pull schlägt fehl → docker login git.zfx.services nachholen.
TLS kommt nicht → DNS-A-Record + offene Ports 80/443 prüfen (Caddy braucht beide für Let's Encrypt).
Logs ansehen: cd kunde && docker compose logs -f app bzw. caddy.

5.1 KiB Raw Permalink Blame History Unescape Escape