zfx-public/teamvis-selfhost
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

TeamVis Self-Host-Bundle v0.31.0

Browse Source
This commit is contained in:
TeamVis Release
2026-06-25 16:38:31 +02:00
commit 717325742d
68 changed files with 3762 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
deploy/selfhost/README.md
+260
View File
@@ -0,0 +1,260 @@
# 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 |