# 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). |
| **Zugangs-Token** | ein **Token** für `git.zoesch.de` — **vom TeamVis-Anbieter**. Damit ziehst du das Container-Image **und** das Installer-Bundle. **Kein** Quellcode-Zugang. |

> So ist die Auslieferung getrennt: Mit dem Token bekommst du nur das **Bundle**
> (Installer + Migrationen, kein Quellcode) und das **Container-Image** — der
> eigentliche App-Quellcode bleibt unzugänglich. Ein und derselbe Token (Benutzer
> `teamvis-pull`) deckt beides ab. (Anbieter-Details: `docs/DISTRIBUTION.md`.)

---

## 1. Grundpakete installieren

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

```bash
# 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:

```bash
docker login git.zoesch.de
# Benutzer: teamvis-pull   ·   Passwort: <Token>
```

---

## 3. Installer-Bundle holen

Mit demselben Token (im Klon-Link):

```bash
git clone https://teamvis-pull:<Token>@git.zoesch.de/zfx-services/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
bash deploy/selfhost/install.sh
```

Der Installer fragt der Reihe nach:

1. **Kurzname** der Instanz (z. B. `kunde`) — nur für Verzeichnis/Compose-Name.
2. **Domain** der App (`team.kunde.de`).
3. **Image-Version** (Default = aktuelle Version, einfach Enter).
4. **Admin-E-Mail** + **Name** (der erste Backend-Login).
5. **Zielverzeichnis** (Default: `./kunde`).
6. **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).
7. **Datenbank-Modus** → hier **`2`** wählen.
8. 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).

---

## 5. Erster Login & Abnahme

1. `https://team.kunde.de/admin/login` öffnen → mit Admin-E-Mail + Passwort
   anmelden (beim ersten Login wird ein neues Passwort gesetzt).
2. **Admin → Branding**: Firmenname, Logo, Farben, Impressum.
3. **Admin → Mitarbeiter**: erste Karte anlegen (oder CSV-Import).
4. **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.zoesch.de` 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`.