# TeamVis — All-in-One Self-Hosting (App + Supabase)

## Schnellstart: `install.sh` (ein Schritt)

Für eine neue Instanz gibt es einen interaktiven Installer, der alles in einem
Rutsch erledigt und beim Start fragt, woher die Datenbank kommt:

```bash
bash deploy/selfhost/install.sh
```

- **Modus 1 — bestehende/eigene Supabase** (Cloud oder self-hosted): es läuft nur
  die App (+ optional Caddy/TLS). Entspricht `docs/NEUKUNDE.md`, nur automatisiert.
- **Modus 2 — alles mitinstallieren:** schlanker Supabase-Stack als Container
  (Postgres + PostgREST + Storage) + App + Caddy, **Single-Domain** (App,
  `/rest/v1`, `/storage/v1` alle unter `https://team.kunde.de` — eine Domain, ein
  Zertifikat). Kein vorab eingerichtetes Supabase nötig.

Das Skript erzeugt Schlüssel/Secrets, schreibt `.env` + `docker-compose.yml` +
`Caddyfile`, spielt das Schema ein, macht in Modus 2 den **Rollen-Bootstrap +
Grants automatisch** (der manuelle Block unter „Variante B" entfällt damit) und
legt den ersten Admin an. Voraussetzungen: docker + compose v2, node 20+,
openssl, DNS auf den Host, Ports 80/443 frei, `docker login git.zoesch.de`.

Variablen lassen sich vorab per ENV setzen (überspringt die Abfrage), z. B.
`APP_DOMAIN=team.kunde.de ADMIN_EMAIL=chef@kunde.de MODE=2 bash deploy/selfhost/install.sh`.

> Die folgenden Abschnitte beschreiben die **manuellen** Varianten (zum
> Verständnis / für Sonderfälle). Für den Normalfall reicht `install.sh`.

---

## Manuell (Hintergrund)

**Option/Status:** ausgearbeitet **und end-to-end auf zfx-vps getestet**
(Lean-Datenebene). Karte, vCard, Storage-Upload/-Abruf, anon-RLS und der
Spalten-Revoke (0045) laufen gegen self-hosted Postgres + PostgREST +
Storage. Der Testlauf hat drei Bootstrap-Lücken aufgedeckt — alle gelöst,
siehe [Befunde](#befunde-aus-dem-testlauf-2026-06-07).

Diese Variante bringt mit **einem Compose-Stack** sowohl die TeamVis-App als
auch eine eigene Supabase-Instanz hoch — der Kunde braucht **kein** vorab
eingerichtetes Supabase (weder Cloud noch self-hosted). Gegensatz zum
Standard-Onboarding (`docs/NEUKUNDE.md`), das eine **externe** Supabase
voraussetzt.

---

## Was TeamVis von Supabase wirklich braucht

Analyse des Codes (`lib/supabase-server.ts`, alle `*.actions.ts`):

| Supabase-Komponente | Von TeamVis genutzt? | Wofür |
|---|---|---|
| **Postgres** | ✅ Pflicht | alle Daten |
| **PostgREST** (`/rest/v1`) | ✅ Pflicht | sämtliche DB-Reads/Writes (`@supabase/supabase-js`) |
| **Storage** (`/storage/v1`) | ✅ Pflicht | Buckets `employee-photos` + Branding, **öffentliche** URLs (`getPublicUrl`) |
| GoTrue / Auth (`/auth/v1`) | ❌ | TeamVis nutzt **keine** Supabase-Auth (Admin = bcrypt+iron-session, Portal = Magic-Link) |
| Realtime | ❌ | — |
| imgproxy (Bild-Transforms) | ❌ | Karten nutzen `next/image`, keine Storage-Transforms |
| Studio / Meta | ⚪ optional | bequemes DB-/SQL-UI für den Betreiber |

**Folge:** technisch genügen **Postgres + PostgREST + Storage + ein
Pfad-Router**. Auth/Realtime/imgproxy sind verzichtbar.

---

## Architektur

```
                       ┌─────────────── Caddy (Auto-HTTPS) ───────────────┐
   Browser ── 443 ───▶ │  team.kunde.de      → teamvis:3000               │
   (Karten, Admin)     │  supabase.kunde.de  → kong:8000                  │
                       └───────────────┬──────────────────┬───────────────┘
                                       │                  │
                            ┌──────────▼─────┐   ┌────────▼─────────────────┐
                            │ teamvis (App)  │   │ Supabase-Stack (kong →    │
                            │ Next.js :3000  │──▶│ rest + storage + db …)    │
                            └────────────────┘   └──────────────────────────┘
```

- Die **Foto-URLs der Karten zeigen auf `supabase.kunde.de`** (öffentliches
  `getPublicUrl`). Deshalb muss diese Domain **öffentlich per HTTPS**
  erreichbar sein — `next/image` erlaubt nur `https` auf
  `/storage/v1/object/public/**` (siehe `next.config.ts`, bereits
  vorbereitet: jeder https-Host auf diesem Pfad ist zulässig).
- Das **App-Image ist unverändert** das SaaS-Image — alle Supabase-Werte
  kommen zur Laufzeit aus ENV (`lib/runtime-env.ts`). Kein Rebuild pro Kunde.

---

## Variante A — offizieller Supabase-Stack + Override (empfohlen)

Lehnt sich an den **getesteten** `supabase/docker`-Stack an und legt TeamVis
per Override darüber. Vorteil: korrekte, aufeinander abgestimmte Image-Pins
(Postgres/PostgREST/Storage/Kong) ohne eigenes Versions-Risiko.

### Schritte

```bash
# 0) Voraussetzungen auf dem Server: docker + compose, node 20+, openssl,
#    DNS für team.kunde.de und supabase.kunde.de auf diese IP, Ports 80/443 frei.

# 1) Supabase-Stack holen
git clone --depth 1 https://github.com/supabase/supabase
cd supabase/docker
cp .env.example .env

# 2) TeamVis-Override + Caddy + Zusatz-ENV hineinlegen
REPO=/pfad/zum/team-stwhas
cp $REPO/deploy/selfhost/docker-compose.override.yml .
cp $REPO/deploy/selfhost/Caddyfile.example ./Caddyfile      # Domains anpassen!
cat $REPO/deploy/selfhost/.env.teamvis.example >> .env       # Werte ausfüllen

# 3) In .env setzen/ersetzen:
#    POSTGRES_PASSWORD           → starkes Passwort
#    SITE_URL=https://team.kunde.de
#    SUPABASE_PUBLIC_URL=https://supabase.kunde.de
#    API_EXTERNAL_URL=https://supabase.kunde.de
#    SESSION_SECRET              → openssl rand -base64 48
#    (JWT_SECRET/ANON_KEY/SERVICE_ROLE_KEY macht bootstrap.sh in Schritt 4)

# 4) Bootstrap: Keys + Stack + Schema + erster Admin
cp $REPO/deploy/selfhost/bootstrap.sh .
TEAMVIS_REPO=$REPO ADMIN_EMAIL=chef@kunde.de bash bootstrap.sh
```

`bootstrap.sh` erledigt: Schlüssel erzeugen (ersetzt die unsicheren
Demo-Keys), `docker compose up -d`, auf gesunde DB warten,
TeamVis-Schema (Migrations-Bündel) einspielen, ersten Admin anlegen.

### Optional schlanker (Footprint senken)

Der Volldownload startet ~10 Container. Nicht genutzte abschalten —
in der `.env` bzw. per `docker compose` weglassen: **studio, auth
(GoTrue), realtime, imgproxy, analytics/vector, meta, supavisor/pooler**.
Übrig bleiben **db, rest, storage, kong** (+ teamvis, caddy). Das ist die
empfohlene Ziel-Konfiguration für eine Einzel-Mandanten-Appliance —
sollte aber im selben Probelauf mitgetestet werden (Kong-Routen + Storage
hängen minimal an Auth-Annahmen).

---

## Variante B — komplett schlank (eigener Mini-Stack)

Nur `supabase/postgres:15.8.1.085` + `postgrest/postgrest:v14.12` +
`supabase/storage-api:v1.60.4` + Caddy als Pfad-Router (kein Kong, kein
GoTrue/Realtime/imgproxy). **Genau das wurde getestet** (siehe Befunde) und
läuft — braucht aber einen Rollen-Bootstrap, den der offizielle Stack
automatisch macht. Caddy-Router statt Kong:

```caddyfile
:8000 {
	handle_path /rest/v1/*    { reverse_proxy rest:3000 }
	handle_path /storage/v1/* { reverse_proxy storage:5000 }
}
```

**Pflicht-Bootstrap nach dem ersten Start** (einmalig, als `supabase_admin`,
Passwort = `POSTGRES_PASSWORD`):

```sql
-- 1) Rollen-Passwörter (das Image setzt nur supabase_admin auf POSTGRES_PASSWORD)
alter role authenticator          with login password '<POSTGRES_PASSWORD>';
alter role supabase_storage_admin with login password '<POSTGRES_PASSWORD>';
alter role supabase_auth_admin    with login password '<POSTGRES_PASSWORD>';

-- 2) service_role-Rechte (auf echtem Supabase automatisch vorhanden)
alter role service_role bypassrls;
grant all on all tables    in schema public to service_role;
grant all on all sequences in schema public to service_role;
grant all on all routines  in schema public to service_role;
alter default privileges in schema public grant all on tables    to service_role;
alter default privileges in schema public grant all on sequences to service_role;
```

Reihenfolge: Passwörter (1) **vor** dem ersten Start von `rest`/`storage`,
die Grants (2) **nach** dem Schema-Load. Wegen dieses Mehraufwands ist für
die *erste* Kundeninstallation **Variante A empfohlen** (dort entfällt der
ganze Block).

---

## Stolpersteine (wichtig)

1. **`SUPABASE_PUBLIC_URL` muss öffentlich + HTTPS sein** — sie steckt in den
   Foto-URLs der Karten. Interner Hostname (`http://kong:8000`) funktioniert
   **nicht** für die Bildanzeige.
2. **SMTP-Kollision:** der Supabase-Stack belegt `SMTP_*` selbst (GoTrue).
   Die App liest deshalb `TEAMVIS_SMTP_*` (siehe Override) — nicht
   vermischen.
3. **Reihenfolge:** Schema erst einspielen, wenn Storage einmal gestartet ist
   (Migration `0044` legt den Bucket in `storage.buckets` an). `bootstrap.sh`
   wartet darauf.
4. **Keys sind JWTs:** `ANON_KEY`/`SERVICE_ROLE_KEY` sind mit `JWT_SECRET`
   signierte Tokens (`gen-keys.mjs`). Wird `JWT_SECRET` geändert, müssen beide
   Keys neu erzeugt werden.
5. **Backups:** jetzt liegt die DB beim Kunden. Postgres-Volume + Storage-
   Volume sichern (`pg_dump` + `volumes/storage`). Beim externen Supabase war
   das deren Sache.
6. **Modul-Rollout:** frische Instanz startet minimal (nur Visitenkarten).
   Danach unter **Admin → Funktionen** gestaffelt freischalten
   (siehe `docs/NEUKUNDE.md` §5a).

---

## Footprint (grob)

| | Container | RAM (Daumenregel) |
|---|---|---|
| Variante A voll | ~12 | ~2–3 GB |
| Variante A schlank | 6 (db, rest, storage, kong, teamvis, caddy) | ~1–1.5 GB |
| Externe Supabase (NEUKUNDE.md) | 2 (teamvis, caddy) | ~0.4 GB |

---

## Befunde aus dem Testlauf (2026-06-07)

Lean-Stack (db + rest + storage + Caddy-Router + app) auf zfx-vps hochgezogen,
nur an localhost gebunden. Drei Bootstrap-Lücken gefunden:

1. **Basis-Schema fehlte** — die Migrationen legen `employees`/`admin_users`
   nicht an (nur additive `add column if not exists`). `bundle-migrations`
   bootstrappt eine leere DB also nicht. **Gelöst:** neue Migration
   `supabase/migrations/0000_base_schema.sql` (idempotent, auf
   Bestandsinstanzen ein No-Op). Betrifft auch den `NEUKUNDE.md`-Weg.
2. **Rollen-Passwörter** — `supabase/postgres` setzt nur `supabase_admin` auf
   `POSTGRES_PASSWORD`; `authenticator`/`supabase_storage_admin` brauchen es
   manuell (Variante B). Variante A erledigt das.
3. **service_role-Grants** — frisch erzeugte Tabellen geben `service_role`
   keine Rechte; auf echtem Supabase passiert das automatisch. Grants +
   `bypassrls` nötig (Variante B). Variante A erledigt das.

**Nach den Fixes verifiziert (alles grün):**

| Test | Ergebnis |
|---|---|
| Schema-Bündel (mit 0000) auf leerer DB | 0 Fehler, 23 Tabellen |
| `/api/health` | `ok:true`, `db.ok:true` |
| Öffentliche Karte `/<slug>` | HTTP 200 |
| vCard `/api/vcard/<slug>` | HTTP 200 |
| anon-REST: aktive MA lesen | ✅ (RLS erlaubt) |
| anon-REST: Geheim-Spalte `phone_mobile` | `permission denied` ✅ (0045 greift) |
| service_role-REST | ✅ (nach Grants) |
| Storage-Upload + öffentlicher Abruf | HTTP 200, Inhalt korrekt |

**Noch offen für „voll kundenreif":** ein Lauf von **Variante A** (offizieller
Stack — bestätigt, dass Punkt 2+3 dort automatisch wegfallen) sowie ein Test
des Admin-Logins + Portal-Magic-Links über die echten HTTPS-Domains (Caddy/TLS
war im localhost-Test nicht aktiv).

## Dateien hier

| Datei | Zweck |
|---|---|
| `docker-compose.override.yml` | TeamVis-App + Caddy über dem Supabase-Stack |
| `.env.teamvis.example` | Zusatz-ENV für die Supabase-.env |
| `Caddyfile.example` | TLS-Ingress (App- + Supabase-Domain) |
| `gen-keys.mjs` | erzeugt JWT_SECRET + ANON_KEY + SERVICE_ROLE_KEY |
| `bootstrap.sh` | Keys + Stack + Schema + Admin in einem Rutsch |